Запуск тестов Playwright из CLI: флаги, фильтры и отладка

Базовая команда

npx playwright test

Запускает все тесты из testDir (обычно ./tests) во всех проектах определённых в playwright.config.ts.

Фильтрация тестов

По файлу или папке

# Все тесты в конкретном файле
npx playwright test tests/login.spec.ts

# Все тесты в папке
npx playwright test tests/api/

# Несколько файлов
npx playwright test tests/login.spec.ts tests/dashboard.spec.ts

По имени теста (--grep)

# Тесты с "login" в названии
npx playwright test --grep "login"

# Тесты по регулярному выражению
npx playwright test --grep "login|registration"

# Инверсия: тесты которые НЕ совпадают
npx playwright test --grep-invert "flaky"

Строка сравнивается с полным заголовком теста включая имя блока describe. "Login page > shows error" совпадёт с --grep "error" и с --grep "Login page".

По тегу

Если тесты используют теги:

test('smoke test @smoke', async ({ page }) => { ... });

npx playwright test --grep "@smoke"

По проекту (браузеру)

# Только Chrome
npx playwright test --project=chromium

# Только Firefox и WebKit
npx playwright test --project=firefox --project=webkit

Режимы запуска

Headed (видимый браузер)

npx playwright test --headed

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

Slow motion

npx playwright test --headed --slow-mo=500

Добавляет задержку 500 мс между действиями. Хорошо подходит для записи демо или отладки проблем с таймингом.

UI Mode (интерактивный режим)

npx playwright test --ui

Открывает интерактивный UI Playwright: отладчик с перемоткой времени. В нём можно:

• Просматривать все тесты в боковой панели
• Запускать отдельные тесты
• Смотреть таймлайн каждого действия
• Видеть DOM-снимки на каждом шаге
• Инспектировать сетевые вызовы

Лучший инструмент отладки в Playwright. Используй когда нужно разобраться в непонятном падении.

Debug Mode

npx playwright test --debug

Ставит паузу перед первым действием и открывает Playwright Inspector. Можно шагать по действиям по одному и вводить команды Playwright в консоли инспектора в интерактивном режиме.

Для конкретного теста:

npx playwright test tests/login.spec.ts --debug

Codegen (запись нового теста)

npx playwright codegen https://lab.becomeqa.com

Открывает браузер где действия записываются. Сгенерированный Playwright-код появляется в окне инспектора. Копируй в тест-файл.

Параллельный запуск

Количество воркеров

# 4 параллельных воркера
npx playwright test --workers=4

# Последовательно (1 воркер)
npx playwright test --workers=1

Шардирование (для CI с несколькими машинами)

# Разбить тесты на 4 шарда, запустить шард 1 на машине 1
npx playwright test --shard=1/4

# Запустить шард 2 на машине 2
npx playwright test --shard=2/4

Каждый шард запускает подмножество тестов. Общее время делится на количество шардов (приблизительно).

Ретраи

# Повторять упавшие тесты до 3 раз
npx playwright test --retries=3

Обычно ретраи задаются в playwright.config.ts, но флаг CLI переопределяет конфиг.

Репортеры

Выбор репортера

# List (живой вывод в консоль)
npx playwright test --reporter=list

# HTML-репорт
npx playwright test --reporter=html

# Dot (минимальный вывод)
npx playwright test --reporter=dot

# Несколько репортеров
npx playwright test --reporter=html,list

Открыть последний HTML-репорт

npx playwright show-report

Открывает playwright-report/index.html в браузере. Визуальный отчёт со всеми результатами тестов, скриншотами, трейсами и видео.

Объединение шардированных репортов

После запуска шардированных тестов объединяй репорты:

npx playwright merge-reports --reporter html ./blob-reports

Trace Viewer

Просмотр записанного трейса (.zip файл из упавшего теста):

npx playwright show-trace trace.zip

Или из HTML-репорта: кликни "Trace" на любом упавшем тесте.

Полезные комбинации

# Отладка конкретного упавшего теста
npx playwright test tests/checkout.spec.ts --grep "payment fails" --debug

# Только smoke-тесты в Chrome, headed
npx playwright test --grep "@smoke" --project=chromium --headed

# Все тесты с одним ретраем, подробный вывод
npx playwright test --retries=1 --reporter=list

# Быстрая проверка: один воркер, максимум 5 тестов
npx playwright test --workers=1 --max-failures=5

# Запуск с другим конфиг-файлом
npx playwright test --config=minimal.config.ts

# Список всех тестов без запуска
npx playwright test --list

Переменные окружения через CLI

Можно передавать переменные окружения напрямую:

BASE_URL=https://staging.myapp.com npx playwright test

Или несколько сразу:

BASE_URL=https://staging.myapp.com ENV=staging npx playwright test

Доступны в конфиге и тестах через process.env.BASE_URL.

Справочник флагов

| Флаг | Что делает |

|------|-----------|

| --headed | Показывает окно браузера |

| --debug | Пауза и открытие инспектора |

| --ui | Интерактивный UI-режим |

| --slow-mo=N | Задержка N мс между действиями |

| --grep "pattern" | Фильтр тестов по имени |

| --grep-invert "pattern" | Исключить тесты по имени |

| --project=name | Запуск конкретного проекта (браузера) |

| --workers=N | Количество параллельных воркеров |

| --retries=N | Повторять упавшие тесты N раз |

| --shard=X/Y | Запустить шард X из Y |

| --reporter=type | Формат вывода |

| --timeout=N | Переопределить таймаут теста (мс) |

| --max-failures=N | Остановить после N падений |

| --list | Список тестов без запуска |

| --config=file | Использовать другой конфиг-файл |

| --pass-with-no-tests | Не падать если тестов не найдено |

Скрипты в package.json

Добавь частые команды как npm-скрипты чтобы коллеги не запоминали флаги:

{
  "scripts": {
    "test": "npx playwright test",
    "test:headed": "npx playwright test --headed",
    "test:debug": "npx playwright test --debug",
    "test:ui": "npx playwright test --ui",
    "test:smoke": "npx playwright test --grep @smoke",
    "test:chrome": "npx playwright test --project=chromium",
    "test:report": "npx playwright show-report",
    "test:ci": "npx playwright test --reporter=list,junit"
  }
}

Тогда любой может запустить npm run test:smoke не зная флаг grep.

CLI стоит освоить хорошо. Связка --grep, --debug и --ui резко ускоряет отладку: точно тот упавший тест, точно в том режиме который нужен для разбора.