{
  "index": 158,
  "slug": "editorial-2023-08-mechanism-e2e-stability",
  "title": "Почему e2e-тест проходит на retry: четыре контракта устойчивого сценария",
  "excerpt": "Timeout в e2e-тесте не объясняет причину. Разбираем locator, actionability, пользовательский результат и retry, чтобы отличать настоящий дефект от замаскированного падения.",
  "contentHtml": "<p>В CI тест нажимает «Сохранить», получает timeout, а со второй попытки проходит. В отчёте он получает статус flaky. Команда увеличивает timeout и закрывает задачу. Через неделю тот же сценарий падает уже на другом шаге. Цена ошибки — не только красный pipeline: команда теряет время на повторы, пропускает дефект интерфейса или данных и начинает считать зелёный retry доказательством исправности.</p>\n<p>Устойчивость e2e-сценария нельзя свести к одному таймауту. В нём действуют четыре разных контракта: locator выбирает нужный элемент, actionability разрешает действие, assertion подтверждает пользовательский результат, а retry описывает повторный запуск. Если смешать эти уровни, диагностика превращается в перебор чисел. Если разделить их, место отказа становится проверяемым.</p>\n<h2>Симптом начинается раньше TimeoutError</h2>\n<p>Одинаковая ошибка ожидания может возникнуть по разным причинам. Locator может найти ноль элементов или несколько. Кнопка может быть видимой, но перекрытой анимацией. Click может успешно отправить событие, а сервер — вернуть ошибку. Сохранение может завершиться, но тест ждёт исчезновения spinner, который скрывается и при успехе, и при отказе. При retry меняются worker, состояние браузера и иногда подготовленные данные.</p>\n<p>Первый вопрос здесь не «какой timeout поставить?», а «какой контракт не выполнен?». Отделите поиск элемента, проверку готовности действия, ожидание результата, подготовку данных и повтор. У каждого слоя должна быть своя ошибка и свой следующий шаг.</p>\n<h2>Четыре контракта одного теста</h2>\n<table><thead><tr><th>Контракт</th><th>Что он проверяет</th><th>Чего он не доказывает</th></tr></thead><tbody><tr><td>Locator</td><td>Тест обращается к нужному пользовательскому элементу и ожидает понятное число совпадений.</td><td>Что операция завершилась успешно.</td></tr><tr><td>Actionability</td><td>Элемент найден, видим, стабилен, получает события и включён для выбранного действия.</td><td>Что приложение приняло действие или записало данные.</td></tr><tr><td>Readiness</td><td>После действия появился наблюдаемый terminal state: статус, строка результата или изменённое значение.</td><td>Что именно этот locator был причиной успеха.</td></tr><tr><td>Retry</td><td>Runner повторил тест и получил новый outcome в другом запуске.</td><td>Что первая ошибка была случайной, а исправление найдено.</td></tr></tbody></table>\n<p>Playwright автоматически ждёт проверки actionability перед действиями. Для <code>click()</code> он проверяет, что locator разрешается ровно в один элемент, элемент видим, стабилен, получает события и включён. Стабильность означает, что геометрия элемента не меняется на последовательных кадрах. Получение событий означает, что другой элемент, например overlay, не перехватит клик. Это защищает от клика по исчезнувшему или перекрытому control, но не знает смысла продукта.</p>\n<p>После успешного <code>click()</code> библиотека не может сама решить, что считать сохранением. Для профиля это может быть сообщение «Сохранено» и новое значение поля. Для импорта — строка с terminal state и числом обработанных записей. Spinner, enabled-кнопка и отсутствие сетевой активности могут быть промежуточными признаками. Их нельзя выдавать за бизнес-результат без проверки сценария.</p>\n<h2>Locator должен описывать интерфейс, а не разметку</h2>\n<p>Хороший locator связан с тем, как пользователь воспринимает control: ролью, доступным именем, label или устойчивым тестовым идентификатором. Селектор по случайному классу или позиции в списке может пройти сегодня и сломаться после перестановки DOM. Но и role-based locator не магический: две кнопки с одним доступным именем — это неоднозначный контракт, а не повод добавить <code>nth(0)</code>.</p>\n<p>Проверяйте cardinality отдельно, когда она важна. <code>await expect(save).toHaveCount(1)</code> сообщает, что на странице ровно одна кнопка с выбранным locator. После этого <code>click()</code> может всё ещё не пройти: control способен быть disabled или закрыт overlay. Разные отказы оставляют разную подсказку для исправления.</p>\n<h2>Учебный пример: действие и postcondition</h2>\n<p>Фрагмент ниже самодостаточен как форма теста, но не подключён к реальному профилю. Пути, label и тексты — проектные значения; в рабочем тесте их нужно заменить на фактический пользовательский контракт. Важен порядок: ввод, проверка уникальности locator, действие, затем ожидание результата.</p>\n<pre><code>import { test, expect } from '@playwright/test';\n\ntest('user saves profile', async ({ page }) =&gt; {\n  await page.goto('/profile');\n\n  const email = page.getByLabel('Почта');\n  const save = page.getByRole('button', { name: 'Сохранить' });\n  const status = page.getByRole('status');\n\n  await email.fill('user@example.test');\n  await expect(save).toHaveCount(1);\n  await expect(save).toBeEnabled();\n  await save.click();\n\n  await expect(status).toHaveText('Сохранено');\n});</code></pre>\n<p><code>getByLabel()</code> и <code>getByRole()</code> выражают пользовательское представление интерфейса. <code>toHaveCount()</code> ловит неоднозначный locator до действия. <code>click()</code> ждёт техническую готовность кнопки. <code>toHaveText()</code> — web-first assertion: он повторяет проверку, пока условие не выполнено или не истечёт timeout. Если сервер вернул ошибку, тест должен упасть на postcondition, а не пройти потому, что кнопка была кликабельной.</p>\n<p>Не подменяйте postcondition ручной паузой. <code>waitForTimeout(2000)</code> иногда маскирует медленный UI, а иногда лишь откладывает отказ. Не ждите исчезновения spinner, если он исчезает и при ошибке. Не используйте <code>force: true</code>, пока не доказано, что перекрытие не является дефектом интерфейса: этот флаг отключает часть проверок actionability и может превратить реальную проблему в зелёный тест.</p>\n<h2>Retry создаёт новый запуск, а не новое доказательство</h2>\n<p>По умолчанию Playwright Test не повторяет упавшие тесты. При включённых retry runner запускает тест снова до достижения лимита. Playwright Test работает с worker-процессами. Если тест падает, worker вместе с браузером отбрасывается; повтор начинается в новом worker, где hooks могут выполниться заново. Поэтому retry способен убрать утечку состояния, изменить порядок подготовки данных или повторить cleanup. Это объясняет различие условий, но не выбирает причину автоматически.</p>\n<p>Категория <code>flaky</code> означает только последовательность «первая попытка упала, повторная прошла». Она не означает «дефект случайный», «сеть была медленной» или «правка сработала». Сохраните initial error, retry outcome, входные данные, worker и cleanup. Иначе отчёт оставит только удобный ярлык.</p>\n<p>Для CI удобно записывать trace на первой повторной попытке. Такой trace содержит историю именно записанного запуска: действия, снимки DOM и сетевой контекст. Он полезен для анализа retry, но не восстанавливает отсутствующий trace initial attempt. Если причина могла проявиться только в первой попытке, включите режим, который сохраняет evidence и для неё, либо соберите отдельный воспроизводимый запуск.</p>\n<h2>Минимальная конфигурация и команды</h2>\n<p>В конфигурации ниже оставлена одна повторная попытка: этого достаточно, чтобы увидеть разницу между initial и retry, но недостаточно, чтобы объявить тест стабильным. Значение <code>retries</code> — политика запуска, а не лечение теста.</p>\n<pre><code>import { defineConfig } from '@playwright/test';\n\nexport default defineConfig({\n  retries: process.env.CI ? 1 : 0,\n  use: {\n    trace: 'on-first-retry',\n  },\n});</code></pre>\n<p>Запустите один тест без параллельного шума и сохраните отчёт:</p>\n<pre><code>npx playwright test tests/profile.spec.ts --workers=1 --retries=1\nnpx playwright show-report\n# Если trace сохранён в test-results, откройте конкретный архив:\nnpx playwright show-trace test-results/&lt;test-name&gt;/trace.zip</code></pre>\n<p>Путь <code>test-results/&lt;test-name&gt;/trace.zip</code> в последней команде условный: имя каталога зависит от проекта и репортера. Команда воспроизводима после подстановки фактического пути из отчёта. Для локального расследования, когда retry не нужен, можно временно запустить <code>npx playwright test tests/profile.spec.ts --workers=1 --trace on</code>, но режим записи каждого запуска дороже по времени и месту.</p>\n<p>Номер попытки можно добавить в evidence:</p>\n<pre><code>test('user saves profile', async ({ page }, testInfo) =&gt; {\n  console.log(JSON.stringify({\n    retry: testInfo.retry,\n    worker: testInfo.workerIndex,\n    title: testInfo.title,\n  }));\n\n  await page.goto('/profile');\n  await page.getByRole('button', { name: 'Сохранить' }).click();\n  await expect(page.getByRole('status')).toHaveText('Сохранено');\n});</code></pre>\n<p>Лог не доказывает причину отказа, но связывает наблюдение с попыткой. Это особенно полезно, когда одинаковый тест выполняется в нескольких browser project или на разных shard.</p>\n<h2>Симптом → причина → проверка → действие</h2>\n<table><thead><tr><th>Симптом</th><th>Версия причины</th><th>Проверка</th><th>Безопасное действие</th></tr></thead><tbody><tr><td>Timeout на click</td><td>Locator пустой, множественный, перекрыт или disabled.</td><td>Проверьте count, видимость, стабильность и получение событий.</td><td>Уточните scope или исправьте UI/данные, если control недоступен.</td></tr><tr><td>Click прошёл, assertion истёк</td><td>Ожидается не тот результат или UI не сообщает terminal state.</td><td>Назовите факт, который должен увидеть пользователь после операции.</td><td>Добавьте assertion на этот факт или согласуйте UI-контракт.</td></tr><tr><td>Initial failed, retry passed</td><td>Утечка данных, порядок тестов, внешний сервис или скрытая готовность.</td><td>Сравните входы, worker, cleanup, browser project и attempt.</td><td>Изолируйте данные и устраните причину; не увеличивайте retry.</td></tr><tr><td>Тест проходит только с waitForTimeout</td><td>Сценарий не ждёт наблюдаемое событие.</td><td>Уберите паузу в изолированной ветке и найдите первый terminal state.</td><td>Замените паузу на locator/assertion с ясным сообщением.</td></tr><tr><td>Trace ничего не объясняет</td><td>Артефакт относится к retry, а вопрос относится к initial.</td><td>Проверьте attempt, test title, project и момент записи.</td><td>Соберите evidence обеих попыток или отдельный повтор с нужным trace mode.</td></tr></tbody></table>\n<h2>Данные и окружение часто меняются вместе с retry</h2>\n<p>Свежий browser context не делает внешние данные свежими. Если тест меняет одну и ту же учётную запись, записи могут пересекаться между worker и параллельными запусками. Если cleanup выполняется только после успеха, retry стартует с другим состоянием. Если серверная очередь или партнёрский API отвечает асинхронно, DOM может быть готов раньше результата операции.</p>\n<p>Сначала зафиксируйте границы изоляции. Для каждого теста задайте уникальный идентификатор сущности или подготовьте её через API; cleanup сделайте идемпотентным; состояние, которое нельзя очищать, проверяйте перед повтором. В лог запишите correlation id, но не секреты и персональные данные. Отдельно сравните локальный запуск, CI worker и browser project: одинаковый код не означает одинаковое окружение.</p>\n<p>Если тест зависит от внешнего сервиса, разделите два вопроса. UI-тест проверяет пользовательский контракт на контролируемом ответе, а интеграционный сценарий отдельно проверяет реальное взаимодействие. Один retry не отличает дефект приложения от временной недоступности партнёра.</p>\n<h2>Порядок разбора</h2>\n<ol><li><strong>Зафиксируйте симптом.</strong> Сохраните test title, browser project, шаг, initial error, retry outcome и ссылку на отчёт. Формулировки «иногда падает» недостаточно.</li><li><strong>Определите фазу.</strong> Отделите locator, actionability, postcondition, подготовку данных, внешний сервис и retry.</li><li><strong>Проверьте locator.</strong> Убедитесь, что он выражает пользовательский смысл, работает в нужном scope и возвращает ожидаемое число элементов.</li><li><strong>Назовите readiness.</strong> Запишите terminal state, который доказывает успех. Сверьте его с тем, что увидит пользователь при ошибке сервера.</li><li><strong>Сравните попытки.</strong> Сопоставьте данные, worker, cleanup, browser project, конфигурацию и порядок действий. Retry рассматривайте как новый запуск.</li><li><strong>Свяжите evidence с attempt.</strong> Trace, screenshot, log и network запись должны иметь понятный test title и номер попытки. Отсутствующий artefact не заменяйте предположением.</li><li><strong>Сделайте один diff.</strong> Меняйте один слой: locator, assertion, изоляцию данных или политику evidence. Зафиксируйте owner и rollback.</li><li><strong>Проверьте отрицательный путь.</strong> Ошибка сервера, неоднозначный locator и отсутствие readiness должны давать разные понятные отказы.</li><li><strong>Повторите на свежих данных.</strong> Прогоните сценарий с той же конфигурацией, а затем отдельно проверьте другой browser project или внешний dependency, если они входят в область риска.</li></ol>\n<figure><img src=\"/assets/editorial/2023/e2e-stability-2023-wait-contract.svg\" alt=\"Схема четырёх контрактов e2e-теста: locator выбирает элемент, actionability разрешает клик, readiness подтверждает результат, retry создаёт новый запуск\" loading=\"lazy\" /><figcaption>Каждый следующий слой проверяет отдельный факт. Evidence привязан к конкретной попытке и не превращает успешный retry в доказательство причины.</figcaption></figure>\n<h2>Ограничения применимости</h2>\n<p>Модель не делает любой тест стабильным. User-facing locator может быть корректным, но приложение — показывать неверный статус. Web-first assertion может ждать правильный DOM-факт, но серверная запись ещё не завершится. Изоляция browser context не очищает базу, очередь или внешний сервис. Retry помогает обнаружить различие между запусками, но не заменяет расследование.</p>\n<p>Примеры используют API Playwright Test и синтетические значения. Они не измеряют flake rate, latency, стоимость CI, совместимость браузеров или качество тестовых данных. Версии Playwright, Node.js, браузеров, project config и runner нужно проверять в своём lockfile и CI-образе. Документация меняется, поэтому для исторического разбора закрепляйте версию пакета и сверяйте поведение с release notes этой версии.</p>\n<p>Не объявляйте тест исправленным после одного зелёного повтора. Нужны как минимум повторяемый сценарий, понятный отрицательный путь, evidence initial/retry и проверка того слоя, который был изменён. Если данных для вывода нет, корректный результат расследования — «причина не установлена», а не повышение timeout.</p>\n<h2>Критерий готовности</h2>\n<p>Разбор готов, когда команда может ответить на пять вопросов: что упало в initial, что прошло в retry, какой locator использовался, какой пользовательский результат ожидался и какое evidence относится к каждой попытке. После правки отдельный запуск проверяет тот же результат на свежих данных, а отрицательный путь завершается ожидаемой ошибкой.</p>\n<p>Для временного исключения нужны owner, срок пересмотра и условие снятия. Для постоянной правки нужны малый diff и понятный rollback. Один зелёный retry этому критерию не соответствует. Соответствует контракт, в котором тест различает готовое действие, подтверждённый результат, состояние данных и условия повторного запуска.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://playwright.dev/docs/actionability\" target=\"_blank\" rel=\"noopener noreferrer\">Playwright: Auto-waiting</a> — официальная таблица actionability для click, auto-retrying assertions и поведение force.</li><li><a href=\"https://playwright.dev/docs/locators\" target=\"_blank\" rel=\"noopener noreferrer\">Playwright: Locators</a> — официальные рекомендации по locator и пользовательским признакам элемента.</li><li><a href=\"https://playwright.dev/docs/test-retries\" target=\"_blank\" rel=\"noopener noreferrer\">Playwright: Retries</a> — worker-процессы, retries и категории passed/flaky/failed.</li><li><a href=\"https://playwright.dev/docs/trace-viewer\" target=\"_blank\" rel=\"noopener noreferrer\">Playwright: Trace viewer</a> — запись trace, режим on-first-retry и команды show-report/show-trace.</li><li><a href=\"https://github.com/microsoft/playwright/releases/tag/v1.37.0\" target=\"_blank\" rel=\"noopener noreferrer\">Playwright v1.37.0 release</a> — официальный релиз для сверки исторического контекста статьи за август 2023 года.</li></ul>"
}