Когда E2E-тест падает, особенно на CI, куда нельзя зайти руками, вопрос не "что было на экране", а "что происходило шаг за шагом". Скриншот - это фотография места аварии: он показывает конечное состояние, но не путь к нему. Playwright даёт нечто гораздо более сильное - trace, полную запись прогона, по которой падение можно разобрать постфактум, как будто вы стояли рядом. Именно trace, а не скриншот, - главный инструмент диагностики.

Инструментов отладки несколько, и у каждого своя роль. npx playwright test --ui открывает UI Mode - интерактивный режим, где видно дерево тестов, шаги и снимки, удобно гонять и разбирать локально. Флаг --debug запускает Inspector с пошаговым выполнением. --headed показывает реальный браузер вместо фонового. show-report открывает HTML-отчёт прогона, а show-trace - конкретный trace-файл. Каждая команда отвечает на свой вопрос отладки.

Отдельно стоит codegen - генератор сценариев. npx playwright codegen с адресом открывает браузер и записывает ваши действия в код теста, попутно подбирая локаторы. Это быстрый способ нащупать правильный локатор и набросать путь, но именно набросок: сгенерированный сценарий почти всегда требует доработки, о которой скажем ниже. Codegen экономит время на старте, а не выдаёт готовый профессиональный тест.

Сердце диагностики - Trace Viewer. Он показывает timeline прогона, снимки DOM на каждом шаге, сетевые запросы, вывод консоли, исходник теста и сами шаги - всё синхронизировано во времени. По trace упавшего теста видно не только где он упал, но и что предшествовало: какой был DOM, что пришло по сети, что писала консоль. Это превращает разбор загадочного CI-падения из гадания в чтение записи.

Полезно один раз собрать команды отладки в одном месте, чтобы не вспоминать их под давлением сломанного прогона. Ниже - набор: UI Mode, отладка конкретного файла, headed-режим, открытие отчёта и trace, генератор. К этой карте возвращаются, когда тест упал и нужно быстро выбрать инструмент под конкретный вопрос - разобрать trace, воспроизвести локально или нащупать локатор.

Ключевая настройка trace на CI - баланс между пользой и стоимостью. Записывать trace каждого теста дорого: это заметно замедляет прогон и раздувает артефакты, а нужен trace в основном у падений. Поэтому оптимальный старт - trace: 'on-first-retry': trace записывается только когда тест упал и пошёл на повторную попытку. Так подробная запись есть ровно там, где она нужна для разбора, и не тратится на тысячи успешных прогонов.