easy-png-tools2/docs/testing-strategy.md

Стратегия e2e-тестирования

Статус: active. Канонические правила для web/e2e/; продуктовые решения и известные баги остаются в docs/backlog.md и docs/checklist-manual-testing.md.

1. Что проверяем

E2E проверяет пользовательский контракт production UI: открытие маршрута, доступность элемента, загрузку или ввод данных, появление результата, ошибку, скачивание и переключение локали. Внутренняя реализация, порядок карточек, CSS-классы и конкретный формат временного URL не являются контрактом.

Точные переводы проверяются в unit-тестах i18n. В e2e проверяется поведение и отдельный RU/EN smoke, а не полный локализованный текст каждого verdict.

2. Приоритет locator-ов

1. getByRole() с доступным именем и getByLabel().
2. Стабильные href или id, если семантического API нет.
3. Разрешённые data-testid только для визуальных границ, которые нельзя надёжно назвать через accessibility API:
   • source-image;
   • result-image;
   • result-verdict;
   • empty-state.
4. input[type="file"] и download-button допускаются только внутри web/e2e/helpers/page.ts.

Нельзя добавлять data-testid для счётчиков, групп, metadata, verdict текста, кнопок темы или переключателя языка без отдельного обоснования.

3. Запрещённые зависимости

В e2e не фиксируются:

• абсолютные TOTAL, GROUPS и другие snapshot-числа каталога;
• точное число fuzzy-search результатов или порядок карточек;
• внутренние CSS-классы и HTML-структура, если есть role/label/href;
• alt как способ найти результат или источник;
• полные локализованные предложения и длинные тире в ожиданиях;
• локализованные имена контролов в общих сценариях без явной установки en.

Поведенческий тест может проверять, что известный инструмент видим или скрыт, ошибка имеет текст и не является сырым i18n-ключом, результат доступен для скачивания. Это не требует повторять словарь в e2e.

4. Локаль и fixtures

Обычные сценарии запускаются с en через useEnglish() или openTool(). RU/EN проверяется отдельным i18n.spec.ts; после смены локали locator не должен зависеть от старого accessible name.

Изображения создаются воспроизводимыми helpers в web/e2e/helpers/fixtures.ts. Тесты не добавляют большие бинарные файлы и не зависят от локальных пользовательских файлов. Runtime-fixtures для malformed/special PNG проверяют browser-контракт: critical CRC и truncated отклоняются движком, ancillary CRC и хвост после IEND допускаются, palette/16-bit декодируются. Отказ декодера — свойство движка, поэтому ожидание задаётся per-engine в web/e2e/png-fixtures.spec.ts, а не через skip. Общее требование для всех движков: битый файл не роняет страницу, отказ показывается alert-ом, а успешный декод даёт результат без ошибки. toPass() допускается только для ограниченного ожидания hydration или асинхронного результата; он не должен превращать проверку продукта в бесконечный retry.

Чистая логика схемы, layout и preview-модели (defaults, sanitization, resolveLayoutGroups, buildSchemaPreviewModel) проверяется в src/**/*.test.ts; DOM, hydration и пользовательские потоки — в Playwright. Component-тесты не дублируют e2e-контракт.

Состав и причины исключений из coverage-гейта, а также пороги — в docs/quality-gates.md; здесь они не дублируются.

5. Helpers и test.fixme

web/e2e/helpers/page.ts владеет общими операциями openTool, uploadImage, renderText, resultImage, sourceImage, verdictStatus, textResult, errorAlert, emptyState, rangeInput, downloadResult, downloadResultFile и downloadResultBytes. Специфика должна вызывать эти helpers, а не повторять raw-селекторы. Harness выбирается по контракту: image — upload + resultImage, text — renderText + результат, generator — auto-run без upload, verdict — verdictStatus, files — отдельный ZIP-сценарий.

test.fixme допускается только для зарегистрированной проблемы в backlog или checklist. В комментарии указывается ссылка на неё. После исправления тест и ссылка обновляются вместе.

Если тест сравнивает два состояния одного элемента, он ждёт изменения значения (not.toHaveText, not.toHaveAttribute), а не его видимости. Пересчёт идёт через debounce, поэтому toBeVisible() после второго ввода проходит на старом значении. Такой тест флакает по таймингу и обычно ловится на CI, а не локально.

6. Проверки

Матрица «изменение → минимальный набор проверок» и состав pnpm verify — в docs/quality-gates.md. Для изменений e2e дополнительно уместны pnpm --dir web check и pnpm --dir web format:check.

verify не включает Playwright: E2E остаётся отдельным тяжёлым gate. В CI non-blocking E2E не считается заменой локальному smoke; перед ревью фиксируются число passed, skipped и известные fixme. Статус e2e в CI — docs/decisions.md, раздел 9.

7. Browser matrix

web/playwright.config.ts запускает четыре проекта:

Проект	Движок	Спецификации
chromium	Chromium	все e2e
firefox	Firefox	tool-flows, png-fixtures, text-and-verdicts
webkit	WebKit	tool-flows, png-fixtures, text-and-verdicts
mobile-chromium	Chromium	navigation, catalog, generators, tool-flows, 390×844, hasTouch

• Название tool-flows.spec.ts описывает содержание: сквозной поток одного инструмента (загрузка → правка параметра → результат → download) на наборе представительных страниц. Пайплайна в коде нет (docs/architecture.md, раздел 1), поэтому спеку нельзя называть pipeline — при её переименовании поправить browserContractTests и mobileTests в web/playwright.config.ts и allowDefaultProject в web/eslint.config.js.

• Рядом живёт tools-smoke.spec.ts — дешёвый проход по выборке страниц («выдал результат без ошибок»): по одной-двум на категорию, а не по каждому инструменту. Остальные страницы закрыты точечными спеками (generators, text-and-verdicts, tool-flows). tool-flows отвечает за более глубокие проверки, tools-smoke — за дешёвый прогон подряд; дублировать их цели не стоит.

• Новые engine-специфичные фичи сначала добавляются в chromium, потом решается, попадает ли spec в browserContractTests.

• Расхождения декодеров не ужесточаются и не скрываются skip-ом: они описаны в тесте как ожидаемое поведение движка.

  Fixture	Отклоняют
  crc-bad-idat.png	Chromium, Firefox
  truncated-header.png	Chromium, Firefox, WebKit
  truncated-no-iend.png	Chromium
  idat-cut.png	Chromium
  ancillary CRC, tail, palette, 16-bit	ни один движок

• workers — 1 локально и 2 в CI: Playwright не умеет per-project лимит воркеров, а browser matrix ограничена памятью, а не CPU. Правила нагрузки на машину и порядок диагностики флаков — docs/agent-workflow.md, раздел 3; обоснование отсутствия per-project таймаутов — docs/decisions.md, раздел 7.

• Visual snapshots и per-project таймауты сознательно не используются — docs/decisions.md, разделы 5 и 7.