docs: describe local browsers

Author: KuznetsovRoman

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) или запустить тесты с [CLI-опцией](/docs/v8/command-line) `--local`. В таком случае перед запуском тестов, при необходимости, будут загружены соответствующие браузеры и вебдрайверы к ним, которые также будут запущены для дальнейшего использования в этих тестах.
+
+Загрузить браузеры и вебдрайверы к ним можно и отдельно, с помощью команды [install-deps](/docs/v8/command-line#install-deps).
+
+### Как использовать?
+
+Узнайте больше об этом в нашей документации [Как запустить Testplane в локальном браузере](/docs/v8/guides/local-browsers).

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#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)
 

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:

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:

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) `--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.
+```

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) `--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).

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)
 

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"
     }
 }