From 5c4339deb54b82ee9bd8af5bf532013af340a1ad Mon Sep 17 00:00:00 2001 From: Roman Kuznetsov Date: Thu, 8 Aug 2024 17:52:14 +0300 Subject: [PATCH] docs: describe CLI --- docs/command-line/index.mdx | 251 ++++++++++++++++++ docs/commands/browser/switchToRepl.mdx | 0 .../current/command-line/index.mdx | 251 ++++++++++++++++++ .../current/commands/browser/switchToRepl.mdx | 0 .../current.json | 4 + sidebars.ts | 5 + 6 files changed, 511 insertions(+) create mode 100644 docs/command-line/index.mdx create mode 100644 docs/commands/browser/switchToRepl.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/command-line/index.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchToRepl.mdx diff --git a/docs/command-line/index.mdx b/docs/command-line/index.mdx new file mode 100644 index 0000000..3246679 --- /dev/null +++ b/docs/command-line/index.mdx @@ -0,0 +1,251 @@ +import Admonition from "@theme/Admonition"; + +# Интерфейс командной строки {#cli} + +Testplane позволяет устанавливать параметры через интерфейс командной строки. + +## Обзор {#overview} + +Доступные опции: + +``` +-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 вывести информацию об использовании +``` + +## Переопределение настроек {#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 +``` + +## Version {#version} + +Вывести текущую версию `testplane`. + +```bash +testplane --version +``` + +## Config {#config} + +Использовать заданный файл конфигурации. + +```bash +testplane --config ./local.testplane.config.ts +``` + +## Browser {#browser} + +Запустить тесты только в указанном браузере. + +```bash +testplane --browser chrome +``` + +## Set {#set} + +Запустить тесты только в указанном наборе. + +```bash +testplane --set desktop +``` + +## Require {#require} + +Загрузить внешние модули, которые локально у вас на машине, перед запуском `testplane`. Это полезно для загрузчиков, таких как ECMAScript модули через [esm](https://www.npmjs.com/package/esm). + +```bash +testplane --require ./tsconfig-register-paths.js +``` + +## Reporter {#reporter} + +Может использоваться для установки одного из следующих терминальных отчетов: + +- `flat` - вся информация об ошибках и повторных тестах будет сгруппирована по браузерам в конце отчета; +- `plain` - информация об ошибках и повторах будет размещена после каждого теста; +- `jsonl` - выводит подробную информацию о каждом результате теста в форме [jsonl](https://jsonlines.org/). + +По умолчанию - `flat`. + +По умолчанию информация о результатах тестов выводится в командную строку, но есть возможность перенаправить вывод в файл: + +```bash +testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' +``` + +Вы также можете создавать несколько отчетов: + +```bash +testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' --reporter flat +``` + +Помимо этих отчетов для терминала, вы можете использовать плагин [html-reporter][html-reporter] для создания html-отчетов. + +## Grep {#grep} + +Запусть только те тесты, полное название которых соответствует шаблону. + +### Пример {#grep-example} + +Если у вас есть некоторые тесты: + +```ts +describe("test", () => { + describe("with", () => { + describe("nested path", () => { + ... + }); + describe("other path", () => { + ... + }) + }); +}); +``` + +То вы можете запустить тесты внутри набора "nested path" без запуска тестов внутри набора "other path" с помощью любого из этих вариантов: + +```bash +testplane --grep "nested path" +testplane --grep "with nested path" +testplane --grep "test with nested path" +``` + +### Update refs {#update-refs} + +Запустить тесты, обновив все ссылки на снимки экрана, созданные командой [assertView][assert-view]. + +```bash +testplane --update-refs +``` + + + Рекомендуемый способ обновления эталонов - использование плагина [html-reporter][html-reporter]. + + +## Inspect {#inspect} + +Запускает тесты Testplane с использованием [nodejs дебаггера](https://nodejs.org/en/docs/inspector). + +```bash +testplane --inspect +``` + + + В отладочном режиме запускается только один рабочий процесс, и все тесты выполняются только в + нем. Используйте этот режим с опцией `sessionsPerBrowser=1`, чтобы отлаживать тесты по одному. + + +## Inspect break {#inspect-brk} + +То же самое, что и [Inspect](#inspect), но с точкой останова в начале. + +```bash +testplane --inspect-brk +``` + +## REPL {#repl} + +Включает [REPL](https://ru.wikipedia.org/wiki/REPL). Также отключает таймаут продолжительности теста. Может быть включен с помощью указания следующих CLI опций: + +- `--repl` - в этом режиме должен быть запущен только один тест в одном браузере, в противном случае выбрасывается ошибка. REPL интерфейс не запускается автоматически, поэтому вам нужно вызвать команду [switchToRepl][switch-to-repl] в коде теста; +- `--repl-before-test` - то же, что и опция `--repl`, за исключением того, что REPL интерфейс открывается автоматически перед запуском теста; +- `--repl-on-fail` - то же, что и опция `--repl`, за исключением того, что REPL интерфейс открывается автоматически при ошибке во время выполнения теста. + +```bash +testplane --repl --grep 'my test name' --browser chrome +``` + + + Больше информации о режиме REPL можно найти в документации команды + [switchToRepl][switch-to-repl]. + + +## Devtools {#devtools} + +Запускает тесты Testplane с использованием [протокола автоматизации devtools][webdriver-vs-cdp]. + +```bash +testplane --devtools +``` + +## Помощь {#help} + +Выводит информацию об опциях и командах. Плагины Testplane могут добавлять свои собственные команды и опции. + +Например, [html-reporter][html-reporter] добавляет команду `gui`. + +```bash +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 diff --git a/docs/commands/browser/switchToRepl.mdx b/docs/commands/browser/switchToRepl.mdx new file mode 100644 index 0000000..e69de29 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/command-line/index.mdx b/i18n/en/docusaurus-plugin-content-docs/current/command-line/index.mdx new file mode 100644 index 0000000..62d7313 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/command-line/index.mdx @@ -0,0 +1,251 @@ +import Admonition from "@theme/Admonition"; + +# Command Line Interface {#cli} + +Testplane allows setting options via command line interface. + +## Overview {#overview} + +Available 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 +--reporter test reporters +--grep run only tests matching the pattern +--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 +-h, --help output usage information +``` + +## Overriding settings {#overriding-settings} + +All options can be overridden via command-line flags or environment variables with the following priorities, by descending: + +- A command-line option; + +- An environment variable; + +- A config file value; + +- The default value. + +### Overriding with CLI option {#overriding-cli-settings} + +To override a config setting with a CLI option, convert the full option path to `--kebab-case`. + +For example, to override config's `baseUrl` property: + +```bash +testplane path/to/mytest.js --base-url http://example.com +``` + +It also works for nested properties. Example of overriding `browsers.firefox.sessionsPerBrowser` value (assuming you have defined browser with id "firefox"): + +```bash +testplane path/to/mytest.js --browsers-firefox-sessions-per-browser 7 +``` + +### Overriding with environment variable {#overriding-env-settings} + +To override a setting with an environment variable, convert its full path to `snake_case` and add the `testplane_` prefix. + +Examples of overriding the same `baseUrl` and `browsers.firefox.sessionsPerBrowser` values using environment variables instead of CLI options: + +```bash +testplane_base_url=http://example.com testplane path/to/mytest.js +testplane_browsers_firefox_sessions_per_browser=7 testplane path/to/mytest.js +``` + +Besides overriding config values, there also two extra environment variables: "TESTPLANE_SKIP_BROWSERS" and "TESTPLANE_SETS": + +#### TESTPLANE_SKIP_BROWSERS + +Skip the browsers specified in the config by passing the browser IDs. Multiple browser IDs should be separated by commas +(spaces after commas are allowed). + +```bash +TESTPLANE_SKIP_BROWSERS=ie10,ie11 testplane +``` + +#### TESTPLANE_SETS + +Runs only specified sets (CLI option `--set` alternative). + +```bash +TESTPLANE_SETS=desktop,touch testplane +``` + +## Version {#version} + +Print current `testplane` version. + +```bash +testplane --version +``` + +## Config {#config} + +Use custom configuration file. + +```bash +testplane --config ./local.testplane.config.ts +``` + +## Browser {#browser} + +Run tests only in specified browser. + +```bash +testplane --browser chrome +``` + +## Set {#set} + +Run tests only in the specified set. + +```bash +testplane --set desktop +``` + +## Require {#require} + +Load external modules, locally existing in your machine, before running `testplane`. This is useful for loaders, such as ECMAScript modules via [esm](https://www.npmjs.com/package/esm). + +```bash +testplane --require ./tsconfig-register-paths.js +``` + +## Reporter {#reporter} + +Can be used to set one of the following reporters: + +- `flat` - all information about failed and retried tests would be grouped by browsers at the end of the report; +- `plain` - information about fails and retries would be placed after each test; +- `jsonl` - displays detailed information about each test result in [jsonl](https://jsonlines.org/) form. + +Default is `flat`. + +Information about test results is displayed to the command line by default. But there is an ability to redirect the output to a file: + +```bash +testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' +``` + +You can also specify multiple reporters: + +```bash +testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' --reporter flat +``` + +Aside these terminal reporters, you can use [html-reporter][html-reporter] plugin in order to generate html reports. + +## Grep {#grep} + +Run only tests, which full name matches the pattern. + +### Example {#grep-example} + +If you have some tests: + +```ts +describe("test", () => { + describe("with", () => { + describe("nested path", () => { + ... + }); + describe("other path", () => { + ... + }) + }); +}); +``` + +You can run tests inside "nested path" suite without running tests inside "other path" suite with any of these variants: + +```bash +testplane --grep "nested path" +testplane --grep "with nested path" +testplane --grep "test with nested path" +``` + +### Update refs {#update-refs} + +Run tests, updating all screenshot references, created by [assertView][assert-view] command. + +```bash +testplane --update-refs +``` + + + Recommended way to update screenshots is using [html-reporter][html-reporter] plugin. + + +## Inspect {#inspect} + +Runs Testplane tests using [nodejs inspector](https://nodejs.org/en/docs/inspector). + +```bash +testplane --inspect +``` + + + In the debugging mode, only one worker is started and all tests are performed only in it. Use + this mode with option `sessionsPerBrowser=1` in order to debug tests one at a time. + + +## Inspect break {#inspect-brk} + +The same as [Inspect](#inspect), but with breakpoint at the start. + +```bash +testplane --inspect-brk +``` + +## REPL {#repl} + +Enables a [REPL](https://en.wikipedia.org/wiki/Read–eval–print_loop). It also disables test duration timeout. Can be used by specifying following CLI options: + +- `--repl` - in this mode, only one test in one browser should be run, otherwise an error is thrown. REPL interface does not start automatically, so you need to call [switchToRepl][switch-to-repl] command in the test code; +- `--repl-before-test` - the same as `--repl` option except that REPL interface opens automatically before run test; +- `--repl-on-fail` - the same as `--repl` option except that REPL interface opens automatically on test fail. + +```bash +testplane --repl --grep 'my test name' --browser chrome +``` + + + More information about Testplane REPL mode can be found in [switchToRepl][switch-to-repl] + command documentation. + + +## Devtools {#devtools} + +Runs Testplane tests using [devtools automation protocol][webdriver-vs-cdp]. + +```bash +testplane --devtools +``` + +## Help {#help} + +Prints out information about options and commands. Testplane Plugins can add their own commands and options. + +For example, [html-reporter][html-reporter] adds `gui` command. + +```bash +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 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchToRepl.mdx b/i18n/en/docusaurus-plugin-content-docs/current/commands/browser/switchToRepl.mdx new file mode 100644 index 0000000..e69de29 diff --git a/i18n/ru/docusaurus-plugin-content-docs/current.json b/i18n/ru/docusaurus-plugin-content-docs/current.json index 5e6fe8a..273f12b 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current.json +++ b/i18n/ru/docusaurus-plugin-content-docs/current.json @@ -50,5 +50,9 @@ "sidebar.mainSidebar.doc.Quickstart": { "message": "Быстрый старт", "description": "The label for the doc item Quickstart in sidebar mainSidebar, linking to the doc quickstart/index" + }, + "sidebar.mainSidebar.doc.CommandLine": { + "message": "Интерфейс командной строки", + "description": "The label for the doc item CommandLine in sidebar mainSidebar, linking to the doc command-line/index" } } diff --git a/sidebars.ts b/sidebars.ts index 541cb5d..dabb9a7 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -8,6 +8,11 @@ const sidebars: SidebarsConfig = { id: "quickstart/index", label: "Quickstart", }, + { + type: "doc", + id: "command-line/index", + label: "Command Line Interface", + }, { type: "category", label: "Commands",