From 20e3b1ecb28be979580572f7eb3c1affcdb4f573 Mon Sep 17 00:00:00 2001 From: Roman Kuznetsov Date: Mon, 23 Dec 2024 06:02:46 +0300 Subject: [PATCH] docs: describe local browsers --- blog/local-browsers.mdx | 20 +++++++ blog/vscode-extension.mdx | 4 +- docs/command-line/install-deps.mdx | 42 ++++++++++++++ docs/command-line/{index.mdx => main.mdx} | 9 +-- docs/config/browsers.mdx | 6 ++ docs/guides/component-testing.mdx | 2 +- docs/guides/local-browsers.mdx | 56 +++++++++++++++++++ .../local-browsers.mdx | 20 +++++++ .../vscode-extension.mdx | 4 +- .../current.json | 2 +- .../current/command-line/install-deps.mdx | 42 ++++++++++++++ .../command-line/{index.mdx => main.mdx} | 8 +-- .../current/config/browsers.mdx | 6 ++ .../current/guides/component-testing.mdx | 2 +- .../current/guides/local-browsers.mdx | 56 +++++++++++++++++++ sidebars.ts | 2 +- 16 files changed, 265 insertions(+), 16 deletions(-) create mode 100644 blog/local-browsers.mdx create mode 100644 docs/command-line/install-deps.mdx rename docs/command-line/{index.mdx => main.mdx} (97%) create mode 100644 docs/guides/local-browsers.mdx create mode 100644 i18n/en/docusaurus-plugin-content-blog/local-browsers.mdx create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/command-line/install-deps.mdx rename i18n/ru/docusaurus-plugin-content-docs/current/command-line/{index.mdx => main.mdx} (98%) create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/guides/local-browsers.mdx diff --git a/blog/local-browsers.mdx b/blog/local-browsers.mdx new file mode 100644 index 0000000..d177b8a --- /dev/null +++ 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 добавлена возможность автоматической загрузки браузеров и драйверов для последующего локального запуска. + + + +Раньше 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 index 486c32e..e2d32fa 100644 --- 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 с нуля, запускать тесты и удобно работать с REPL режимом. +Для Testplane реализовали расширение для [VS Code][vscode], с помощью которого можно настраивать Testplane с нуля, запускать тесты и удобно работать с REPL режимом. @@ -80,7 +80,7 @@ Install Testplane #### С настройкой `REPL` -При клике в чекбокс `Enable REPL` и последующем запуске теста (в REPL режиме можно одновременно запустить только один тест) он будет запущен в специальном REPL режиме. Подробнее про этот режим можно прочитать здесь. +При клике в чекбокс `Enable REPL` и последующем запуске теста (в REPL режиме можно одновременно запустить только один тест) он будет запущен в специальном REPL режиме. Подробнее про этот режим можно прочитать здесь. ![Включение опции REPL](/img/blog/vscode-extension/enable-repl.png) diff --git a/docs/command-line/install-deps.mdx b/docs/command-line/install-deps.mdx new file mode 100644 index 0000000..182a677 --- /dev/null +++ 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 Testplane config. + +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 Testplane config, 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 `@` 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 b/docs/command-line/main.mdx similarity index 97% rename from docs/command-line/index.mdx rename to docs/command-line/main.mdx index fa87954..a7c2de5 100644 --- a/docs/command-line/index.mdx +++ b/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 index 7746dca..8862887 100644 --- 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`. + + 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). + + ### 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 index 638c9f5..6929af3 100644 --- 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 new file mode 100644 index 0000000..d40eae0 --- /dev/null +++ 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 new file mode 100644 index 0000000..3bf2d50 --- /dev/null +++ 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. + + + +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 index d19fabf..c141797 100644 --- 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 REPL mode. +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 REPL mode. @@ -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 here. +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 here. ![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 index 293a62c..1e0c818 100644 --- 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 new file mode 100644 index 0000000..1dec2c0 --- /dev/null +++ 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} + +Вы также можете указать, какие браузеры необходимо загрузить. + +Например, если в конфиге Testplane у вас описаны браузеры "chrome-dark" и "firefox-dark", вы можете использовать следующую команду, чтобы загрузить только эти два браузера: + +```bash +npx testplane install-deps chrome-dark firefox-dark +``` + +Также поддерживается использование имен браузеров с версиями в формате `@`: + +```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/i18n/ru/docusaurus-plugin-content-docs/current/command-line/index.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/command-line/main.mdx similarity index 98% rename from i18n/ru/docusaurus-plugin-content-docs/current/command-line/index.mdx rename to i18n/ru/docusaurus-plugin-content-docs/current/command-line/main.mdx index 991a915..999e292 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/command-line/index.mdx +++ b/i18n/ru/docusaurus-plugin-content-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 index 27d792b..10a5631 100644 --- 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`. + + Также можно использовать значение `"local"`, чтобы использовать автоматические локальные + браузеры, управляемые Testplane. Читайте больше в рецепте [Как запустить Testplane в локальном + браузере](/docs/v8/guides/local-browsers). + + ### 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 index 11cd279..3d18ebd 100644 --- 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 new file mode 100644 index 0000000..a5369cc --- /dev/null +++ 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. +``` diff --git a/sidebars.ts b/sidebars.ts index 9025fec..c3d36aa 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -10,7 +10,7 @@ const sidebars: SidebarsConfig = { }, { type: "doc", - id: "command-line/index", + id: "command-line/main", label: "CLI", }, {