Testplane CLI
Testplane CLI позволяет управлять браузером из терминала.
Вы можете открывать страницы, проходить пользовательские сценарии, сохранять компактные DOM-снимки, смотреть логи консоли, сохранять состояние аутентификации, отлаживать отчеты Testplane и воспроизводить Time Travel snapshots. Инструмент полезен сам по себе, а также является основой для Testplane Skill.
Установка
Установите пакет в проект:
npm install --save-dev @testplane/cli
Затем запускайте его так:
npx @testplane/cli --help
Типовой сценарий
Самый простой способ использования — начинать с navigate. Если браузер еще не запущен, CLI запустит его автоматически.
npx @testplane/cli navigate https://example.com
npx @testplane/cli snapshot
По умолчанию браузеры CLI работают в headless-режиме. Если вы хотите видеть браузер во время отладки, сначала запустите его явно:
npx @testplane/cli launch --headless false
npx @testplane/cli navigate http://localhost:3000
Когда закончите:
npx @testplane/cli close-browser
Если не закрыть браузер вручную, по умолчанию он закроется через 5 минут неактивности.
Как выглядит вывод
Большинство браузерных команд возвращают три полезных блока информации: результат действия, эквивалентный код Testplane и текущее состояние браузера.
Successfully navigated to https://example.com
## Testplane Code
await browser.openAndWait("https://example.com");
## Browser Tabs
1. Title: Example Domain; URL: https://example.com/ (current)
## Current Tab Snapshot
The snapshot was saved to: /tmp/.testplane/snapshots/2026-05-14T21-24-40-811Z.yml
Снапшоты оптимизированы для людей и агентов, читающих вывод терминала. По умолчанию они убирают шумные теги и атрибуты, обрезают очень длинный текст и сохраняют большие снимки во временный файл вместо переполнения терминала.
Навигация и инспекция страниц
Используйте navigate с увеличенным таймаутом для медленных локальных приложений или CI-окружений:
npx @testplane/cli navigate http://localhost:3000 --timeout 60000
Используйте snapshot, чтобы понять структуру страницы:
npx @testplane/cli snapshot
Вы можете настроить снимок, если вывод по умолчанию скрывает что-то важное:
npx @testplane/cli snapshot --include-attrs data-qa href class --max-text-length 200
Используйте screenshot, когда нужны визуальные подтверждения:
npx @testplane/cli screenshot ./tmp/page.png
Для большинства задач отладки тестов начинайте с snapshot. Его быстрее читать, проще искать по нему, и обычно этого достаточно, чтобы найти нужный селектор или состояние.
Взаимодействие с элементами
Команды принимают либо селектор, либо семантические опции в стиле Testing Library.
npx @testplane/cli click '[data-testid="submit"]'
npx @testplane/cli click --role button --name "Submit"
npx @testplane/cli type --label-text "Email" --value "user@example.com"
npx @testplane/cli wait --text "Saved" --timeout 5000
Для нативных элементов <select>:
npx @testplane/cli select "#country" --visible-text "Germany"
npx @testplane/cli select --label-text "Country" --value de
npx @testplane/cli select --label-text "Country" --index 2
После действия CLI сообщает итоговое состояние браузера. Это полезно, когда клик приводит к навигации или заменяет элемент, с которым вы только что взаимодействовали.
Логи консоли
console читает сообщения консоли браузера из сессий на базе Chromium. Он возвращает только сообщения, которые еще не были возвращены предыдущим вызовом console в текущей сессии.
npx @testplane/cli navigate https://stackoverflow.com/questions/10175445/load-page-on-selection-from-dropdown-form
npx @testplane/cli console
Пример:
Retrieved 8 unseen browser console messages
1. [2026-05-14T22:23:40.793Z] WARNING (security): Error with Feature-Policy header: Unrecognized feature: 'speaker'.
2. [2026-05-14T22:23:43.883Z] SEVERE (other): Not signed in with the identity provider.
3. [2026-05-14T22:23:44.059Z] SEVERE (javascript): Access to fetch at 'https://id5-sync.com/api/config/prebid' from origin 'https://stackoverflow.com' has been blocked by CORS policy.
4. [2026-05-14T22:23:44.059Z] SEVERE (network): Failed to load resource: net::ERR_FAILED
Это удобно, когда страница в снимке выглядит нормально, но приложение падает в JavaScript, не загружает заблокированный ресурс или пишет полезные runtime-ошибки.
Работа с вкладками
Используйте команды вкладок, когда сценарий открывает новую страницу.
npx @testplane/cli list-tabs
npx @testplane/cli new-tab http://localhost:3000/settings
npx @testplane/cli switch-tab 1
npx @testplane/cli close-tab 2
Состояние аутентификации
Для сценариев с авторизацией можно сохранять и восстанавливать состояние браузера.
npx @testplane/cli save-state ./tmp/auth-state.json
npx @testplane/cli restore-state ./tmp/auth-state.json
Состояние может включать cookies, localStorage и sessionStorage. Ненужные части можно отключить:
npx @testplane/cli save-state ./tmp/auth-state.json --cookies false
Считайте сохраненный файл чувствительным. Он может содержать реальные auth-данные, даже если в выводе команды печатаются только счетчики.
По умолчанию restore-state обновляет текущую страницу, чтобы код приложения сразу увидел восстановленные cookies и storage.
Запуск произвольного кода Testplane
Когда встроенной команды недостаточно, используйте run-code.
npx @testplane/cli run-code "await browser.getUrl()"
npx @testplane/cli run-code "(browser) => browser.getTitle()"
npx @testplane/cli run-code --file ./debug-script.js
Inline-код может быть JavaScript-выражением, небольшим async-телом или функцией, которая принимает browser.
Подключение к существующим сессиям
Если вы запускаете тест Testplane с --keep-browser, Testplane может напечатать данные браузерной сессии. Подключитесь к этому браузеру и изучите состояние, которое осталось после теста:
npx @testplane/cli attach --session '{"sessionId":"...","capabilities":{}}'
npx @testplane/cli snapshot
Это полезно, когда тест выполняет подготовку, которую трудно воспроизвести вручную, например логин, создание данных или длинный пользо вательский сценарий.
REPL-режим
Предположим, вы запустили Testplane с включенным repl и определенным repl-портом:
npx testplane --grep 'test name' -b chrome-desktop --repl-before-test --repl-port 4444
Тогда CLI может подключиться к этой REPL-сессии Testplane:
npx @testplane/cli attach-repl --port 4444
В REPL-режиме CLI сейчас поддерживает два действия:
npx @testplane/cli snapshot
npx @testplane/cli run-code "await browser.getUrl()"
Главное преимущество — вы остаетесь внутри runtime своего проекта. Это значит, что run-code может использовать page objects, кастомные команды, фикстуры и helper-функции, уже доступные в процессе теста.
Чтение HTML-отчетов Testplane
Команды отчетов работают с локальными директориями отчетов, HTML-файлами отчетов, databaseUrls.json и удаленными URL отчетов.
npx @testplane/cli test-results ./html-report --status failed
npx @testplane/cli inspect-result ./html-report --name "checkout submits order" --browser chrome
Полезные фильтры:
npx @testplane/cli test-results ./html-report --grep checkout
npx @testplane/cli test-results ./html-report --browser chrome --duration '>5s'
npx @testplane/cli test-results ./html-report --grep-error "NoSuchElement"
npx @testplane/cli test-results ./html-report --meta owner=qa --file 'src/**'
Для больших отчетов или использования в скриптах можно сохранить отфильтрованный набор как JSON:
npx @testplane/cli test-results ./html-report --status failed --save-json
Удаленные отчеты автоматически скачиваются и кэшируются:
REPORT_URL="https://gh-testplane-ci.s3.yandexcloud.net/testplane-ci/e2e-tests-reports/25706755847-557-1/new-ui.html"
npx @testplane/cli test-results "$REPORT_URL" --limit 10 --fields name,status,browser,duration,file
Это позволяет разбирать отчеты CI скриптами из терминала, не открывая сначала полный HTML-интерфейс.
Time Travel snapshots
Если отчет содержит данные Testplane Time Travel, вы можете исследовать DOM в конкретный момент записанного прогона.
npx @testplane/cli time-travel-snapshot ./html-report \
--name "checkout submits order" \
--browser chrome \
--attempt 0 \
--time 250
Вывод включает выбранное время, соседние шаги теста и DOM-снимок воспроизведенной страницы.
Используйте --diff-from, чтобы сравнить два момента:
npx @testplane/cli time-travel-snapshot ./html-report \
--name "checkout submits order" \
--browser chrome \
--time 250 \
--diff-from 100
Также можно напрямую исследовать zip-файл со снимком:
npx @testplane/cli time-travel-snapshot --snapshot-file ./snapshot.zip --time 100
Time Travel особенно полезен, когда падение произошло в CI, а живой браузер уже закрыт. Вы все равно можете посмотреть, как приложение выглядело в момент выполнения теста.
Кастомная конфигурация браузера
Используйте launch, когда нужен видимый браузер, конкретный viewport, mobile emulation или кастомный Selenium grid.
npx @testplane/cli launch --headless false --window-size '{"width":1280,"height":720}'
Пример mobile emulation:
npx @testplane/cli launch --desired-capabilities '{
"browserName": "chrome",
"goog:chromeOptions": {
"mobileEmulation": {
"deviceMetrics": {
"width": 360,
"height": 800,
"pixelRatio": 1
}
}
}
}'
По умолчанию grid-url равен local, что позволяет Testplane автоматически управлять Chrome и Firefox. Для других браузеров запустите драйвер или Selenium grid самостоятельно и передайте его URL:
npx @testplane/cli launch --grid-url http://localhost:4444/wd/hub
Частые сценарии
Отладка селектора:
npx @testplane/cli navigate http://localhost:3000/profile
npx @testplane/cli snapshot --include-attrs data-qa aria-label
npx @testplane/cli click --role button --name "Edit profile"
npx @testplane/cli snapshot
Повторное использование login-state:
npx @testplane/cli navigate http://localhost:3000/login
# Войдите через команды или вручную в видимой сессии
npx @testplane/cli save-state ./tmp/auth-state.json
npx @testplane/cli close-browser
npx @testplane/cli navigate http://localhost:3000/dashboard
npx @testplane/cli restore-state ./tmp/auth-state.json
Разбор отчета CI:
npx @testplane/cli test-results "$REPORT_URL" --status failed --fields name,browser,error
npx @testplane/cli inspect-result "$REPORT_URL" --name "full test name" --browser chrome
npx @testplane/cli time-travel-snapshot "$REPORT_URL" --name "full test name" --browser chrome --time 1000
Подключение после падения теста:
npx testplane tests/checkout.testplane.ts --grep "submits order" --keep-browser
npx @testplane/cli attach --session '{"sessionId":"...","capabilities":{}}'
npx @testplane/cli snapshot
Если сомневаетесь
У каждой команды есть подробная справка и примеры использования — вы всегда можете попросить CLI показать больше информации по любой команде:
npx @testplane/cli --help
npx @testplane/cli click --help
npx @testplane/cli test-results --help