docs: describe local browsers

gemini-testing · Dec 24, 2024 · 2564ac5 · 2564ac5
1 parent d655633
commit 2564ac5
Show file tree

Hide file tree

Showing 11 changed files with 737 additions and 115 deletions.
diff --git a/blog/local-browsers.mdx b/blog/local-browsers.mdx
@@ -0,0 +1,28 @@
+---
+title: Запуск на локальных браузерах
+slug: local-browsers-intro
+hide_table_of_contents: false
+date: 2024-12-19T14:00
+---
+
+import Admonition from "@theme/Admonition";
+import localBrowsersExampleUrl from "/video/blog/local-browsers/local-browsers-example.mp4";
+
+В Testplane добавлена возможность автоматической загрузки браузеров и драйверов для последующего локального запуска.
+
+<!-- truncate -->
+
+Раньше Testplane с протоколом автоматизации webdriver можно было запустить локально только с вручную запущенным [selenium-standalone](https://github.com/webdriverio/selenium-standalone). Теперь достаточно указать указать `gridUrl: "local"` в [Конфиге Testplane](/docs/v8/command-line) или запустить тесты с [CLI-опцией](/docs/v8/command-line) `--local`. В таком случае перед запуском тестов при необходимости будут загружены соответствующие браузеры и вебдрайверы к ним, которые также будут запущены для дальнейшего использования в этих тестах.
+
+Загрузить браузеры и вебдрайверы к ним можно и отдельно, с помощью команды [install-deps](/docs/v8/command-line#install-deps).
+
+Пример запуска тестов на локальном браузере с webdriver протоколом автоматизации:
+
+<video src={localBrowsersExampleUrl} width="100%" controls="controls" autoplay>
+    Тег video не поддерживается вашим браузером.
+    <a href="video/blog/local-browsers/local-browsers-example.mp4">Скачайте видео</a>.
+</video>
+
+### Как использовать?
+
+Узнайте больше об этом в нашей документации [Как запустить Testplane в локальном браузере](/docs/v8/guides/local-browsers).
diff --git a/blog/vscode-extension.mdx b/blog/vscode-extension.mdx
@@ -9,7 +9,7 @@ import Admonition from "@theme/Admonition";
 import runTestsFromSidebarVideoUrl from "/video/blog/vscode-extension/run-tests-from-sidebar.mp4";
 import runTestsFromEditorVideoUrl from "/video/blog/vscode-extension/run-tests-from-editor.mp4";
 
-Для Testplane реализовали расширение для [VS Code][vscode], с помощью которого можно настраивать Testplane с нуля, запускать тесты и удобно работать с <a href="/ru/docs/v8/command-line/#testplane-repl">REPL режимом</a>.
+Для Testplane реализовали расширение для <a href="https://code.visualstudio.com/">VS Code</a>, с помощью которого можно настраивать Testplane с нуля, запускать тесты и удобно работать с <a href="/ru/docs/v8/command-line#testplane-repl">REPL режимом</a>.
 
 <!-- truncate -->
 
@@ -80,7 +80,7 @@ Install Testplane
 
 #### С настройкой `REPL`
 
-При клике в чекбокс `Enable REPL` и последующем запуске теста (в REPL режиме можно одновременно запустить только один тест) он будет запущен в специальном REPL режиме. Подробнее про этот режим можно прочитать <a href="/ru/docs/v8/command-line/#testplane-repl">здесь</a>.
+При клике в чекбокс `Enable REPL` и последующем запуске теста (в REPL режиме можно одновременно запустить только один тест) он будет запущен в специальном REPL режиме. Подробнее про этот режим можно прочитать <a href="/ru/docs/v8/command-line#testplane-repl">здесь</a>.
 
 ![Включение опции REPL](/img/blog/vscode-extension/enable-repl.png)
 
@@ -125,6 +125,5 @@ Install Testplane
 
 Устанавливайте расширение Testplane для VS Code и приходите с фидбеком. В случае обнаружения проблем приходите в [issue github](https://github.com/gemini-testing/testplane/issues) — мы вам обязательно поможем!
 
-[vscode]: https://code.visualstudio.com/
 [vscode-testplane-marketplace]: https://marketplace.visualstudio.com/items?itemName=gemini-testing.vscode-testplane
 [mocha-bdd-interface]: https://mochajs.org/#bdd
diff --git a/docs/command-line/index.mdx b/docs/command-line/index.mdx
@@ -29,6 +29,7 @@ Main command to run tests.
     --repl-before-test [type]        open repl interface before test run (default: false)
     --repl-on-fail [type]            open repl interface on test fail only (default: false)
     --devtools                       switches the browser to the devtools mode with using CDP protocol
+    --local                          use automatically downloaded browsers and drivers, provided by Testplane
     -h, --help                       output usage information
 ```
 
@@ -463,6 +464,47 @@ For example, [html-reporter][html-reporter] adds `gui` command.
 testplane list-tests --help
 ```
 
+## `install-deps` command {#install-deps}
+
+This command is a part of the guide [How to launch Testplane in the local browser](/docs/v8/guides/local-browsers).
+
+Use the `install-deps` command to download all browsers, specified in [Testplane config](/docs/v8/config/main).
+
+If this command is launched on supported ubuntu version, all missing necessary ubuntu packages would be downloaded too.
+
+### Usage {#usage}
+
+```bash
+npx testplane install-deps
+```
+
+### Command arguments {#arguments}
+
+You can also specify, which browsers are need to be downloaded.
+
+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:
+
+```bash
+npx testplane install-deps chrome-dark firefox-dark
+```
+
+Using browser names with versions in a format like `<browserName>@<browserVersion>` is also supported:
+
+```bash
+npx testplane install-deps chrome@130 firefox@104
+```
+
+### Installation directory {#directory}
+
+By default, browsers and drivers are downloaded to ".testplane" directory at home directory.
+
+You can specify other path by setting `TESTPLANE_BROWSERS_PATH` env variable:
+
+```bash
+TESTPLANE_BROWSERS_PATH=./node_modules/.testplane npx testplane install-deps
+TESTPLANE_BROWSERS_PATH=~/.testplane npx testplane install-deps
+```
+
 ## Overriding settings {#overriding-settings}
 
 All options can be overridden via command-line flags or environment variables with the following priorities, by descending:

diff --git a/docs/config/browsers.mdx b/docs/config/browsers.mdx
@@ -134,6 +134,11 @@ Grid URL (the address where ChromeDriver/Selenium Standalone/Sauce Labs/etc. lis
 
 Default: `http://localhost:4444/wd/hub`.
 
+<Admonition type="info">
+    You can also use value `"local"` in order to use local browsers, managed by Testplane. Read more
+    in guide [How to launch Testplane in the local browser](/docs/v8/guides/local-browsers).
+</Admonition>
+
 ### baseUrl {#base_url}
 
 Base URL of the service being tested. Allows for more convenient use of the `browser.url` commands:

diff --git a/docs/guides/local-browsers.mdx b/docs/guides/local-browsers.mdx
@@ -0,0 +1,98 @@
+import Admonition from "@theme/Admonition";
+
+# How to Run Testplane in a Local Browser
+
+## Introduction
+
+Testplane can automatically download browsers in accordance with your [Testplane Config](/docs/v8/config/main).
+
+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.
+
+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.
+
+## Installing dependencies
+
+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`).
+
+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'.
+
+You can read more about this command on the respective page: [install-deps](/docs/v8/command-line#install-deps)
+
+## Running tests
+
+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:
+
+```bash
+npx testplane --local
+```
+
+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.
+
+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.
+
+## Debugging tests
+
+When `debug` is enabled in the config, web driver logs with a prefix will be output to stdout/stderr:
+
+```typescript
+export default {
+    // ... other Testplane settings
+    system: {
+        debug: true,
+    },
+};
+```
+
+To reduce excessive `webdriverio` logs, you can set the desired level for the `WDIO_LOG_LEVEL` environment variable.
+
+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:
+
+```bash
+testplane_system_debug=true WDIO_LOG_LEVEL=error npx testplane --local -b chrome
+```
+
+And the web driver logs will look something like this:
+
+```plaintext
+$ testplane_system_debug=true WDIO_LOG_LEVEL=error npx testplane --local -b chrome
+[chromedriver@130] Starting ChromeDriver 130.0.6723.116 (6ac35f94ae3d01152cf1946c896b0678e48f8ec4-refs/branch-heads/6723@{#1764}) on port 43415
+[chromedriver@130] Only local connections are allowed.
+[chromedriver@130] Please see https://chromedriver.chromium.org/security-considerations for suggestions on keeping ChromeDriver safe.
+[chromedriver@130] ChromeDriver was started successfully on port 43415.
+```
+
+## Browser support {#browser-support}
+
+Here is the table of supported browsers:
+
+| Browser | Auto download | Auto driver download | Running webdriver |
+| ------- | ------------- | -------------------- | ----------------- |
+| Chrome  | +             | +                    | +                 |
+| Firefox | +             | +                    | +                 |
+| Edge    | -             | +                    | +                 |
+| Safari  | -             | +                    | +                 |
+
+Supported browser versions per OS:
+
+|   OS    | Windows | MacOs | Ubuntu 20 | Ubuntu 22 | Ubuntu 24 |
+| :-----: | ------- | ----- | --------- | --------- | --------- |
+| Chrome  | 73+     | 73+   | 73+       | 73+       | 73+       |
+| Firefox | 60+     | 60+   | 60+       | 91+       | 126+      |
+|  Edge   | \*      | \*    | \*        | \*        | \*        |
+| Safari  | -       | \*    | -         | -         | -         |
+
+-   -   Browser auto download is not supported, but if the browser is installed by the user himself, installed version will be used by Testplane.
+
+For virtual environments, you would need to run headless. "--no-sandbox" CLI arg for "chrome" browser could also be necessary:
+
+```typescript
+{
+    // other chrome browser settings
+    headless: true,
+    desiredCapabilities: {
+        browserName: "chrome",
+        browserVersion: "130.0",
+        "goog:chromeOptions": { args: ["--no-sandbox"] }
+    }
+}
+```
diff --git a/i18n/en/docusaurus-plugin-content-blog/local-browsers.mdx b/i18n/en/docusaurus-plugin-content-blog/local-browsers.mdx
@@ -0,0 +1,28 @@
+---
+title: Running on Local Browsers
+slug: local-browsers-intro
+hide_table_of_contents: false
+date: 2024-12-19T14:00
+---
+
+import Admonition from "@theme/Admonition";
+import localBrowsersExampleUrl from "/video/blog/local-browsers/local-browsers-example.mp4";
+
+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.
+
+<!-- truncate -->
+
+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.
+
+You can also download the browsers and their web drivers separately using the [install-deps](/docs/v8/command-line#install-deps) command.
+
+Example of running tests on local browser with webdriver automation protocol:
+
+<video src={localBrowsersExampleUrl} width="100%" controls="controls" autoplay>
+    Tag video is not supported by your browser.
+    <a href="video/blog/local-browsers/local-browsers-example.mp4">Download video</a>.
+</video>
+
+### How to use?
+
+Learn more about this in our documentation [How to Run Testplane in a Local Browser](/docs/v8/guides/local-browsers).
diff --git a/i18n/en/docusaurus-plugin-content-blog/vscode-extension.mdx b/i18n/en/docusaurus-plugin-content-blog/vscode-extension.mdx
@@ -9,7 +9,7 @@ import Admonition from "@theme/Admonition";
 import runTestsFromSidebarVideoUrl from "/video/blog/vscode-extension/run-tests-from-sidebar.mp4";
 import runTestsFromEditorVideoUrl from "/video/blog/vscode-extension/run-tests-from-editor.mp4";
 
-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>.
+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>.
 
 <!-- truncate -->
 
@@ -80,7 +80,7 @@ In the sidebar of the testing panel, there is also a section titled Testplane. H
 
 #### With the `REPL` settings
 
-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>.
+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>.
 
 ![Enabling the REPL option](/img/blog/vscode-extension/enable-repl.png)