Запуск через CLI

Урок: Запуск через CLI — фильтры, отладка и CI в Playwright Test

Введение

Когда ты только начинаешь работать с Playwright, чаще всего ты запускаешь тесты одной командой:

npx playwright test

И кажется, что этого достаточно. Но довольно быстро появляется новая реальность:

тестов становится много;
запуск всех тестов занимает время;
нужно прогнать только один файл или даже один тест;
нужно разобраться, почему тест падает;
нужно запускать тесты в CI (например, в GitHub Actions).

И тут становится понятно: важен не только код тестов, но и то, как ты их запускаешь.

CLI (Command Line Interface) — это основной инструмент управления запуском тестов. Через него ты можешь:

фильтровать, какие тесты запускать;
включать режим отладки;
управлять браузером;
адаптировать запуск под CI.

Если конфигурация — это «правила», то CLI — это «пульт управления».

Базовая команда запуска

Начнём с основы:

npx playwright test

По официальной документации именно эта команда запускает все тесты, используя файл конфигурации playwright.config. (playwright.dev)

Что происходит:

Playwright находит конфиг;
читает testDir;
собирает все тесты;
запускает их согласно настройкам (projects, use, retries и т.д.).

Это полный прогон проекта.

Запуск конкретного файла или папки

Когда тестов становится много, запускать всё каждый раз неудобно.

CLI позволяет запускать конкретные файлы:

npx playwright test tests/login.spec.ts

Или даже папку:

npx playwright test tests/auth

Что происходит:

Playwright фильтрует тесты по пути;
запускает только подходящие файлы.

Это базовый и самый часто используемый способ ускорить работу.

Фильтрация по названию теста (`-g`)

Иногда нужен не файл, а конкретный тест.

Для этого используется флаг -g (grep).

npx playwright test -g "логин"

Playwright запустит только те тесты, в названии которых есть слово "логин". Документация описывает это как фильтрацию по регулярному выражению. (playwright.dev)

Пример теста:

test('пользователь может залогиниться', async ({ page }) => {
  // ...
});

Команда:

npx playwright test -g "залогиниться"

Запустит только этот тест.

Это особенно полезно:

при отладке;
при работе над конкретной фичей;
когда тестов сотни.

Запуск в конкретном проекте (`--project`)

Если у тебя есть projects, можно запускать тесты только в одном из них.

npx playwright test --project=chromium

Или:

npx playwright test --project=mobile

Что это даёт:

тесты не гоняются во всех браузерах;
быстрее локальная разработка;
можно проверять конкретное окружение.

Режим отладки (`--debug`)

Когда тест падает, обычного лога часто недостаточно.

Для этого есть режим отладки:

npx playwright test --debug

По документации этот режим включает:

headed режим (браузер с UI);
замедление выполнения;
встроенные инструменты отладки. (playwright.dev)

Что ты получаешь:

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

Пауза в коде (`page.pause()`)

CLI — это не единственный способ отладки.

Можно прямо в тесте поставить паузу:

test('пример', async ({ page }) => {
  await page.goto('/');
  await page.pause();
});

И запустить:

npx playwright test

Тест остановится, и откроется инспектор.

Это позволяет:

исследовать DOM;
пробовать селекторы;
вручную выполнять действия.

Очень полезно при сложных сценариях.

Запуск в UI-режиме (`--ui`)

Playwright предоставляет удобный интерфейс для запуска тестов:

npx playwright test --ui

По документации это интерактивный режим, где можно:

выбирать тесты;
запускать их по одному;
смотреть результаты;
отлаживать. (playwright.dev)

Это похоже на IDE для тестов.

Когда использовать:

при обучении;
при исследовании тестов;
при сложной отладке.

Запуск с trace и логами

Для более глубокой диагностики используют trace:

npx playwright test --trace on

Или:

npx playwright test --trace retain-on-failure

Trace позволяет:

посмотреть шаги теста;
увидеть скриншоты;
отследить network-запросы.

Это один из самых мощных инструментов Playwright.

Повторы и стабильность (`--retries`)

Иногда тесты падают нестабильно.

Можно временно задать повторы:

npx playwright test --retries=2

Это полезно:

для CI;
при нестабильной среде;
для диагностики flaky-тестов.

Но важно: это не решение проблемы, а инструмент.

Управление количеством воркеров (`--workers`)

Playwright запускает тесты параллельно.

Можно управлять этим:

npx playwright test --workers=1

Когда это нужно:

при отладке;
если тесты мешают друг другу;
на слабых машинах.

Запуск в CI

Теперь важный момент — CI (Continuous Integration).

В CI тесты:

запускаются автоматически;
должны быть стабильными;
не должны зависеть от интерфейса.

Обычно используют:

npx playwright test

Но с учётом конфигурации:

retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,

CLI тут играет ключевую роль:

он запускается в пайплайне;
читает конфиг;
выполняет тесты без участия человека.

Headless режим через CLI

Иногда нужно явно указать режим браузера:

npx playwright test --headed

Это противоположность headless.

Полезно:

при визуальной отладке;
при демонстрации.

Комбинирование параметров

CLI становится особенно мощным, когда ты комбинируешь параметры:

npx playwright test tests/login.spec.ts -g "успешный логин" --project=chromium --debug

Что делает эта команда:

запускает конкретный файл;
фильтрует тест по названию;
использует только Chromium;
включает режим отладки.

Это уже точечный инструмент, а не просто запуск.

Практический смысл

На практике CLI — это твой основной инструмент работы с тестами.

Ты постоянно используешь его, чтобы:

быстро запускать нужные тесты;
отлаживать падающие сценарии;
проверять изменения;
управлять запуском в CI.

Без CLI работа с Playwright превращается в медленный и неудобный процесс.

С CLI ты получаешь:

скорость;
гибкость;
контроль.

Итоговое понимание

Главная идея этой темы в том, что запуск тестов — это не просто команда, а управляемый процесс.

CLI Playwright даёт тебе полный контроль:

ты выбираешь, что запускать;
ты управляешь условиями запуска;
ты включаешь инструменты отладки;
ты адаптируешь тесты под CI.

Если конфигурация задаёт правила игры, то CLI — это способ гибко управлять этими правилами в каждый конкретный момент.

Именно поэтому умение работать с CLI — это не дополнительный навык, а основа эффективной работы с Playwright Test.