diff --git a/blog/local-browsers.mdx b/blog/local-browsers.mdx new file mode 100644 index 0000000..94cb86b --- /dev/null +++ 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 добавлена возможность автоматической загрузки браузеров и драйверов для последующего локального запуска. + + + +Раньше 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 протоколом автоматизации: + + + +### Как использовать? + +Узнайте больше об этом в нашей документации [Как запустить Testplane в локальном браузере](/docs/v8/guides/local-browsers). diff --git a/blog/vscode-extension.mdx b/blog/vscode-extension.mdx index 486c32e..fca9043 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, с помощью которого можно настраивать 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) @@ -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 index fa87954..952b825 100644 --- 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 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 +``` + ## 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 index 7746dca..7aa184e 100644 --- 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`. + + 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). + + ### 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 new file mode 100644 index 0000000..aa77a05 --- /dev/null +++ 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 new file mode 100644 index 0000000..7ba4669 --- /dev/null +++ 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. + + + +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: + + + +### 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..164b550 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/command-line/index.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/command-line/index.mdx index 991a915..6aa6e69 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/command-line/index.mdx +++ b/i18n/ru/docusaurus-plugin-content-docs/current/command-line/index.mdx @@ -2,157 +2,277 @@ import Admonition from "@theme/Admonition"; # CLI {#cli} -Testplane позволяет устанавливать параметры через CLI. +## Команда `testplane` -## Обзор {#overview} - -Доступные опции: +Основная команда для запуска тестов. +```bash +> testplane --help + + Usage: testplane [options] [command] [paths...] + + Run tests + + Options: + + -V, --version output the version number + -c, --config path to configuration file + -b, --browser run tests only in specified browser + -s, --set run tests only in the specified set + -r, --require require module + --grep run only tests matching the pattern + --reporter test reporters + --update-refs update screenshot references or gather them if they do not exist ("assertView" command) + --inspect [inspect] nodejs inspector on [=[host:]port] + --inspect-brk [inspect-brk] nodejs inspector with break at the start + --repl [type] run one test, call `browser.switchToRepl` in test code to open repl interface (default: false) + --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 ``` --V, --version вывести версию инструмента --c, --config путь к конфигурационному файлу --b, --browser запустить тесты только в указанном браузере --s, --set запустить тесты только в указанном наборе --r, --require добавить модуль ---reporter установить репортер ---grep запустить только тесты, соответствующие шаблону ---update-refs обновить эталоны скриншотов или создать их, если они не существуют (используеося командой "assertView") ---inspect [inspect] запустить node.js инспектор ---inspect-brk [inspect-brk] запустить nodejs инспектор с точкой останова в начале ---repl [type] запустить repl режим, позволяя вызвать `browser.switchToRepl` в коде теста для открытия repl интерфейса (по умолчанию: false) ---repl-before-test [type] запустить repl режим перед запуском теста (по умолчанию: false) ---repl-on-fail [type] запустить repl режим только в случае падения теста (по умолчанию: false) ---devtools запустить тесты используя протокол автоматизации Chrome Devtools Protocol --h, --help вывести информацию об использовании + +Например, + +```bash +npx testplane --config ./config.js --reporter flat --browser firefox --grep name ``` -## Переопределение настроек {#overriding-settings} +### Опции {#testplane-options} -Все параметры можно переопределить с помощью флагов командной строки или переменных среды согласно следующим приоритетам (в порядке убывания): +#### Version {#testplane-version} -- Опция командной строки; +Вывести текущую версию `testplane`. -- Переменная окружения; +```bash +testplane --version +``` -- Значение в файле конфигурации; +#### Config {#testplane-config} -- Значение по умолчанию. +Использовать пользовательский файл конфигурации. -### Переопределение с помощью опции CLI {#overriding-cli-settings} +```bash +testplane --config ./local.testplane.config.ts +``` -Чтобы переопределить параметр конфигурации с помощью опции CLI, преобразуйте полный путь опции в `--kebab-case`. +#### Browser {#testplane-browser} -Например, чтобы переопределить свойство `baseUrl` в конфигурации: +Запускать тесты только в указанном браузере. ```bash -testplane path/to/mytest.js --base-url http://example.com +testplane --browser chrome ``` -Это также работает для вложенных свойств. Пример переопределения значения `browsers.firefox.sessionsPerBrowser` (предполагается, что Вы описали браузер с идентификатором "firefox"): +#### Set {#testplane-set} + +Запускать тесты только в указанном наборе. ```bash -testplane path/to/mytest.js --browsers-firefox-sessions-per-browser 7 +testplane --set desktop ``` -### Переопределение с помощью переменной окружения {#overriding-env-settings} +#### Require {#testplane-require} + +Загрузить внешние модули, локально существующие на вашей машине, перед запуском `testplane`. Это полезно для загрузчиков, таких как ECMAScript модули через [esm](https://www.npmjs.com/package/esm). -Чтобы переопределить настройку с помощью переменной окружения, переведите ее полный путь в `snake_case` и добавьте префикс `testplane_`. +```bash +testplane --require ./tsconfig-register-paths.js +``` -Примеры переопределения тех же значений `baseUrl` и `browsers.firefox.sessionsPerBrowser` с использованием переменных среды вместо опций CLI: +#### Reporter {#testplane-reporter} + +Может использоваться для установки одного из следующих репортеров: + +- `flat` - вся информация о неудачных и повторно выполненных тестах будет сгруппирована по браузерам в конце отчета; +- `plain` - информация о сбоях и повторениях будет размещена после каждого теста; +- `jsonl` - отображает подробную информацию о каждом результате теста в формате [jsonl](https://jsonlines.org/). + +По умолчанию используется `flat`. + +Информация о результатах тестов выводится в командную строку по умолчанию. Но есть возможность перенаправить вывод в файл: ```bash -testplane_base_url=http://example.com testplane path/to/mytest.js -testplane_browsers_firefox_sessions_per_browser=7 testplane path/to/mytest.js +testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' ``` -Помимо переопределения значений конфигурации, также существуют две дополнительные переменные среды: "TESTPLANE_SKIP_BROWSERS" и "TESTPLANE_SETS": +Вы также можете указать несколько репортеров: -#### TESTPLANE_SKIP_BROWSERS +```bash +testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' --reporter flat +``` + +Помимо этих терминальных репортеров, вы можете использовать плагин [html-reporter][html-reporter], чтобы генерировать HTML-отчеты. + +#### Grep {#testplane-grep} + +Запускать только тесты, полное название которых совпадает с шаблоном. + +##### Пример {#testplane-grep-example} + +Если у вас есть некоторые тесты: + +```ts +describe("test", () => { + describe("with", () => { + describe("nested path", () => { + ... + }); + describe("other path", () => { + ... + }) + }); +}); +``` -Пропустить браузеры, указанные в конфигурации, по их идентификатору. Несколько идентификаторов браузеров должны быть разделены запятой -(допускаются пробелы после запятых). +Вы можете запустить тесты внутри "nested path" набора, не запуская тесты внутри "other path" набора, с любым из этих вариантов: ```bash -TESTPLANE_SKIP_BROWSERS=ie10,ie11 testplane +testplane --grep "nested path" +testplane --grep "with nested path" +testplane --grep "test with nested path" ``` -#### TESTPLANE_SETS +#### Update-refs {#testplane-update-refs} -Запускает только указанные наборы (альтернатива опции CLI `--set`). +Запуск тестов с обновлением всех ссылок на скриншоты, созданных командой [assertView][assert-view]. ```bash -TESTPLANE_SETS=desktop,touch testplane +testplane --update-refs ``` -## Version {#version} + + Рекомендуемый способ обновления скриншотов - использование плагина + [html-reporter][html-reporter]. + -Вывести текущую версию `testplane`. +#### Inspect {#testplane-inspect} + +Запускает тесты Testplane с использованием [инспектора nodejs](https://nodejs.org/en/docs/inspector). ```bash -testplane --version +testplane --inspect ``` -## Config {#config} + + В режиме отладки запускается только один рабочий и все тесты выполняются только в нём. + Используйте этот режим с опцией `sessionsPerBrowser=1`, чтобы отлаживать тесты поодиночке. + + +#### Inspect break {#testplane-inspect-brk} -Использовать заданный файл конфигурации. +То же, что и [Инспекция](#testplane-inspect), но с точкой останова в начале. ```bash -testplane --config ./local.testplane.config.ts +testplane --inspect-brk ``` -## Browser {#browser} +#### REPL {#testplane-repl} + +Включает [REPL](https://en.wikipedia.org/wiki/Read–eval–print_loop). Также отключает ограничение времени выполнения теста. Можно использовать, указав следующие опции CLI: -Запустить тесты только в указанном браузере. +- `--repl` - в этом режиме следует запускать только один тест в одном браузере, иначе будет выбрасываться ошибка. Интерфейс REPL не запускается автоматически, поэтому вам нужно вызвать команду [switchToRepl][switch-to-repl] в коде теста; +- `--repl-before-test` - то же, что и опция `--repl`, за исключением того, что интерфейс REPL открывается автоматически перед запуском теста; +- `--repl-on-fail` - то же, что и опция `--repl`, за исключением того, что интерфейс REPL открывается автоматически при сбое теста. ```bash -testplane --browser chrome +testplane --repl --grep 'my test name' --browser chrome ``` -## Set {#set} + + Более подробная информация о режиме REPL в Testplane доступна в документации команды + [switchToRepl][switch-to-repl]. + -Запустить тесты только в указанном наборе. +#### Devtools {#testplane-devtools} + +Запускает тесты Testplane с использованием [протокола автоматизации devtools][webdriver-vs-cdp]. ```bash -testplane --set desktop +testplane --devtools ``` -## Require {#require} +#### Help {#testplane-help} -Загрузить внешние модули, которые локально у вас на машине, перед запуском `testplane`. Это полезно для загрузчиков, таких как ECMAScript модули через [esm](https://www.npmjs.com/package/esm). +Выводит информацию о параметрах и командах. Плагины Testplane могут добавлять свои собственные команды и параметры. + +Например, [html-reporter][html-reporter] добавляет команду `gui`. ```bash -testplane --require ./tsconfig-register-paths.js +testplane --help ``` -## Reporter {#reporter} +## Команда `list-tests` + +Команда для получения списка тестов в одном из доступных форматов (`list` или `tree`). -Может использоваться для установки одного из следующих терминальных отчетов: +```bash +> testplane list-tests --help -- `flat` - вся информация об ошибках и повторных тестах будет сгруппирована по браузерам в конце отчета; -- `plain` - информация об ошибках и повторах будет размещена после каждого теста; -- `jsonl` - выводит подробную информацию о каждом результате теста в форме [jsonl](https://jsonlines.org/). + Использование: list-tests [опции] [пути...] -По умолчанию - `flat`. + Выводит информацию о всех тестах в одном из доступных форматов -По умолчанию информация о результатах тестов выводится в командную строку, но есть возможность перенаправить вывод в файл: + Опции: + + -c, --config путь к файлу конфигурации + -b, --browser выводит тесты только в указанном браузере + -s, --set выводит тесты только в указанном наборе + -r, --require подключить модуль + --grep выводит только тесты, соответствующие шаблону + --ignore исключить пути из чтения тестов + --silent [type] флаг отключения генерации событий во время чтения тестов (по умолчанию: false) + --output-file сохранить результаты в указанный файл + --formatter [name] вернуть тесты в указанном формате (по умолчанию: list) + -h, --help вывести информацию об использовании +``` + +Например, + +``` +npx testplane list-tests --config ./config.js --browser firefox --grep name --formatter tree +``` + +### Опции {#list-tests-options} + +#### Config {#list-tests-config} + +Использовать пользовательский файл конфигурации. ```bash -testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' +testplane list-tests --config ./local.testplane.config.ts ``` -Вы также можете создавать несколько отчетов: +#### Browser {#list-tests-browser} + +Выводит тесты только в указанном браузере. ```bash -testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' --reporter flat +testplane list-tests --browser chrome ``` -Помимо этих отчетов для терминала, вы можете использовать плагин [html-reporter][html-reporter] для создания html-отчетов. +#### Set {#list-tests-set} + +Выводит тесты только в указанном наборе. -## Grep {#grep} +```bash +testplane list-tests --set desktop +``` -Запусть только те тесты, полное название которых соответствует шаблону. +#### Require {#list-tests-require} -### Пример {#grep-example} +Загрузить внешние модули, локально существующие на вашей машине, перед выводом тестов `testplane`. Это полезно для загрузчиков, таких как ECMAScript модули через [esm](https://www.npmjs.com/package/esm). + +```bash +testplane list-tests --require ./tsconfig-register-paths.js +``` + +#### Grep {#list-tests-grep} + +Выводит только тесты, полное название которых совпадает с шаблоном. + +##### Пример {#list-tests-grep-example} Если у вас есть некоторые тесты: @@ -169,80 +289,278 @@ describe("test", () => { }); ``` -То вы можете запустить тесты внутри набора "nested path" без запуска тестов внутри набора "other path" с помощью любого из этих вариантов: +Вы можете вывести тесты внутри "nested path" набора, не включая тесты внутри "other path" набора, с любым из этих вариантов: ```bash -testplane --grep "nested path" -testplane --grep "with nested path" -testplane --grep "test with nested path" +testplane list-tests --grep "nested path" +testplane list-tests --grep "with nested path" +testplane list-tests --grep "test with nested path" ``` -### Update refs {#update-refs} +#### Silent {#list-tests-silent} -Запустить тесты, обновив все ссылки на снимки экрана, созданные командой [assertView][assert-view]. +Выводит тесты без генерации событий. ```bash -testplane --update-refs +testplane list-tests --silent ``` - - Рекомендуемый способ обновления эталонов - использование плагина [html-reporter][html-reporter]. - +#### Output file {#list-tests-output-file} + +Сохранить список тестов в указанный файл. + +```bash +testplane list-tests --output-file "./tests.json" +``` -## Inspect {#testplane-inspect} +#### Formatter {#list-tests-formatter} -Запускает тесты Testplane с использованием [nodejs дебаггера](https://nodejs.org/en/docs/inspector). +Выводит тесты в указанном формате. Доступные форматтеры: `list` (по умолчанию) и `tree`. + +##### List formatter {#list-tests-formatter-list} + +Выводит тесты в формате `list`. ```bash -testplane --inspect +testplane list-tests --formatter "list" ``` - - В отладочном режиме запускается только один рабочий процесс, и все тесты выполняются только в - нем. Используйте этот режим с опцией `sessionsPerBrowser=1`, чтобы отлаживать тесты по одному. - +Для следующих тестов: + +```typescript title="example.testplane.ts" +describe("suite1", () => { + it("test1", () => {}); +}); -## Inspect break {#inspect-brk} +it("test2", () => {}); +``` + +Возвращает следующий вывод: + +```json +[ + { + "id": "d2b3179", + "titlePath": [ + "suite", + "test1" + ], + "browserIds": [ + "yandex", + "chrome" + ], + "file": "tests/example.testplane.ts", + "pending": false, + "skipReason": "" + } + { + "id": "5a105e8", + "titlePath": [ + "test1" + ], + "browserIds": [ + "yandex", + "chrome" + ], + "file": "tests/example.testplane.ts", + "pending": false, + "skipReason": "" + } +] +``` + +Здесь у нас есть плоский список уникальных тестов, где: -То же самое, что и [Inspect](#testplane-inspect), но с точкой останова в начале. +- `id` (`String`) - уникальный идентификатор теста; +- `titlePath` (`String[]`) - полное название теста. Каждый элемент массива - название набора или теста. Чтобы получить полное название, нужно просто соединить `titlePath` с одним пробелом; +- `browserIds` (`String[]`) - список браузеров, в которых будет запускаться тест; +- `file` (`String`) - путь к файлу относительно рабочей директории; +- `pending` (`Boolean`) - флаг, означающий, что тест отключен или нет; +- `skipReason` (`String`) - причина, по которой тест был отключен. + +##### Tree formatter {#list-tests-formatter-tree} + +Выводит тесты в формате `tree`. ```bash -testplane --inspect-brk +testplane list-tests --formatter "tree" ``` -## REPL {#testplane-repl} +Для следующих тестов: -Включает [REPL](https://ru.wikipedia.org/wiki/REPL). Также отключает таймаут продолжительности теста. Может быть включен с помощью указания следующих CLI опций: +```typescript title="example.testplane.ts" +describe("suite1", () => { + it("test1", () => {}); +}); + +it("test2", () => {}); +``` + +Возвращает следующий вывод: + +```json +[ + { + "id": "36749990", + "title": "suite1", + "line": 1, + "column": 1, + "file": "example.testplane.ts", + "suites": [], + "tests": [ + { + "id": "d2b3179", + "title": "test1", + "line": 2, + "column": 5, + "browserIds": ["yandex", "chrome"] + } + ], + "pending": false, + "skipReason": "" + }, + { + "id": "5a105e8", + "title": "test2", + "line": 5, + "column": 1, + "browserIds": ["yandex", "chrome"], + "file": "example.testplane.ts", + "pending": false, + "skipReason": "" + } +] +``` + +Здесь у нас есть список уникальных тестов в виде структуры дерева (с родительскими наборами), где `Suite` имеет следующие опции: + +- `id` (`String`) - уникальный идентификатор набора; +- `title` (`String`) - заголовок набора; +- `line` (`Number`) - строка, в которой был вызван набор; +- `column` (`Number`) - столбец, в котором был вызван набор; +- `file` (`String`, только в верхнем наборе) - путь к файлу относительно рабочей директории; +- `suites` (`Suite[]`, существует только в наборе) - список вложенных наборов; +- `tests` (`Test[]`) - список тестов; +- `pending` (`Boolean`) - флаг, означающий, что тест отключен или нет; +- `skipReason` (`String`) - причина, по которой тест был отключен. -- `--repl` - в этом режиме должен быть запущен только один тест в одном браузере, в противном случае выбрасывается ошибка. REPL интерфейс не запускается автоматически, поэтому вам нужно вызвать команду [switchToRepl][switch-to-repl] в коде теста; -- `--repl-before-test` - то же, что и опция `--repl`, за исключением того, что REPL интерфейс открывается автоматически перед запуском теста; -- `--repl-on-fail` - то же, что и опция `--repl`, за исключением того, что REPL интерфейс открывается автоматически при ошибке во время выполнения теста. +И `Test` имеет следующие опции: + +- `id` (`String`) - уникальный идентификатор теста; +- `title` (`String`) - заголовок теста; +- `line` (`Number`) - строка, в которой был вызван тест; +- `column` (`Number`) - столбец, в котором был вызван тест; +- `browserIds` (`String[]`) - список браузеров, в которых будет запущен тест; +- `file` (`String`, только в тестах без родительских наборов) - путь к файлу относительно рабочей директории; +- `pending` (`Boolean`) - флаг, означающий, что тест отключен или нет; +- `skipReason` (`String`) - причина, по которой тест был отключен. + +#### Help {#list-tests-help} + +Выводит информацию о параметрах и командах. Плагины Testplane могут добавлять свои собственные команды и параметры. + +Например, [html-reporter][html-reporter] добавляет команду `gui`. ```bash -testplane --repl --grep 'my test name' --browser chrome +testplane list-tests --help ``` - - Больше информации о режиме REPL можно найти в документации команды - [switchToRepl][switch-to-repl]. - +## Команда `install-deps` {#install-deps} -## Devtools {#devtools} +Эта команда является частью рецепта [Как запустить Testplane в локальном браузере](/docs/v8/guides/local-browsers). -Запускает тесты Testplane с использованием [протокола автоматизации devtools][webdriver-vs-cdp]. +Используйте команду `install-deps`, чтобы загрузить все браузеры, указанные в [конфиге Testplane](/docs/v8/config/main). + +Если эта команда запущена на поддерживаемой версии Ubuntu, также будут загружены все отсутствующие необходимые пакеты Ubuntu. + +### Использование {#usage} ```bash -testplane --devtools +npx testplane install-deps ``` -## Помощь {#help} +### Аргументы команды {#arguments} -Выводит информацию об опциях и командах. Плагины Testplane могут добавлять свои собственные команды и опции. +Вы можете также указать, какие браузеры нужно загрузить. -Например, [html-reporter][html-reporter] добавляет команду `gui`. +Например, если у вас описаны браузеры "chrome-dark", "firefox-dark" в конфигурации Testplane, вы можете использовать следующую команду для загрузки только этих двух браузеров: ```bash -testplane --help +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 +``` + +## Переопределение настроек {#overriding-settings} + +Все параметры можно переопределить с помощью флагов командной строки или переменных окружения с приоритетами в следующем порядке по убыванию: + +- Опция командной строки; + +- Переменная окружения; + +- Значение в файле конфигурации; + +- Значение по умолчанию. + +### Переопределение с помощью CLI опции {#overriding-cli-settings} + +Чтобы переопределить настройку в конфигурации с помощью опции CLI, преобразуйте полный путь параметра в `--kebab-case`. + +Например, чтобы переопределить свойство `baseUrl` в конфигурации: + +```bash +testplane path/to/mytest.js --base-url http://example.com +``` + +Это также работает для вложенных свойств. Пример переопределения значения `browsers.firefox.sessionsPerBrowser` (предполагается, что у вас определен браузер с идентификатором "firefox"): + +```bash +testplane path/to/mytest.js --browsers-firefox-sessions-per-browser 7 +``` + +### Переопределение с помощью переменной окружения {#overriding-env-settings} + +Чтобы переопределить настройку с помощью переменной окружения, преобразуйте её полный путь в `snake_case` и добавьте префикс `testplane_`. + +Примеры переопределения значений `baseUrl` и `browsers.firefox.sessionsPerBrowser` с использованием переменных окружения вместо опций CLI: + +```bash +testplane_base_url=http://example.com testplane path/to/mytest.js +testplane_browsers_firefox_sessions_per_browser=7 testplane path/to/mytest.js +``` + +Кроме переопределения значений конфигурации, существуют также две дополнительные переменные окружения: "TESTPLANE_SKIP_BROWSERS" и "TESTPLANE_SETS": + +#### TESTPLANE_SKIP_BROWSERS + +Пропустить браузеры, указанные в конфигурации, путем передачи идентификаторов браузеров. Несколько идентификаторов браузеров должны быть разделены запятыми (после запятых разрешены пробелы). + +```bash +TESTPLANE_SKIP_BROWSERS=ie10,ie11 testplane +``` + +#### TESTPLANE_SETS + +Запускает только указанные наборы (альтернатива опции CLI `--set`). + +```bash +TESTPLANE_SETS=desktop,touch testplane ``` [html-reporter]: ../html-reporter/html-reporter-setup 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..2590207 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/local-browsers.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/guides/local-browsers.mdx new file mode 100644 index 0000000..340b31c --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/guides/local-browsers.mdx @@ -0,0 +1,98 @@ +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`). + +Также можно загрузить лишь необходимые бразуеры, описанные в конфиге. Например, если описан браузер `chrome-dark`, то загрузить только его можно командой `npx testplane install-deps chrome-dark`. + +Больше об этой команде можно прочитать на соответствующей странице: [install-deps](/docs/v8/command-line#install-deps) + +## Запуск тестов + +Запускать тесты на локальных браузерах можно с [CLI опцией](/docs/v8/command-line) `--local`, либо с [gridUrl](/docs/v8/config/browsers/#grid_url): "local" в [конфиге Testplane](/docs/v8/config/main). Например: + +```bash +npx testplane --local +``` + +Так для поддерживаемых браузеров будут автоматически запущены соответствующие вебдрайвер процессы, и Testplane будет использовать эти локально запущенные драйверы с локально загруженными браузерами. + +При необходимости, браузеры будут загружены перед запуском, так что отдельный запуск команды `install-deps` не обязателен, особенно если хочется быстро запустить тест только в одном браузере. + +## Отладка тестов + +При включении `debug` в конфиге, логи вебдрайвера с префиксом будут выводиться в stdout/stderr: + +```typescript +export default { + // ... остальные настройки 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. +``` + +## Поддержка браузеров {#browser-support} + +Ниже представлена таблица поддерживаемых браузеров: + +| Браузер | Авто-загрузка | Авто-загрузка драйвера | Запуск webdriver | +| ------- | ------------- | ---------------------- | ---------------- | +| Chrome | + | + | + | +| Firefox | + | + | + | +| Edge | - | + | + | +| Safari | - | + | + | + +Поддерживаемые версии браузеров в зависимости от ОС: + +| ОС | Windows | MacOs | Ubuntu 20 | Ubuntu 22 | Ubuntu 24 | +| :-----: | ------- | ----- | --------- | --------- | --------- | +| Chrome | 73+ | 73+ | 73+ | 73+ | 73+ | +| Firefox | 60+ | 60+ | 60+ | 91+ | 126+ | +| Edge | \* | \* | \* | \* | \* | +| Safari | - | \* | - | - | - | + +- - Авто-загрузка браузера не поддерживается, но если браузер установлен пользователем, Testplane будет использовать установленную версию. + +Для виртуальных сред браузер может быть запущен только в фоновом режиме. Также может потребоваться CLI аргумент "--no-sandbox" для браузера "chrome": + +```typescript +{ + // другие настройки браузера chrome + headless: true, + desiredCapabilities: { + browserName: "chrome", + browserVersion: "130.0", + "goog:chromeOptions": { args: ["--no-sandbox"] } + } +} +``` diff --git a/static/video/blog/local-browsers/local-browsers-example.mp4 b/static/video/blog/local-browsers/local-browsers-example.mp4 new file mode 100644 index 0000000..9089d08 Binary files /dev/null and b/static/video/blog/local-browsers/local-browsers-example.mp4 differ