Ревью только что написанных или изменённых автотестов на соответствие best practices TypeScript + Playwright (по официальной документации) и конвенциям вашего проекта. Используй по /test-review либо после написания/правки любого теста (UI E2E, API, UI+API, моки, visual, mobile) или Page Object/фикстуры/констант — до коммита. Выдаёт приоритизированный список замечаний с severity, привязкой к строкам и готовыми фиксами.
Ревью только что написанных или изменённых автотестов на соответствие best practices TypeScript + Playwright (по официальной документации) и конвенциям вашего проекта. Используй по /test-review либо после написания/правки любого теста (UI E2E, API, UI+API, моки, visual, mobile) или Page Object/фикстуры/констант — до коммита. Выдаёт приоритизированный список замечаний с severity, привязкой к строкам и готовыми фиксами.
Проверь только что написанный или изменённый тест-код на соответствие best practices и выдай приоритизированный список замечаний с фиксами. Источник правил — официальная документация Playwright (best-practices, locators, test-assertions) и TypeScript + конвенции конкретного проекта.
Источник правды по проекту — его корневой CLAUDE.md (если есть) и стиль соседнего кода. Этот скилл — фаза проверки: он дополняет проектные правила, не заменяет их. Развёрнутые ❌ до → ✅ после и ссылки на источники по каждому правилу — в references/rules-catalog.md.
Когда применять и режим работы
Режим по умолчанию — диагностика. Прочитать код, прогнать статический анализ, выдать отчёт. Файлы не править, пока пользователь явно не попросит «применяй / чини». Тогда — итеративно, по одному изменению с прогоном между ними (не big-bang переписывание рабочего теста).
Scope — только новое/изменённое, не весь suite. По умолчанию — незакоммиченные изменения (git status + git diff). Если пользователь указал файл/папку — ревьюй их.
Любой тип теста: UI E2E, API, UI+API, visual regression, mobile, моки, а также Page Object, фикстуры, константы.
Не уходи в автономные действия за пределами ревью (воспроизведение через браузер, прогон всего suite, правки) без подтверждения — задача по умолчанию «прочитать и оценить».
Доказательная дисциплина (без галлюцинаций)
Каждое замечание — по реально прочитанной строке (file:line) или по наблюдённому выводу typecheck / lint / прогона. Не выдумывай нарушения «по аналогии» и не ссылайся на строки, которых не видел.
Правило проверяется инструментом (tsc, ESLint, прогон) → сначала запусти инструмент, потом репорти его вывод, а не «вероятно есть».
Не уверен, что это дефект, а не осознанное решение проекта → помечай «под вопросом», не утверждай. Сверяйся с CLAUDE.md проекта и соседним кодом: часть «анти-паттернов» может быть намеренной (легаси-хелперы, нестандартная разметка, осознанные исключения из правил). Имена файлов/эндпоинтов/селекторов из памяти и прошлого контекста — фон, перепроверяй на живом коде.
Не нашёл нарушений в категории — так и пиши «чисто», не придумывай замечание ради объёма.
Процесс
Scope. Определи файлы под ревью: git status --short + git diff --name-only (учитывай untracked), либо переданные пути. Для каждого spec найди связанные Page Object'ы, константы, фикстуры.
Контекст.Read изменённых файлов + связанных POM/констант/фикстур. Read соседнего spec в той же папке как эталон стиля. Сверь правила директории/сьюта (smoke / regress / api и т.п.) по CLAUDE.md проекта, если он есть.
Статический анализ (обязательно — дёшево и доказательно):
Typecheck: tsc --noEmit (или typecheck-скрипт проекта из package.json). Любая ошибка типов в новом коде = 🔴 Blocker.
ESLint: найди конфиг проекта и прочитай, какие правила реально включены (особенно из eslint-plugin-playwright) — не предполагай по памяти. Вывод линта — источник правды.
Что реально ловит линт — проверка двухуровневая. (1) Плагина eslint-plugin-playwright нет вообще → floating promise, ручные ассерты и networkidle невидимы; предложи подключить recommended. (2) Recommended подключён → missing-playwright-await, prefer-web-first-assertions, no-networkidle уже error и ловятся, но no-wait-for-timeout, no-force-option и expect-expect там только warn (сверено по v2.10.5) — без --max-warnings 0 эти предупреждения не валят CI. Предложи поднять их до error. @typescript-eslint/no-floating-promises требует type-aware линтинга — включён мало у кого. Что осталось вне линта — проверяй вручную (A/C/H).
При необходимости — проверка форматирования (Prettier), если настроена в проекте.
Чеклист. Пройди категории A–J ниже + K (правила вашего проекта). На каждое нарушение — severity + file:line + фикс. Глубже по правилу — references/rules-catalog.md.
Верификация стабильности (только если пользователь просит убедиться, что тест рабочий, и есть sandbox): прогон только этого теста в нативном параллелизме проекта (НЕ --workers=1):
npx playwright test <file> --grep "<id>" --project="<projectName>" --retries=0 --repeat-each=5
Pass-на-ретрае или плавающий результат = флак = 🟠 Major, чинить причину (гонки/гидратация/ожидания), а не прятать за retries.
Отчёт — в формате из раздела «Формат отчёта».
Severity
Метка
Значение
Типичные примеры
🔴 Blocker
Тест сломан, недетерминирован или маскирует баг. Не мержить.
Ошибка typecheck; пропущенный await (floating promise); waitForTimeout/in-page setTimeout-пауза; pass только на ретрае; { force: true } / dispatchEvent / прямой setter в обход реального UI; тест без ассертов; test.only; условный expect, который может не выполниться.
🟠 Major
Хрупкость или флак при смене контента/окружения; нарушение ключевого правила проекта.
CSS/XPath-цепочки вместо role/label; мгновенный count()/isVisible()/allTextContents() как gate; точные цены/тексты/даты вместо regex; нарушение конвенции проекта (импорт базового @playwright/test там, где проект требует кастомную фикстуру; пропущена обязательная проектная проверка — напр. монитор сетевых ошибок); waitForLoadState('networkidle'); тест зависит от состояния другого.
🟡 Minor
Стиль/читаемость/поддерживаемость; на стабильность не влияет.
Нет test.step по бизнес-шагам; инлайн-комментарии вместо самодокументирования; .nth() где годится .filter(); рабочий, но не приоритетный локатор; неиспользуемый импорт/константа.
⚪ Nit
Косметика.
Именование, порядок импортов, форматирование (если не ловит Prettier).
Чеклист ревью
Каждый пункт — что искать; в скобках — severity нарушения. Развёрнутые примеры и пруфы — в каталоге.
A. Детерминизм, ожидания, асинхронность
Нет page.waitForTimeout(ms) и нет setTimeout/sleep внутри page.evaluate (грепни оба). Ждать состояние, не время. (🔴)
Нет «висящих» промисов: каждый expect, test.step, действие (click/fill/goto), waitFor* — под await/return/void. Пропущенный await = молчаливый флак. (🔴)
Сеть — паттерн promise → действие → await: const p = page.waitForResponse(...); await click(); await p. Объявление после действия = гонка. (🔴)
Нет waitForLoadState('networkidle'). Навигация — goto(url, { waitUntil: 'domcontentloaded' }), без дублирующего waitForLoadState следом. (🟠)
Производные/составные проверки (несколько связанных условий, замер коллекции сразу после появления) — в await expect(async () => {...}).toPass({ timeout }), а не цепочка await-ов. (🟠)
Учтена SSR-гидратация: SSR-фреймворки (Nuxt/Next и др.) могут перемонтировать контент после гидратации → мгновенный count()/allTextContents() сразу после появления ловит окно пустоты. Замер через toPass. (🟠)
B. Локаторы
Приоритет: getByRole({ name }) → getByText → getByLabel → getByPlaceholder → getByAltText → getByTitle → getByTestId → CSS (крайний случай) → XPath (почти никогда). (🟠 при CSS/XPath без причины)
Нет хрупких CSS-цепочек по структуре DOM (div > div > span, .episode-actions-later). Ломаются при ребрендинге. (🟠)
Strict mode: локатор резолвится в один элемент; уточнение через { name } / .filter({ hasText }) / .filter({ has }), а не .nth(). .nth() — только с обоснованием. (🟡)
Плавающие элементы (дропдауны, тосты, модалки, портальный контент, iframe) ищутся глобально от page, не от секции. (🟠)
Длинный getByText('целое предложение') не используется как якорь — хрупко к правкам копирайта; брать стабильный фрагмент/role. (🟡)
C. Ассерты
Только web-first (авто-ретрай): toBeVisible/toHaveText/toHaveCount/toHaveValue/toBeChecked/toHaveAttribute/toHaveURL. Нет expect(await loc.isVisible()).toBe(true) и expect(await loc.count()).toBe(n) — не ретраятся. (🔴/🟠)
Каждый тест что-то проверяет (нет теста, который только кликает без expect). (🔴)
Блок независимых проверок одной секции — через expect.soft, чтобы собрать все падения разом. (🟡)
Нет ассертов на точные цены/числа/даты/динамический контент — regex или диапазон. (🟠)
Известный незакрытый баг — test.fail() (с единственным баг-ассертом), не test.fixme(); рабочее поведение — отдельным обычным тестом. (🟡)
D. Изоляция и независимость
Тесты независимы: состояние НЕ передаётся между тестами. let x на уровне describe, переинициализируемый в beforeEach, — распространённый валидный паттерн; нарушение — когда тест читает результат другого. Прогон в одиночку и в любом порядке должен проходить. (🔴 если ломает изоляцию)
describe.configure({ mode: 'serial' }) — только при реальной зависимости, не «на всякий случай». (🟠)
Setup/teardown — в beforeEach/фикстурах, без копипасты; созданные сущности (API) удаляются. (🟠)
Тест не зависит от внешних сайтов и third-party виджетов — тестируем только то, что контролируем; внешнее — мок/проверка факта запроса. (🟠)
E. TypeScript и линт
Typecheck зелёный для нового кода (tsc --noEmit, strict). (🔴)
any в POM / fixtures / utils — нежелателен, типизируй (Locator/Page/Route/APIResponse). Сверь с конфигом проекта: any может быть осознанно разрешён в спеках (напр. для мок-данных) — тогда там не флагай. @ts-ignore — только с причиной/тикетом. (🟠 для POM/utils)
Поля POM — readonly Locator; фикстуры типизированы (base.extend<{...}>); тело ответа API типизируй явно, если на него опираются ассерты. (🟡)
Пропущенный await линт часто НЕ ловит (проверь конфиг: есть ли no-floating-promises / missing-playwright-await; valid-expect покрывает лишь часть) → перечитай глазами, см. A2. (🔴)
Сверь модульную систему (ESM vs CJS) и стиль импортов (относительные vs алиасы) с фактическим кодом проекта — следуй существующему стилю, не навязывай свой. Неиспользуемые импорты/переменные/константы/методы POM убрать. (🟡)
F. Сеть и моки
Моки (page.route) — только для edge cases (5xx, пустой ответ, таймаут, офлайн). Позитивный happy-path — против реального API. (🟠)
Проверка контракта, где это суть теста: waitForResponse (статус + тело) / waitForRequest + postDataJSON(). Для форм — инспекция payload на [object Object], пустые/несериализованные поля, а не «кнопка активна». (🟠)
Роуты ставятся до триггерящего действия; область — тест/фикстура, не глобально на suite. (🟠)
Внешний хост, который может не отвечать (напр. внешний личный кабинет, платёжный шлюз): переход не проверяем «вглубь» — оракул это инициированный навигационный запрос + route.abort(), иначе pending-навигация подвешивает teardown. (🟠)
G. Структура, читаемость, гигиена
Логические шаги обёрнуты в test.step('Императив', …) (видно в Allure/HTML/trace). return — снаружи коллбэка. Не дробить на каждое действие. (🟡)
Нет инлайн-комментариев в тестах — самодокументирование (осмысленные имена, semantic-локаторы, шаги). Контекст — в описании/аннотации репортера (напр. allure.description), если проект их использует. (🟡)
Параметризация однотипных кейсов через for...ofснаружиtest.describe, а не копии теста. (🟡)
Нет test.only, закомментированных тестов, временных файлов/черновиков, отладочных console.log/page.pause(). (🔴 для test.only/page.pause, иначе 🟡)
Имена тестов/шагов осмысленны; формат ID/тегов (@allure.id:N, ключ ТК и т.п.) — как у соседних тестов в файле. (⚪)
H. Маскировка багов и флак
Нет синтетических обходов реального UX: { force: true }, dispatchEvent, прямой React/Vue-setter, ручной скролл вместо авто-actionability — если только это не оправдано контролируемым input'ом (напр. кастомные display:none инпуты — проверь в браузере). Фикс должен ловить регрессию, если фича сломается, а не прятать её. (🔴)
retries/mode: serial/увеличенный timeout не используются как «лекарство» от флака. Карантин допустим только временно, со ссылкой на тикет. (🟠)
try/catch не глушит падения действий/ассертов (auto-waiting встроен; .catch() прячет баг). (🟠)
Пред-релизный тест (написан до выката фичи) падает честно, не спрятан за skip/флагом. (🟠)
I. Спецслучаи по типу теста
API: проверяется статус И тело; идентификаторы запросов — свежий randomUUID() из встроенного crypto на каждый запрос (не тащи пакет uuid, если его нет в проекте); учтён rate limit; cleanup созданного. (🟠)
iframe:frameLocator; контент ищется внутри фрейма. Новый таб:context.waitForEvent('page'). Download:waitForEvent('download') + проверка имени. Upload:setInputFiles. Время:page.clock. Геолокация/права:grantPermissions/setGeolocation. (🟠 при ручных обходах)
visual:toHaveScreenshot с animations:'disabled' и mask на динамику; эталоны — на платформе CI (macOS-эталон против Linux-CI = гарантированный diff). Только если тест-кейс требует эталон. (🟠)
J. Соответствие намерению (оракул реально проверяет заявленное)
Тест проверяет то, что обещает имя/описание, а не суррогат. «Валидация формы» → инспекция реального payload, не только «кнопка активна». «Загрузка ещё» → реальная догрузка и сверка, не только клик. (🟠)
Привязка к контенту структурная (наличие, непустота, count > 0, regex), чтобы тест пережил смену копирайта/цен — особенно для регрессов после фикса. (🟠)
Оракул адекватен ограничению окружения: где UI не различает 404/5xx (одна заглушка на оба) — проверка сетевая, не «увидел текст ошибки». (🟠)
K. Правила вашего проекта (шаблон — заполните под свой репозиторий)
У зрелого тест-репозитория всегда есть конвенции, которые не проверит ни один универсальный чеклист. Зафиксируйте их здесь или в CLAUDE.md проекта — тогда ревью будет ловить их нарушения. Типовые категории с примерами:
Кастомные фикстуры: где импортировать test из кастомной фикстуры (./fixtures/custom-test) вместо @playwright/test, и какие обязательные проверки она даёт (напр. монитор сетевых ошибок, вызываемый в конце теста / в afterEach). (🟠)
Паттерны директорий: чем отличаются правила smoke / regress / api сьютов — композиция vs фикстуры для POM, репортер-аннотации, testMatch/testIgnore, куда добавлять новые тесты. (🟠)
Окружения: тест и POM проверены на всех целевых стендах, не только на одном (DOM на тест-стенде может отличаться от прода); известные особенности стендов зафиксированы списком. (🟠)
Skipped-гигиена: тест не добавляет постоянных skipped в штатные прогоны; окружение-специфичное исключается конфигом (testIgnore/testMatch), runtime test.skip — только для динамических условий (фича-флаг, известный баг с тикетом). Итог прогона: passed = ок, failed = проблема, skipped = требует объяснения. (🟡)
Зависимости/конфиг: не бампать версию @playwright/test и не добавлять зависимости без сверки с CI (Docker-образ, lock-файл); не трогать playwright.config.ts без необходимости. (🔴 если затронуто без запроса)
Формат отчёта
## Ревью: <файлы / scope>
**Статический анализ:** typecheck ✅/❌ · lint ✅/❌ · (прогон: N/N pass, --repeat-each=5)
### 🔴 Blocker (N)
1. `path/to/spec.ts:42` — <что не так>.
Почему: <ссылка на правило/категорию>.
Фикс:
```ts
// ❌ было / ✅ стало
🟠 Major (N)
…
🟡 Minor (N)
…
⚪ Nit (N)
…
✅ Что хорошо
<что соответствует best practice — кратко>
Вердикт
<Готов к коммиту / К доработке: список Blocker+Major> · <команда для прогона с правильным --project>
Правила:
- Сортировка строго по severity (Blocker → Nit). Внутри — по файлу/строке.
- Каждый Blocker/Major — с конкретным фиксом (сниппет `❌ было → ✅ стало`).
- Чисто в категории — пиши «чисто», не выдумывай.
- В конце — однострочный вердикт и команда запуска с верным `--project`.
- Если просили применить фиксы — делай **итеративно** (одно изменение → typecheck/прогон → следующее), не переписывай рабочий тест целиком.
