test: less fragile - use semantic locators\helpers

2026-11-13 17:08:20 +00:00 · 2026-09-25 17:40:58 +05:00
parent 16d4288912
commit 5313567e70
26 changed files with 436 additions and 274 deletions
@@ -0,0 +1,87 @@
+# Стратегия 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`.
+Тесты не добавляют большие бинарные файлы и не зависят от локальных
+пользовательских файлов. `toPass()` допускается только для ограниченного
+ожидания hydration или асинхронного результата; он не должен превращать проверку
+продукта в бесконечный retry.
+
+## 5. Helpers и `test.fixme`
+
+`web/e2e/helpers/page.ts` владеет общими операциями `openTool`, `uploadImage`,
+`resultImage`, `sourceImage`, `verdictStatus`, `textResult`, `errorAlert`,
+`emptyState`, `rangeInput` и `downloadResult`. Специфика должна вызывать эти
+helpers, а не повторять raw-селекторы.
+
+`test.fixme` допускается только для зарегистрированной проблемы в backlog или
+checklist. В комментарии указывается ссылка на неё; Q4 не исправляет продуктовое
+поведение. После исправления тест и ссылка обновляются вместе.
+
+## 6. Проверки
+
+Для изменений e2e выполняются:
+
+```text
+pnpm --dir web check
+pnpm --dir web test:rules
+pnpm --dir web lint:all
+pnpm --dir web exec prettier --check .
+pnpm check:docs
+pnpm --dir web test:e2e
+pnpm verify
+```
+
+`verify` не включает Playwright: E2E остаётся отдельным тяжёлым gate. В CI
+non-blocking E2E не считается заменой локальному smoke; перед ревью фиксируются
+число passed, skipped и известные fixme.