CLI

Команда testplane

Основная команда для запуска тестов.

> testplane --help

  Usage: testplane [options] [command] [paths...]

  Run tests

  Options:

    -V, --version                    output the version number
    -c, --config <path>              path to configuration file
    -b, --browser <browser>          run tests only in specified browser
    -s, --set <set>                  run tests only in the specified set
    -r, --require <module>           require module
    --grep <grep>                    run only tests matching the pattern
    --reporter <name>                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
    --keep-browser                   do not close browser session after test completion
    --keep-browser-on-fail           do not close browser session when test fails
    -h, --help                       output usage information

Например,

npx testplane --config ./config.js --reporter flat --browser firefox --grep name

Опции

Version

Вывести текущую версию testplane.

testplane --version

Config

Использовать пользовательский файл конфигурации.

testplane --config ./local.testplane.config.ts

Browser

Запускать тесты только в указанном браузере.

testplane --browser chrome

Set

Запускать тесты только в указанном наборе.

testplane --set desktop

Require

Загрузить внешние модули, локально существующие на вашей машине, перед запуском testplane. Это полезно для загрузчиков, таких как ECMAScript модули через esm.

testplane --require ./tsconfig-register-paths.js

Reporter

Может использоваться для установки одного из следующих репортеров:

• flat - вся информация о неудачных и повторно выполненных тестах будет сгруппирована по браузерам в конце отчета;
• plain - информация о сбоях и повторениях будет размещена после каждого теста;
• jsonl - отображает подробную информацию о каждом результате теста в формате jsonl.

По умолчанию используется flat.

Информация о результатах тестов выводится в командную строку по умолчанию. Но есть возможность перенаправить вывод в файл:

testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}'

Вы также можете указать несколько репортеров:

testplane --reporter '{"type": "jsonl", "path": "./some-path/result.jsonl"}' --reporter flat

Помимо этих терминальных репортеров, вы можете использовать плагин html-reporter, чтобы генерировать HTML-отчеты.

Grep

Запускать только тесты, полное название которых совпадает с шаблоном.

Пример

Если у вас есть некоторые тесты:

describe("test", () => {
    describe("with", () => {
        describe("nested path", () => {
            ...
        });
        describe("other path", () => {
            ...
        })
    });
});

Вы можете запустить тесты внутри "nested path" набора, не запуская тесты внутри "other path" набора, с любым из этих вариантов:

testplane --grep "nested path"
testplane --grep "with nested path"
testplane --grep "test with nested path"

Update-refs

Запуск тестов с обновлением всех ссылок на скриншоты, созданных командой assertView.

testplane --update-refs

к сведению

Рекомендуемый способ обновления скриншотов - использование плагина html-reporter.

Inspect

Запускает тесты Testplane с использованием инспектора nodejs.

testplane --inspect

к сведению

В режиме отладки запускается только один рабочий и все тесты выполняются только в нём. Используйте этот режим с опцией sessionsPerBrowser=1, чтобы отлаживать тесты поодиночке.

Inspect break

То же, что и Инспекция, но с точкой останова в начале.

testplane --inspect-brk

REPL

Включает REPL. Также отключает ограничение времени выполнения теста. Можно использовать, указав следующие опции CLI:

• --repl - в этом режиме следует запускать только один тест в одном браузере, иначе будет выбрасываться ошибка. Интерфейс REPL не запускается автоматически, поэтому вам нужно вызвать команду switchToRepl в коде теста;
• --repl-before-test - то же, что и опция --repl, за исключением того, что интерфейс REPL открывается автоматически перед запуском теста;
• --repl-on-fail - то же, что и опция --repl, за исключением того, что интерфейс REPL открывается автоматически при сбое теста.

testplane --repl --grep 'my test name' --browser chrome

к сведению

Более подробная информация о режиме REPL в Testplane доступна в документации команды switchToRepl.

Keep browser

• --keep-browser - в этом режиме браузер не закроется по завершению выполнения тестов, в консоли будет выведена информация как подключиться к оставшемуся браузеру
• --keep-browser-on-fail - то же, что и опция --keep-browser, только браузер останется только в том случае, если тесты завершатся неуспешно

Пример вывода в консоли c информацией для подключения к браузеру

[15:44:38 +0700] Testplane run has finished, but the browser won't be closed, because you passed the --keep-browser argument.
[15:44:38 +0700] You may attach to this browser using the following capabilities:
[15:44:38 +0700] {
  "sessionId": "c69958b3f85b851f7bf83f27bb026d58",
  "sessionCaps": {
    "acceptInsecureCerts": false,
    ...
  },
  "driverPid": 31745
}
[15:44:38 +0700] ✓ test example #0 [chrome:c69958b3f85b851f7bf83f27bb026d58, pid:31744] - 1676ms

Devtools

Запускает тесты Testplane с использованием протокола автоматизации devtools.

testplane --devtools

Help

Выводит информацию о параметрах и командах. Плагины Testplane могут добавлять свои собственные команды и параметры.

Например, html-reporter добавляет команду gui.

testplane --help

Команда list-tests

Команда для получения списка тестов в одном из доступных форматов (list или tree).

> testplane list-tests --help

  Использование: list-tests [опции] [пути...]

  Выводит информацию о всех тестах в одном из доступных форматов

  Опции:

    -c, --config <path>        путь к файлу конфигурации
    -b, --browser <browser>    выводит тесты только в указанном браузере
    -s, --set <set>            выводит тесты только в указанном наборе
    -r, --require <module>     подключить модуль
    --grep <grep>              выводит только тесты, соответствующие шаблону
    --ignore <file-path>       исключить пути из чтения тестов
    --silent [type]            флаг отключения генерации событий во время чтения тестов (по умолчанию: false)
    --output-file <file-path>  сохранить результаты в указанный файл
    --formatter [name]         вернуть тесты в указанном формате (по умолчанию: list)
    -h, --help                 вывести информацию об использовании

Например,

npx testplane list-tests --config ./config.js --browser firefox --grep name --formatter tree

Опции

Config

Использовать пользовательский файл конфигурации.

testplane list-tests --config ./local.testplane.config.ts

Browser

Выводит тесты только в указанном браузере.

testplane list-tests --browser chrome

Set

Выводит тесты только в указанном наборе.

testplane list-tests --set desktop

Require

Загрузить внешние модули, локально существующие на вашей машине, перед выводом тестов testplane. Это полезно для загрузчиков, таких как ECMAScript модули через esm.

testplane list-tests --require ./tsconfig-register-paths.js

Grep

Выводит только тесты, полное название которых совпадает с шаблоном.

Пример

Если у вас есть некоторые тесты:

describe("test", () => {
    describe("with", () => {
        describe("nested path", () => {
            ...
        });
        describe("other path", () => {
            ...
        })
    });
});

Вы можете вывести тесты внутри "nested path" набора, не включая тесты внутри "other path" набора, с любым из этих вариантов:

testplane list-tests --grep "nested path"
testplane list-tests --grep "with nested path"
testplane list-tests --grep "test with nested path"

Silent

Выводит тесты без генерации событий.

testplane list-tests --silent

Output file

Сохранить список тестов в указанный файл.

testplane list-tests --output-file "./tests.json"

Formatter

Выводит тесты в указанном формате. Доступные форматтеры: list (по умолчанию) и tree.

List formatter

Выводит тесты в формате list.

testplane list-tests --formatter "list"

Для следующих тестов:

example.testplane.ts

describe("suite1", () => {
    it("test1", () => {});
});

it("test2", () => {});

Возвращает следующий вывод:

[
    {
        "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": ""
    }
]

Здесь у нас есть плоский список уникальных тестов, где:

• id (String) - уникальный идентификатор теста;
• titlePath (String[]) - полное название теста. Каждый элемент массива - название набора или теста. Чтобы получить полное название, нужно просто соединить titlePath с одним пробелом;
• browserIds (String[]) - список браузеров, в которых будет запускаться тест;
• file (String) - путь к файлу относительно рабочей директории;
• pending (Boolean) - флаг, означающий, что тест отключен или нет;
• skipReason (String) - причина, по которой тест был отключен.

Tree formatter

Выводит тесты в формате tree.

testplane list-tests --formatter "tree"

Для следующих тестов:

example.testplane.ts

describe("suite1", () => {
    it("test1", () => {});
});

it("test2", () => {});

Возвращает следующий вывод:

[
    {
        "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) - причина, по которой тест был отключен.

И Test имеет следующие опции:

• id (String) - уникальный идентификатор теста;
• title (String) - заголовок теста;
• line (Number) - строка, в которой был вызван тест;
• column (Number) - столбец, в котором был вызван тест;
• browserIds (String[]) - список браузеров, в которых будет запущен тест;
• file (String, только в тестах без родительских наборов) - путь к файлу относительно рабочей директории;
• pending (Boolean) - флаг, означающий, что тест отключен или нет;
• skipReason (String) - причина, по которой тест был отключен.

Help

Выводит информацию о параметрах и командах. Плагины Testplane могут добавлять свои собственные команды и параметры.

Например, html-reporter добавляет команду gui.

testplane list-tests --help

Команда list-browsers

Команда для получения всех браузеров из конфигурации.

> npx testplane list-browsers --help

  Usage: list-browsers [options]

  Lists all browsers from the config

  Options:

    --type [type]      return browsers in specified type ('tags': browserName and browserVersion, 'ids': browserId from config) (default: tags)
    --format [format]  return browsers in specified format ('json' / 'plain') (default: json)
    -h, --help         output usage information

Например,

npx testplane list-browsers --type ids --format plain

Опции

Type

Укажите тип выводимых данных: browserId из конфигурации или browserName с browserVersion.

testplane list-browsers --type tags

Format

Укажите формат выводимых данных: обычный текст или json.

testplane list-browsers --format json

Пример

Если у вас имеется следующий раздел "browsers" в вашей конфигурации Testplane:

{
    "my-chrome": { "desiredCapabilities": { "browserName": "chrome", "browserVersion": "130.0" } },
    "my-safari": { "desiredCapabilities": { "browserName": "safari" } }
}

Следующие команды произведут соответствующий результат:

Команда	Результат
testplane list-browsers --type ids --format plain	my-chrome my-safari
testplane list-browsers --type ids --format json	["my-chrome","my-safari"]
testplane list-browsers --type tags --format plain	chrome@130.0 safari
testplane list-browsers --type tags --format json	[{"browserName":"chrome","browserVersion":"130.0"},{"browserName":"safari"}]

Help

Выводит информацию команде и ее опциях.

testplane list-browsers --help

Команда config

Команда для получения всех значений конфигурации Testplane, включая значения по умолчанию и перезаписанные значения с помощью переменных среды.

> npx testplane config --help

  Usage: config [options]

  Outputs Testplane config (including default and overriden by environment variables values)

  Options:

    -c, --config <path>  path to configuration file
    --space <count>      white spaces count to insert into the JSON output (default: 0)
    -h, --help           output usage information

Например:

npx testplane config --space 4

Опции

Space

Укажите количество пробелов, используемых для форматирования человекочитаемого вывода команды.

testplane config --space 4

Help

Выводит информацию команде и ее опциях.

testplane config --help

Команда install-deps

Эта команда является частью рецепта Как запустить Testplane в локальном браузере.

Используйте команду install-deps, чтобы загрузить все браузеры, указанные в конфиге Testplane.

Если эта команда запущена на поддерживаемой версии Ubuntu, также будут загружены все отсутствующие необходимые пакеты Ubuntu.

Использование

npx testplane install-deps

Аргументы команды

Вы можете также указать, какие браузеры нужно загрузить.

Например, если у вас описаны браузеры "chrome-dark", "firefox-dark" в конфигурации Testplane, вы можете использовать следующую команду для загрузки только этих двух браузеров:

npx testplane install-deps chrome-dark firefox-dark

Поддерживается также использование названий браузеров с версиями в формате <browserName>@<browserVersion>:

npx testplane install-deps chrome@130 firefox@104

Директория установки

По умолчанию браузеры и драйверы загружаются в директорию ".testplane" в домашней директории.

Вы можете указать другой путь, установив переменную среды TESTPLANE_BROWSERS_PATH:

TESTPLANE_BROWSERS_PATH=./node_modules/.testplane npx testplane install-deps
TESTPLANE_BROWSERS_PATH=~/.testplane npx testplane install-deps

Переопределение настроек

Все параметры можно переопределить с помощью флагов командной строки или переменных окружения с приоритетами в следующем порядке по убыванию:

• Опция командной строки;

• Переменная окружения;

• Значение в файле конфигурации;

• Значение по умолчанию.

Переопределение с помощью CLI опции

Чтобы переопределить настройку в конфигурации с помощью опции CLI, преобразуйте полный путь параметра в --kebab-case.

Например, чтобы переопределить свойство baseUrl в конфигурации:

testplane path/to/mytest.js --base-url http://example.com

Это также работает для вложенных свойств. Пример переопределения значения browsers.firefox.sessionsPerBrowser (предполагается, что у вас определен браузер с идентификатором "firefox"):

testplane path/to/mytest.js --browsers-firefox-sessions-per-browser 7

Переопределение с помощью переменной окружения

Чтобы переопределить настройку с помощью переменной окружения, преобразуйте её полный путь в snake_case и добавьте префикс testplane_.

Примеры переопределения значений baseUrl и browsers.firefox.sessionsPerBrowser с использованием переменных окружения вместо опций CLI:

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

Пропустить браузеры, указанные в конфигурации, путем передачи идентификаторов браузеров. Несколько идентификаторов браузеров должны быть разделены запятыми (после запятых разрешены пробелы).

TESTPLANE_SKIP_BROWSERS=ie10,ie11 testplane

TESTPLANE_SETS

Запускает только указанные наборы (альтернатива опции CLI --set).

TESTPLANE_SETS=desktop,touch testplane