docs: describe local browsers

gemini-testing · Dec 23, 2024 · 20e3b1e · 20e3b1e
1 parent d655633
commit 20e3b1e
Show file tree

Hide file tree

Showing 16 changed files with 265 additions and 16 deletions.
diff --git a/blog/local-browsers.mdx b/blog/local-browsers.mdx
@@ -0,0 +1,20 @@
+---
+title: Запуск на локальных браузерах
+slug: local-browsers-intro
+hide_table_of_contents: false
+date: 2024-12-19T14:00
+---
+
+import Admonition from "@theme/Admonition";
+
+В Testplane добавлена возможность автоматической загрузки браузеров и драйверов для последующего локального запуска.
+
+<!-- truncate -->
+
+Раньше Testplane с протоколом автоматизации webdriver можно было запустить локально только со вручную запущенным [selenium-standalone](https://github.com/webdriverio/selenium-standalone). Теперь достаточно указать указать `gridUrl: "local"` в [Конфиге Testplane](/docs/v8/command-line/main) или запустить тесты с [CLI-опцией](/docs/v8/command-line/main) `--local`. В таком случае перед запуском тестов, при необходимости, будут загружены соответствующие браузеры и вебдрайверы к ним, которые также будут запущены для дальнейшего использования в этих тестах.
+
+Загрузить браузеры и вебдрайверы к ним можно и отдельно, с помощью команды [install-deps](/docs/v8/command-line/install-deps).
+
+### Как использовать?
+
+Узнайте больше об этом в нашей документации [Как запустить 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 реализовали расширение для [VS Code][vscode], с помощью которого можно настраивать Testplane с нуля, запускать тесты и удобно работать с <a href="/ru/docs/v8/command-line/main#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/main#testplane-repl">здесь</a>.
 
 ![Включение опции REPL](/img/blog/vscode-extension/enable-repl.png)
 

diff --git a/docs/command-line/install-deps.mdx b/docs/command-line/install-deps.mdx
@@ -0,0 +1,42 @@
+# install-deps
+
+## Overview {#overview}
+
+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 <a href="/docs/v8/config/main">Testplane config</a>.
+
+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
+```
diff --git a/docs/command-line/index.mdx → docs/command-line/main.mdx b/docs/command-line/index.mdx → docs/command-line/main.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
 ```
 
@@ -521,7 +522,7 @@ Runs only specified sets (CLI option `--set` alternative).
 TESTPLANE_SETS=desktop,touch testplane
 ```
 
-[html-reporter]: ../html-reporter/html-reporter-setup
-[assert-view]: ../commands/browser/assertView
-[switch-to-repl]: ../commands/browser/switchToRepl
-[webdriver-vs-cdp]: ../reference/webdriver-vs-cdp
+[html-reporter]: ../../html-reporter/html-reporter-setup
+[assert-view]: ../../commands/browser/assertView
+[switch-to-repl]: ../../commands/browser/switchToRepl
+[webdriver-vs-cdp]: ../../reference/webdriver-vs-cdp
diff --git a/docs/config/browsers.mdx b/docs/config/browsers.mdx
@@ -134,6 +134,12 @@ 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 automatic local browsres, 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/component-testing.mdx b/docs/guides/component-testing.mdx
@@ -174,4 +174,4 @@ Calling the `log`, `info`, `warn`, `error`, `debug` and `table` commands on the
 [testplane-examples-component-testing]: https://github.com/gemini-testing/testplane/tree/master/examples/component-testing
 [testplane-global-hook]: https://github.com/gemini-testing/testplane-global-hook
 [vite-hmr]: https://vitejs.dev/guide/api-hmr.html
-[repl-mode]: ../command-line/index.mdx#testplane-repl
+[repl-mode]: ../command-line/main.mdx#testplane-repl
diff --git a/docs/guides/local-browsers.mdx b/docs/guides/local-browsers.mdx
@@ -0,0 +1,56 @@
+import Admonition from "@theme/Admonition";
+
+# How to Run Testplane in a Local Browser
+
+## Introduction
+
+Testplane allows for the automatic downloading of browsers and web drivers as specified in the [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.
+
+## 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 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/main) `--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:
+
+```javascript
+// 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.
+```
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,20 @@
+---
+title: Running on Local Browsers
+slug: local-browsers-intro
+hide_table_of_contents: false
+date: 2024-12-19T14:00
+---
+
+import Admonition from "@theme/Admonition";
+
+Testplane now has the ability for automatic downloading of browsers and drivers for subsequent local browser test launches.
+
+<!-- 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/main) `--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.
+
+### 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/main#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/main#testplane-repl">here</a>.
 
 ![Enabling the REPL option](/img/blog/vscode-extension/enable-repl.png)
 

diff --git a/i18n/ru/docusaurus-plugin-content-docs/current.json b/i18n/ru/docusaurus-plugin-content-docs/current.json
@@ -57,6 +57,6 @@
     },
     "sidebar.mainSidebar.doc.CLI": {
         "message": "CLI",
-        "description": "The label for the doc item Command Line in sidebar mainSidebar, linking to the doc command-line/index"
+        "description": "The label for the doc item Command Line in sidebar mainSidebar, linking to the doc command-line/main"
     }
 }
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/command-line/install-deps.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/command-line/install-deps.mdx
@@ -0,0 +1,42 @@
+# install-deps
+
+## Обзор {#overview}
+
+Эта команда является частью рецепта [Как запустить Testplane в локальном браузере](/docs/v8/guides/local-browsers).
+
+Используйте команду `install-deps` для загрузки всех браузеров, описанных в [конфиге Testplane](/docs/v8/config/main).
+
+Если эта команда запускается на поддерживаемой версии Ubuntu, все недостающие необходимые пакеты для Ubuntu также будут загружены.
+
+## Использование {#usage}
+
+```bash
+npx testplane install-deps
+```
+
+## Аргументы команды {#arguments}
+
+Вы также можете указать, какие браузеры необходимо загрузить.
+
+Например, если в <a href="ru/docs/v8/config/main">конфиге Testplane</a> у вас описаны браузеры "chrome-dark" и "firefox-dark", вы можете использовать следующую команду, чтобы загрузить только эти два браузера:
+
+```bash
+npx testplane install-deps chrome-dark firefox-dark
+```
+
+Также поддерживается использование имен браузеров с версиями в формате `<browserName>@<browserVersion>`:
+
+```bash
+npx testplane install-deps chrome@130 firefox@104
+```
+
+## Директория установки {#directory}
+
+По умолчанию браузеры и драйверы загружаются в директорию ".testplane" в домашней директории.
+
+Вы можете указать другой путь, установив переменную окружения `TESTPLANE_BROWSERS_PATH` в соответствующее значение:
+
+```bash
+TESTPLANE_BROWSERS_PATH=./node_modules/.testplane npx testplane install-deps
+TESTPLANE_BROWSERS_PATH=~/.testplane npx testplane install-deps
+```
diff --git a/...ntent-docs/current/command-line/index.mdx → ...ontent-docs/current/command-line/main.mdx b/...ntent-docs/current/command-line/index.mdx → ...ontent-docs/current/command-line/main.mdx
@@ -245,7 +245,7 @@ testplane --devtools
 testplane --help
 ```
 
-[html-reporter]: ../html-reporter/html-reporter-setup
-[assert-view]: ../commands/browser/assertView
-[switch-to-repl]: ../commands/browser/switchToRepl
-[webdriver-vs-cdp]: ../reference/webdriver-vs-cdp
+[html-reporter]: ../../html-reporter/html-reporter-setup
+[assert-view]: ../../commands/browser/assertView
+[switch-to-repl]: ../../commands/browser/switchToRepl
+[webdriver-vs-cdp]: ../../reference/webdriver-vs-cdp
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/config/browsers.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/config/browsers.mdx
@@ -135,6 +135,12 @@ URL грида (адрес, на котором слушает ChromeDriver/Sele
 
 По умолчанию: `http://localhost:4444/wd/hub`.
 
+<Admonition type="info">
+    Также можно использовать значение `"local"`, чтобы использовать автоматические локальные
+    браузеры, управляемые Testplane. Читайте больше в рецепте [Как запустить Testplane в локальном
+    браузере](/docs/v8/guides/local-browsers).
+</Admonition>
+
 ### baseUrl {#base_url}
 
 Базовый URL тестируемого сервиса. Позволяет более удобно использовать команды `browser.url`:

diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/guides/component-testing.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/guides/component-testing.mdx
@@ -170,4 +170,4 @@ function Component() {
 [testplane-examples-component-testing]: https://github.com/gemini-testing/testplane/tree/master/examples/component-testing
 [testplane-global-hook]: https://github.com/gemini-testing/testplane-global-hook
 [vite-hmr]: https://vitejs.dev/guide/api-hmr.html
-[repl-mode]: ../command-line/index.mdx#testplane-repl
+[repl-mode]: ../command-line/main.mdx#testplane-repl
diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/guides/local-browsers.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/guides/local-browsers.mdx
@@ -0,0 +1,56 @@
+import Admonition from "@theme/Admonition";
+
+# Как запустить Testplane в локальном браузере
+
+## Введение
+
+Testplane позволяет автоматически загружать браузеры и вебдрайверы, описанные в [Конфиге Testplane](/docs/v8/config/main).
+
+Также, если Testplane используется на поддерживаемой версии Ubuntu, аналогичным образом загрузятся и необходимые для запуска браузеров deb пакеты.
+
+## Установка зависимостей
+
+В проекте c Testplane можно выполнить команду `npx testplane install-deps`. Эта команда загрузит необходимые браузеры ( `chrome` и `firefox`) и вебдрайверы к ним (`chrome`, `firefox` и `edge`).
+
+Больше об этой команде можно прочитать на соответствующей странице: [install-deps](/docs/v8/command-line/install-deps)
+
+## Запуск тестов
+
+Запускать тесты на локальных браузерах можно с [CLI опцией](/docs/v8/command-line/main) `--local`, либо с [gridUrl](/docs/v8/config/browsers/#grid_url): "local" в [конфиге Testplane](/docs/v8/config/main). Например:
+
+```bash
+npx testplane --local
+```
+
+Так для поддерживаемых браузеров будут автоматически запущены соответствующие вебдрайвер процессы, и Testplane будет использовать эти локально запущенные драйверы с локально загруженными браузерами.
+
+При необходимости, браузеры будут загружены перед запуском, так что отдельный запуск команды `install-deps` не обязателен, особенно если хочется быстро запустить тест только в одном браузере.
+
+## Отладка тестов
+
+При включении `debug` в конфиге, логи вебдрайвера с префиксом будут выводиться в stdout/stderr:
+
+```javascript
+// остальные настройки Testplane
+system: {
+    debug: true,
+}
+```
+
+От избыточных логов `webdriverio` можно избавиться, установив нужный уровень переменной среды `WDIO_LOG_LEVEL`.
+
+Например, так будет выглядеть запуск со включенным через переменную среды дебагом, уровнем логгирования webdriverio `error` в локальном браузере, имеющем browserId `chrome` в конфиге:
+
+```bash
+testplane_system_debug=true WDIO_LOG_LEVEL=error npx testplane --local -b chrome
+```
+
+И логи вебдрайвера будут выглядеть примерно следующим образом:
+
+```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.
+```