Skip to content

Commit 27038e9

Browse files
KuznetsovRomanKuznetsovRoman
committed
docs: describe local browsers
1 parent d655633 commit 27038e9

File tree

11 files changed

+737
-115
lines changed

11 files changed

+737
-115
lines changed

‎blog/local-browsers.mdx

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Запуск на локальных браузерах
3+
slug: local-browsers-intro
4+
hide_table_of_contents: false
5+
date: 2024-12-19T14:00
6+
---
7+
8+
import Admonition from "@theme/Admonition";
9+
import localBrowsersExampleUrl from "/video/blog/local-browsers/local-browsers-example.mp4";
10+
11+
В Testplane добавлена возможность автоматической загрузки браузеров и драйверов для последующего локального запуска.
12+
13+
<!-- truncate -->
14+
15+
Раньше Testplane с протоколом автоматизации webdriver можно было запустить локально только с вручную запущенным [selenium-standalone](https://github.com/webdriverio/selenium-standalone). Теперь достаточно указать указать `gridUrl: "local"` в [Конфиге Testplane](/docs/v8/command-line) или запустить тесты с [CLI-опцией](/docs/v8/command-line) `--local`. В таком случае перед запуском тестов при необходимости будут загружены соответствующие браузеры и вебдрайверы к ним, которые также будут запущены для дальнейшего использования в этих тестах.
16+
17+
Загрузить браузеры и вебдрайверы к ним можно и отдельно, с помощью команды [install-deps](/docs/v8/command-line#install-deps).
18+
19+
Пример запуска тестов на локальном браузере с webdriver протоколом автоматизации:
20+
21+
<video src={localBrowsersExampleUrl} width="100%" controls="controls" autoplay="autoplay">
22+
Тег video не поддерживается вашим браузером.
23+
<a href="video/blog/local-browsers/local-browsers-example.mp4">Скачайте видео</a>.
24+
</video>
25+
26+
### Как использовать?
27+
28+
Узнайте больше об этом в нашей документации [Как запустить Testplane в локальном браузере](/docs/v8/guides/local-browsers).

‎blog/vscode-extension.mdx

+2-3
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import Admonition from "@theme/Admonition";
99
import runTestsFromSidebarVideoUrl from "/video/blog/vscode-extension/run-tests-from-sidebar.mp4";
1010
import runTestsFromEditorVideoUrl from "/video/blog/vscode-extension/run-tests-from-editor.mp4";
1111

12-
Для Testplane реализовали расширение для [VS Code][vscode], с помощью которого можно настраивать Testplane с нуля, запускать тесты и удобно работать с <a href="/ru/docs/v8/command-line/#testplane-repl">REPL режимом</a>.
12+
Для Testplane реализовали расширение для <a href="https://code.visualstudio.com/">VS Code</a>, с помощью которого можно настраивать Testplane с нуля, запускать тесты и удобно работать с <a href="/ru/docs/v8/command-line#testplane-repl">REPL режимом</a>.
1313

1414
<!-- truncate -->
1515

@@ -80,7 +80,7 @@ Install Testplane
8080

8181
#### С настройкой `REPL`
8282

83-
При клике в чекбокс `Enable REPL` и последующем запуске теста (в REPL режиме можно одновременно запустить только один тест) он будет запущен в специальном REPL режиме. Подробнее про этот режим можно прочитать <a href="/ru/docs/v8/command-line/#testplane-repl">здесь</a>.
83+
При клике в чекбокс `Enable REPL` и последующем запуске теста (в REPL режиме можно одновременно запустить только один тест) он будет запущен в специальном REPL режиме. Подробнее про этот режим можно прочитать <a href="/ru/docs/v8/command-line#testplane-repl">здесь</a>.
8484

8585
![Включение опции REPL](/img/blog/vscode-extension/enable-repl.png)
8686

@@ -125,6 +125,5 @@ Install Testplane
125125

126126
Устанавливайте расширение Testplane для VS Code и приходите с фидбеком. В случае обнаружения проблем приходите в [issue github](https://github.com/gemini-testing/testplane/issues) — мы вам обязательно поможем!
127127

128-
[vscode]: https://code.visualstudio.com/
129128
[vscode-testplane-marketplace]: https://marketplace.visualstudio.com/items?itemName=gemini-testing.vscode-testplane
130129
[mocha-bdd-interface]: https://mochajs.org/#bdd

‎docs/command-line/index.mdx

+42
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Main command to run tests.
2929
--repl-before-test [type] open repl interface before test run (default: false)
3030
--repl-on-fail [type] open repl interface on test fail only (default: false)
3131
--devtools switches the browser to the devtools mode with using CDP protocol
32+
--local use automatically downloaded browsers and drivers, provided by Testplane
3233
-h, --help output usage information
3334
```
3435
@@ -463,6 +464,47 @@ For example, [html-reporter][html-reporter] adds `gui` command.
463464
testplane list-tests --help
464465
```
465466
467+
## `install-deps` command {#install-deps}
468+
469+
This command is a part of the guide [How to launch Testplane in the local browser](/docs/v8/guides/local-browsers).
470+
471+
Use the `install-deps` command to download all browsers, specified in [Testplane config](/docs/v8/config/main).
472+
473+
If this command is launched on supported ubuntu version, all missing necessary ubuntu packages would be downloaded too.
474+
475+
### Usage {#usage}
476+
477+
```bash
478+
npx testplane install-deps
479+
```
480+
481+
### Command arguments {#arguments}
482+
483+
You can also specify, which browsers are need to be downloaded.
484+
485+
For example, if you have browsers "chrome-dark", "firefox-dark" described in <a href="/docs/v8/config/main">Testplane config</a>, you can use the following command to only download these two browsers:
486+
487+
```bash
488+
npx testplane install-deps chrome-dark firefox-dark
489+
```
490+
491+
Using browser names with versions in a format like `<browserName>@<browserVersion>` is also supported:
492+
493+
```bash
494+
npx testplane install-deps chrome@130 firefox@104
495+
```
496+
497+
### Installation directory {#directory}
498+
499+
By default, browsers and drivers are downloaded to ".testplane" directory at home directory.
500+
501+
You can specify other path by setting `TESTPLANE_BROWSERS_PATH` env variable:
502+
503+
```bash
504+
TESTPLANE_BROWSERS_PATH=./node_modules/.testplane npx testplane install-deps
505+
TESTPLANE_BROWSERS_PATH=~/.testplane npx testplane install-deps
506+
```
507+
466508
## Overriding settings {#overriding-settings}
467509
468510
All options can be overridden via command-line flags or environment variables with the following priorities, by descending:

‎docs/config/browsers.mdx

+5
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,11 @@ Grid URL (the address where ChromeDriver/Selenium Standalone/Sauce Labs/etc. lis
134134

135135
Default: `http://localhost:4444/wd/hub`.
136136

137+
<Admonition type="info">
138+
You can also use value `"local"` in order to use local browsers, managed by Testplane. Read more
139+
in guide [How to launch Testplane in the local browser](/docs/v8/guides/local-browsers).
140+
</Admonition>
141+
137142
### baseUrl {#base_url}
138143

139144
Base URL of the service being tested. Allows for more convenient use of the `browser.url` commands:

‎docs/guides/local-browsers.mdx

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
import Admonition from "@theme/Admonition";
2+
3+
# How to Run Testplane in a Local Browser
4+
5+
## Introduction
6+
7+
Testplane can automatically download browsers in accordance with your [Testplane Config](/docs/v8/config/main).
8+
9+
Additionally, if Testplane is used on a supported version of Ubuntu, the necessary deb packages for running browsers will also be downloaded in a similar manner.
10+
11+
Running tests on a local browser can help with troubleshooting a problem that occurs when running on a remote grid, but using local browsers for screenshot testing is not recommended, as screenshots will vary depending on the operating system version.
12+
13+
## Installing dependencies
14+
15+
In a project with Testplane, you can execute the command `npx testplane install-deps`. This command will download the necessary browsers (`chrome` and `firefox`) and their web drivers (`chrome`, `firefox`, and `edge`).
16+
17+
You can also download only the necessary browsers described in the config. For example, if the browser `chrome-dark` is described, you can download only this one with the command `npm testplane install-deps chrome-dark'.
18+
19+
You can read more about this command on the respective page: [install-deps](/docs/v8/command-line#install-deps)
20+
21+
## Running tests
22+
23+
You can run tests on local browsers using the [CLI option](/docs/v8/command-line) `--local`, or with [gridUrl](/docs/v8/config/browsers/#grid_url): "local" in the [Testplane config](/docs/v8/config/main). For example:
24+
25+
```bash
26+
npx testplane --local
27+
```
28+
29+
This way, the corresponding web driver processes for supported browsers will be automatically started, and Testplane will use these locally launched drivers with locally downloaded browsers.
30+
31+
If necessary, browsers will be downloaded before the test run, so running the `install-deps` command separately is not mandatory, especially if you want to quickly run a test in just one browser.
32+
33+
## Debugging tests
34+
35+
When `debug` is enabled in the config, web driver logs with a prefix will be output to stdout/stderr:
36+
37+
```typescript
38+
export default {
39+
// ... other Testplane settings
40+
system: {
41+
debug: true,
42+
},
43+
};
44+
```
45+
46+
To reduce excessive `webdriverio` logs, you can set the desired level for the `WDIO_LOG_LEVEL` environment variable.
47+
48+
For example, here's how a launch would look with debugging enabled via an environment variable, `webdriverio` logging level set to `error` in a local browser with browserId `chrome` in the config:
49+
50+
```bash
51+
testplane_system_debug=true WDIO_LOG_LEVEL=error npx testplane --local -b chrome
52+
```
53+
54+
And the web driver logs will look something like this:
55+
56+
```plaintext
57+
$ testplane_system_debug=true WDIO_LOG_LEVEL=error npx testplane --local -b chrome
58+
[chromedriver@130] Starting ChromeDriver 130.0.6723.116 (6ac35f94ae3d01152cf1946c896b0678e48f8ec4-refs/branch-heads/6723@{#1764}) on port 43415
59+
[chromedriver@130] Only local connections are allowed.
60+
[chromedriver@130] Please see https://chromedriver.chromium.org/security-considerations for suggestions on keeping ChromeDriver safe.
61+
[chromedriver@130] ChromeDriver was started successfully on port 43415.
62+
```
63+
64+
## Browser support {#browser-support}
65+
66+
Here is the table of supported browsers:
67+
68+
| Browser | Auto download | Auto driver download | Running webdriver |
69+
| ------- | ------------- | -------------------- | ----------------- |
70+
| Chrome | + | + | + |
71+
| Firefox | + | + | + |
72+
| Edge | - | + | + |
73+
| Safari | - | + | + |
74+
75+
Supported browser versions per OS:
76+
77+
| OS | Windows | MacOs | Ubuntu 20 | Ubuntu 22 | Ubuntu 24 |
78+
| :-----: | ------- | ----- | --------- | --------- | --------- |
79+
| Chrome | 73+ | 73+ | 73+ | 73+ | 73+ |
80+
| Firefox | 60+ | 60+ | 60+ | 91+ | 126+ |
81+
| Edge | \* | \* | \* | \* | \* |
82+
| Safari | - | \* | - | - | - |
83+
84+
- - Browser auto download is not supported, but if the browser is installed by the user himself, installed version will be used by Testplane.
85+
86+
For virtual environments, you would need to run headless. "--no-sandbox" CLI arg for "chrome" browser could also be necessary:
87+
88+
```typescript
89+
{
90+
// other chrome browser settings
91+
headless: true,
92+
desiredCapabilities: {
93+
browserName: "chrome",
94+
browserVersion: "130.0",
95+
"goog:chromeOptions": { args: ["--no-sandbox"] }
96+
}
97+
}
98+
```

‎i18n/en/docusaurus-plugin-content-blog/local-browsers.mdx

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Running on Local Browsers
3+
slug: local-browsers-intro
4+
hide_table_of_contents: false
5+
date: 2024-12-19T14:00
6+
---
7+
8+
import Admonition from "@theme/Admonition";
9+
import localBrowsersExampleUrl from "/video/blog/local-browsers/local-browsers-example.mp4";
10+
11+
Testplane is now able to automatically download browsers for running tests locally. Enjoy a hassle-free start with `--local` option if you don't need remote browser grid.
12+
13+
<!-- truncate -->
14+
15+
Previously, Testplane with the webdriver automation protocol could only be launched locally with a manually started [selenium-standalone](https://github.com/webdriverio/selenium-standalone). Now, it is enough to specify `gridUrl: "local"` in the [Testplane Config](/docs/v8/config/main) or run tests with the [CLI option](/docs/v8/command-line) `--local`. In this case, if necessary, the corresponding browsers and web drivers will be downloaded before running the tests, and they will also be launched for further use in these tests.
16+
17+
You can also download the browsers and their web drivers separately using the [install-deps](/docs/v8/command-line#install-deps) command.
18+
19+
Example of running tests on local browser with webdriver automation protocol:
20+
21+
<video src={localBrowsersExampleUrl} width="100%" controls="controls" autoplay="autoplay">
22+
Tag video is not supported by your browser.
23+
<a href="video/blog/local-browsers/local-browsers-example.mp4">Download video</a>.
24+
</video>
25+
26+
### How to use?
27+
28+
Learn more about this in our documentation [How to Run Testplane in a Local Browser](/docs/v8/guides/local-browsers).

‎i18n/en/docusaurus-plugin-content-blog/vscode-extension.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ import Admonition from "@theme/Admonition";
99
import runTestsFromSidebarVideoUrl from "/video/blog/vscode-extension/run-tests-from-sidebar.mp4";
1010
import runTestsFromEditorVideoUrl from "/video/blog/vscode-extension/run-tests-from-editor.mp4";
1111

12-
We have implemented an extension for [VS Code][vscode] for Testplane, which allows you to configure Testplane from scratch, run tests, and conveniently work with the <a href="/ru/docs/v8/command-line/#testplane-repl">REPL mode</a>.
12+
We have implemented an extension for [VS Code][vscode] for Testplane, which allows you to configure Testplane from scratch, run tests, and conveniently work with the <a href="/ru/docs/v8/command-line#testplane-repl">REPL mode</a>.
1313

1414
<!-- truncate -->
1515

@@ -80,7 +80,7 @@ In the sidebar of the testing panel, there is also a section titled Testplane. H
8080

8181
#### With the `REPL` settings
8282

83-
When you click the checkbox `Enable REPL` and subsequently run a test (only one test can be run simultaneously in REPL mode), it will be launched in a special REPL mode. You can read more about this mode <a href="/ru/docs/v8/command-line/#testplane-repl">here</a>.
83+
When you click the checkbox `Enable REPL` and subsequently run a test (only one test can be run simultaneously in REPL mode), it will be launched in a special REPL mode. You can read more about this mode <a href="/ru/docs/v8/command-line#testplane-repl">here</a>.
8484

8585
![Enabling the REPL option](/img/blog/vscode-extension/enable-repl.png)
8686

0 commit comments

Comments
 (0)