From 84645cf2e3793ba3f6abd1f0c2e3621d59f9cd7c Mon Sep 17 00:00:00 2001
From: "E.Gavrilov" <gavrilovdev@yandex-team.ru>
Date: Thu, 3 Sep 2026 19:20:07 +0300
Subject: [PATCH] Rewrite editorial article 188

---
 editorial/agent-rewrites/188.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/editorial/agent-rewrites/188.json b/editorial/agent-rewrites/188.json
index c1b3ee7..96da098 100644
--- a/editorial/agent-rewrites/188.json
+++ b/editorial/agent-rewrites/188.json
@@ -1,7 +1,7 @@
 {
   "index": 188,
   "slug": "editorial-2022-10-mechanism-ui-tests",
-  "title": "Механика UI-теста: наблюдаемое состояние вместо случайной паузы",
-  "excerpt": "Как связать действие пользователя, переход состояния и проверяемый результат, чтобы UI-тест объяснял сбой, а не маскировал его ожиданием.",
-  "contentHtml": "<p>UI-тест нажимает «Сохранить», ждёт секунду и иногда падает на проверке результата. На быстрой машине он успевает увидеть новый экран. На занятой машине проверка срабатывает раньше. Если увеличить паузу, тест станет медленнее, но не умнее. Цена ошибки — флак в CI, повторный запуск и потеря доверия к зелёному результату. При настоящем дефекте команда получает сигнал поздно, потому что тест не знает, какого состояния он ждёт.</p>\n<p>Тезис простой: UI-тест должен ждать не время, а наблюдаемое состояние, которое означает завершение пользовательского действия. Страница должна назвать переход. Тест должен проверить это имя через доступную семантику или другой устойчивый контракт. Переход, наблюдение и assertion остаются отдельными слоями. Если их смешать, timeout превращается в замену модели.</p>\n<h2>Механизм: от действия к результату</h2>\n<p>Рассмотрим форму с текстовым полем и кнопкой отправки. Пользователь вводит текст. Состояние формы остаётся <code>editing</code>. После отправки приложение переходит в <code>submitting</code> и связывает попытку с идентификатором запроса. Только подтверждение этой попытки переводит форму в <code>saved</code>. Если подтверждение не пришло или относится к старой попытке, интерфейс показывает <code>recovery-required</code>, а не объявляет успех.</p>\n<p>В этой схеме есть четыре разных факта. Клик сообщает о намерении. Переход меняет модель. UI делает переход видимым. Assertion проверяет видимый результат. Клик не доказывает отправку. Исчезновение кнопки не доказывает сохранение. Истёкшая секунда не доказывает ни один из этих фактов.</p>\n<div class=\"table-scroll\"><table><caption>Что ждёт проверка после отправки формы</caption><thead><tr><th scope=\"col\">Слой</th><th scope=\"col\">Пример</th><th scope=\"col\">Чего он не доказывает</th><th scope=\"col\">Нужная проверка</th></tr></thead><tbody><tr><td>Действие</td><td>Пользователь нажал «Сохранить»</td><td>Ответ принят</td><td>Проверить переход в pending</td></tr><tr><td>Переход</td><td><code>submitting</code> и <code>request-01</code></td><td>Результат виден человеку</td><td>Проверить guard и связь ответа с запросом</td></tr><tr><td>Наблюдение</td><td><code>role=status</code>, имя «Сохранение выполняется»</td><td>Сеть работала без ошибок</td><td>Проверить доступный результат сценария</td></tr><tr><td>Ответ</td><td>Подтверждение с тем же идентификатором</td><td>Любой экран с текстом «Готово» корректен</td><td>Проверить переход в <code>saved</code></td></tr></tbody></table></div>\n<h2>Почему одной переменной loading недостаточно</h2>\n<p>Флаг <code>isLoading</code> отвечает только на вопрос о занятом состоянии. Он не различает первую и вторую попытку, не защищает от двойной отправки и не объясняет, что делать после ошибки. Для асинхронной формы нужен корреляционный признак. В учебном примере это <code>requestId</code>. Первый submit получает <code>request-01</code>. Ответ с <code>request-00</code> считается устаревшим и не меняет экран.</p>\n<p>Тот же guard закрывает повторный submit. Пока состояние равно <code>submitting</code>, второй клик не создаёт новый запрос. В реальном интерфейсе кнопка может стать disabled, но смысл правила должен жить в переходе состояния, а не только в DOM. Иначе другой обработчик или быстрый повторный клик обойдёт визуальную блокировку.</p>\n<p>Отрицательный путь важен не меньше happy path. Если сервер не подтвердил запрос, форма не должна показывать «Сохранено». Она должна сохранить черновик, показать понятное восстановление и дать действие, предусмотренное продуктом: повторить, проверить результат или вернуться к редактированию. Конкретная политика зависит от системы. Тест обязан проверить, что ложного успеха нет.</p>\n<h2>Учебный пример: переходы без браузера</h2>\n<p>Следующий код ограничен локальной моделью. Он не открывает страницу, не отправляет HTTP-запрос и не показывает результат реального продукта. Его задача — сделать инварианты видимыми до написания browser-теста: повторная отправка блокируется, старый ответ игнорируется, отсутствие подтверждения ведёт к восстановлению.</p>\n<pre><code>const state = { phase: 'editing', text: 'Согласовать условия', requestId: null };\n\nfunction submit(current) {\n  if (current.phase === 'submitting') {\n    return { ...current, event: 'submit-blocked' };\n  }\n  return { ...current, phase: 'submitting', requestId: 'request-01' };\n}\n\nfunction acknowledge(current, id) {\n  if (current.phase !== 'submitting' || id !== current.requestId) {\n    return { ...current, event: 'stale-acknowledgement' };\n  }\n  return { ...current, phase: 'saved', event: 'saved' };\n}\n\nfunction fail(current, id) {\n  if (current.phase !== 'submitting' || id !== current.requestId) {\n    return { ...current, event: 'stale-failure' };\n  }\n  return { ...current, phase: 'recovery-required', event: 'recovery' };\n}</code></pre>\n<p>Код намеренно не решает transport, retry и доступность. Он фиксирует границу переходов. После него browser-тест может проверять факты интерфейса: появился статус отправки, второй submit не изменил попытку, корректный ответ показал сохранение, а устаревший ответ не перекрыл новую форму.</p>\n<figure><img src=\"/assets/editorial/2022/ui-tests-2022-observation-route.svg\" alt=\"Схема переходов UI-теста: intent переходит в submitting, подтверждение с совпадающим request id ведёт в saved, устаревший ответ и повторная отправка блокируются, отсутствие подтверждения ведёт в recovery-required\" loading=\"lazy\" /><figcaption>Схема отделяет действие, переход, наблюдение и отрицательный путь. Это учебная модель, а не trace браузера и не результат production-прогона.</figcaption></figure>\n<h2>Как выглядит browser assertion</h2>\n<p>После того как страница получила понятный контракт, assertion выражает пользовательский факт. В Playwright пример может выглядеть так:</p>\n<pre><code>await page.getByRole('button', { name: 'Сохранить' }).click();\nawait expect(page.getByRole('status'))\n  .toHaveText('Сохранение выполняется');\n\n// Контролируемый ответ тестового окружения приходит здесь.\nawait expect(page.getByRole('status'))\n  .toHaveText('Изменение сохранено');</code></pre>\n<p>Вызов <code>toHaveText</code> ждёт условие до установленного timeout. Это полезно только тогда, когда условие связано с переходом, который важен пользователю. Проверка «кнопка исчезла» может пройти из-за закрытия модального окна, ошибки рендера или смены маршрута. Она не заменяет статус результата.</p>\n<p>Выбирайте locator по смыслу. Роль и имя подходят для состояния, которое должен распознать пользователь. <code>data-testid</code> уместен для технического узла, у которого нет пользовательской семантики. Ни один locator не исправит отсутствующий contract. Если экран не различает pending, success и recovery, автоматизация будет угадывать состояние по косвенным признакам.</p>\n<h2>Симптом → причина → проверка → действие</h2>\n<div class=\"table-scroll\"><table><caption>Карта диагностики нестабильной UI-проверки</caption><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td>После click стоит <code>wait(1000)</code></td><td>Нет названного pending-состояния</td><td>Найти видимый результат до и после отправки</td><td>Добавить status и assertion на него</td></tr><tr><td>Тест ждёт исчезновения кнопки</td><td>DOM-признак подменяет бизнес-результат</td><td>Проверить, что будет при server error</td><td>Утвердить success и recovery отдельно</td></tr><tr><td>Два быстрых click создают два эффекта</td><td>Guard живёт только в UI</td><td>Повторить submit в состоянии <code>submitting</code></td><td>Запретить переход и проверить один request id</td></tr><tr><td>Поздний ответ показывает старый успех</td><td>Ответ не связан с попыткой</td><td>Передать устаревший <code>requestId</code></td><td>Игнорировать ответ или отправить его в согласованный recovery-путь</td></tr><tr><td>После ошибки нечего повторить</td><td>Форма очистила черновик до подтверждения</td><td>Проверить текст и snapshot после failure</td><td>Сохранить черновик и назвать действие восстановления</td></tr></tbody></table></div>\n<h2>Порядок действий</h2>\n<ol><li><strong>Запишите симптом.</strong> Сохраните текст падения, действие перед ним и текущий assertion. Не увеличивайте timeout до диагностики.</li><li><strong>Назовите состояния.</strong> Опишите pending, success и recovery словами, которые понимает пользователь.</li><li><strong>Назначьте владельца перехода.</strong> Укажите, какой обработчик создаёт request id, кто принимает ответ и кто меняет видимый статус.</li><li><strong>Проверьте отрицательный путь.</strong> Подайте пустой ввод, повторный submit, устаревший ответ и отсутствие подтверждения.</li><li><strong>Добавьте локальные проверки модели.</strong> Убедитесь, что guard, correlation и rollback не зависят от времени и DOM.</li><li><strong>Настройте контролируемый browser-вход.</strong> В тестовом окружении зафиксируйте разрешённый способ получить success и failure. Не выдавайте локальную модель за e2e.</li><li><strong>Поставьте assertion на observable state.</strong> Проверяйте role, имя и текст результата. Timeout оставьте ограничителем, а не условием успеха.</li><li><strong>Проверьте обратимость.</strong> Если новый contract расходится с UX, откатите его вместе с assertion. Не оставляйте паузу как постоянный обход.</li></ol>\n<h2>Ограничения</h2>\n<p>Модель не знает о re-render, планировщике фреймворка, локализации, авторизации, нескольких вкладках и фактической доставке ответа. <code>request-01</code> — учебное имя, а не требование к production-протоколу. В реальной системе поздний ответ может требовать журнала, повторного чтения данных или server reconciliation, а не молчаливого игнорирования.</p>\n<p>Роль <code>status</code> или <code>alert</code> нельзя добавлять только ради теста. Доступное сообщение должно соответствовать срочности и поведению интерфейса. Источник текста, локализация и фокус требуют отдельной проверки. UI-тест подтверждает выбранный contract, но не сертифицирует всю доступность страницы.</p>\n<p>Учебный пример не доказывает, что флак исчез, не измеряет длительность CI и не сообщает production-результаты. Для такого вывода нужны воспроизводимые запуски, версия браузера и runner, окружение, история падений и правило сравнения. Без этих данных корректно утверждать только то, что assertion теперь ждёт названное состояние.</p>\n<h2>Проверяемый критерий готовности</h2>\n<p>Изменение готово, если один сценарий проходит по четырём наблюдаемым веткам: pending появляется после действия, корректное подтверждение показывает success, повторная отправка не создаёт второй переход, а устаревший или отсутствующий ответ не показывает ложный успех. Для каждой ветки есть assertion на public UI contract. В коде нет произвольной паузы, которая заменяет отсутствующее состояние. Локальные проверки модели и browser-тест имеют явно описанные границы.</p>\n<h2>Проверяемые источники</h2><ul><li><a href=\"https://playwright.dev/docs/test-assertions\" target=\"_blank\" rel=\"noopener noreferrer\">Playwright: Assertions</a> — официальная документация по auto-retrying assertions и условиям, которые проверяются до timeout.</li><li><a href=\"https://www.w3.org/TR/webdriver/\" target=\"_blank\" rel=\"noopener noreferrer\">W3C WebDriver</a> — действующая спецификация интерфейса управления браузером; она не определяет смысл прикладного состояния страницы.</li><li><a href=\"https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html\" target=\"_blank\" rel=\"noopener noreferrer\">W3C WCAG 2.2: Status Messages</a> — официальное описание границы для сообщений о результате, которые не должны незаметно менять контекст пользователя.</li></ul>"
+  "title": "Механика UI-проверки: сделать состояние наблюдаемым",
+  "excerpt": "Как отделить transition, наблюдение и assertion, чтобы не лечить флак произвольным ожиданием.",
+  "contentHtml": "<p>Проблема теста, который ждёт секунду потому, что после клика ему нечего наблюдать, обычно скрыта в самой странице. Внутри меняется несколько флагов, затем кто-то закрывает модалку, а итог пользователю виден только случайно. Цена — флак и дорогая диагностика: лог показывает click, но не показывает, какой transition не состоялся и почему.</p>\n<p>Механика ниже строит один узкий мост: domain transition создаёт named visible state, а assertion проверяет именно его. Это не настоящий Playwright run и не реализация WebDriver. Локальная fixture специально не содержит таймеров, selector-ов, DOM или HTTP, чтобы можно было проверить reason перехода и rollback без истории конкретного браузера.</p>\n<h2>Три слоя, которые нельзя склеивать</h2>\n<p>Первый слой — intent: пользователь ввёл текст или нажал submit. Второй — transition: state machine решила, что переход допустим, и записала request id. Третий — observation: экран получил status либо alert с доступным именем. Когда тест сразу читает внутренний флаг второго слоя, он перестаёт проверять пользовательский результат. Когда он ждёт только время, он не проверяет ни один слой. Нужен явный третий слой, связанный с переходом.</p>\n<div class=\"table-scroll\"><table><caption>Разделение ответственности</caption><thead><tr><th scope=\"col\">Слой</th><th scope=\"col\">Хранит</th><th scope=\"col\">Не должен утверждать</th><th scope=\"col\">Проверка</th></tr></thead><tbody><tr><td>Intent</td><td>ввод и click</td><td>что сохранение принято</td><td>событие доступно пользователю</td></tr><tr><td>Transition</td><td>phase и request id</td><td>что браузер уже отрисовал результат</td><td>guard и matching acknowledgement</td></tr><tr><td>Observation</td><td>role, name, testState</td><td>что сеть работала</td><td>assertion пользовательского сценария</td></tr><tr><td>Транспорт</td><td>запрос и reply</td><td>смысл UI без mapping</td><td>отдельный API-contract</td></tr></tbody></table></div>\n<h2>Почему request id входит в учебную модель</h2>\n<p>Если confirmation приходит после submit, модели недостаточно boolean <code>isLoading</code>. Ей нужно знать, какую попытку она ждёт. Первый <code>submit</code> создаёт <code>request-01</code>; acknowledgement с <code>request-00</code> отвергается. После rollback счётчик не возвращается назад: повторный submit получает <code>request-02</code>, а запоздалый reply от первой попытки остаётся чужим. Это не утверждение о формате production ID и не требование передавать именно такое поле по сети. Это способ записать invariант: старый reply не может признать текущий transition.</p>\n<p>Дальше работает guard. Повторный submit во время <code>submitting</code> возвращает <code>submit-guard-active</code> и не создаёт второй request id. Такой исход важен именно как наблюдаемая граница: кнопка в реальном UI может стать disabled, но смысл должен жить не только в button. Иначе пользовательский сценарий будет зависеть от timing отрисовки, а компонент-автоматизация найдёт обходной путь.</p>\n<h2>Пример: local fixture проверяет owner перехода</h2>\n<p>Ниже нет <code>page.click</code>, <code>locator</code> или sleep. Вызовы создают намерение, планируют transition и вручную передают acknowledgement. Проверка не измеряет задержку: она смотрит на shape evidence и на <code>testState</code>. Если заменить order событий, stale acknowledgement не сдвигает сценарий; если сделать rollback, состояние возвращается к snapshot. Это удобный first gate перед настоящим UI.</p>\n<pre><code>import { runUiTestsFixture } from &#039;./upgrade-2022-10.mjs&#039;;\nconst report = runUiTestsFixture();\nif (!Object.values(report.assertions).every(Boolean)) throw new Error(&#039;fixture contract failed&#039;);\nconsole.log(report.evidence.planned.observation.testState); // &#039;submitting&#039;\nconsole.log(report.evidence.accepted.observation.name); // &#039;Изменение сохранено&#039;</code></pre>\n<p>После failure fixture возвращает pre-submit snapshot: <code>editing</code> с черновиком, без request id и без сохранённого результата. При этом счётчик запросов не откатывается. Поэтому повторный submit получает новый id, а поздний <code>request-01</code> не может подтвердить вторую попытку. Это не метрика надёжности и не готовая политика production rollback. Это узкая защита от модели, которая после возврата случайно принимает старый reply за текущий успех.</p>\n<figure><img src=\"/assets/editorial/2022/ui-tests-2022-observation-route.svg\" alt=\"Схема разделения UI-проверки: intent submit создаёт transition submitting с request id; accessible status становится наблюдением; acknowledgement с совпадающим id переводит в saved; stale reply и повторный submit не меняют переход; recovery выводится отдельным alert.\" loading=\"lazy\" /><figcaption>Рисунок отделяет модель переходов от инструмента автоматизации и не показывает настоящий DOM или WebDriver-сеанс.</figcaption></figure>\n<h2>Как писать browser assertion после контракта</h2>\n<p>После модели assertion должен выражать пользовательский факт, например: после действия есть status с именем «Отправка ожидает подтверждения», а после контролируемого ответа — status «Изменение сохранено». В Playwright-документации v1.27.0 retrying assertion повторяет проверку выбранного условия до timeout. Поэтому timeout — ограничитель ожидания условия, не само условие. Если condition выбран как «кнопка где-то исчезла», инструмент добросовестно ждёт неправильный факт.</p>\n<p>Стабильный selector допустим, если он не подменяет семантику. Для чисто технического контейнера можно применять <code>data-testid</code>; для результата сценария лучше сначала искать роль и имя, которые уже нужны человеку. Это не абсолютное правило: составной виджет, локализация и визуально скрытый status потребуют отдельного решения. Важно зафиксировать, какой contract должен пережить рефакторинг, а какой selector является внутренней деталью.</p>\n<h2>Маршрут: симптом → причина → проверка → действие</h2>\n<ol><li><strong>Симптом.</strong> В отчёте есть timeout либо sleep между click и проверкой, но не видно нужного состояния.</li><li><strong>Причина.</strong> Intent, transition и observation склеены: тест знает click, но не знает owner результата.</li><li><strong>Проверка.</strong> Найдите phase, request id и текст/role результата. Если одного нет, тесту нечего ждать корректно.</li><li><strong>Действие.</strong> Добавьте named status для pending/saved и alert для recovery; свяжите их с transition в одном месте.</li><li><strong>Проверка guard.</strong> Локально подтвердите duplicate submit и stale reply. Fixture не заменяет browser тест.</li><li><strong>Rollback.</strong> Откатывайте весь новый contract вместе с тестом, если доступное состояние расходится с утверждённой UX-копией; не возвращайте sleep как постоянный патч.</li></ol>\n<h2>Ошибки внедрения</h2>\n<p>Первая ошибка — назвать все состояния <code>loading</code>. Пользователь не отличит ожидание подтверждения от повторной попытки, а тест не отличит новый запрос от старого reply. Вторая — очищать форму сразу после click. Тогда rollback нечего восстанавливать. Третья — делать success индикатор побочным эффектом network callback без проверки request id. В такой схеме поздний callback способен сообщить о старой операции поверх нового редактирования.</p>\n<p>Четвёртая ошибка — добавить <code>aria-live</code> или role только ради теста. WCAG 2.1, критерий 4.1.3, требует, чтобы сообщения о состоянии можно было определить программно и передать вспомогательным технологиям без перевода фокуса. Это не даёт универсального шаблона: роль должна соответствовать срочности и поведению интерфейса. Полный accessibility-аудит реализации остаётся отдельной задачей.</p>\n<h2>Ограничение и следующий шаг</h2>\n<p>Учебная модель не знает re-render, framework scheduler, локализацию, авторизацию, несколько вкладок и фактическую доставку reply. Она не говорит, что любой stale reply следует молча отбросить: production может потребовать журнал, server reconciliation или повторное чтение данных. Фиксированная строка request id и ручной acknowledgement существуют только для детерминированной fixture.</p>\n<p>Следующий шаг — взять один настоящий тест и нарисовать его timeline без времени: intent, pending observation, controlled response, final observation. Отдельно обозначьте fail path. Если на этой схеме нет наблюдаемого условия после click, сначала добавьте contract страницы. Только потом заменяйте sleep на auto-retrying assertion выбранного инструмента.</p>\n<h2>Историческая граница октября 2022</h2>\n<p>Техническая граница построена на immutable Playwright documentation commit v1.27.0, WebDriver Working Draft от 25 октября 2022 года и WCAG 2.1 Recommendation. Ни один из документов не является доказательством того, что локальная fixture открывала страницу или что конкретный UI обладает заявленной доступностью.</p>\n<h2>Проверяемые источники</h2><ul><li><a href=\"https://github.com/microsoft/playwright/blob/af0d2936ac6e8780214c251ff58a5e7d6eba41ca/docs/src/test-assertions-js.md\" target=\"_blank\" rel=\"noopener noreferrer\">Playwright: test assertions, commit af0d2936 (7 октября 2022)</a> — неизменяемый исходный документ версии v1.27.0, опубликованной 7 октября 2022 года. Описывает retrying assertion до условия или timeout; статья не запускает Playwright.</li><li><a href=\"https://www.w3.org/TR/2022/WD-webdriver2-20221025/\" target=\"_blank\" rel=\"noopener noreferrer\">W3C WebDriver, Working Draft 25 октября 2022 года</a> — датированный Working Draft, доступный в октябре 2022 года. Он задаёт remote-control interface, но не определяет смысл прикладного состояния страницы.</li><li><a href=\"https://www.w3.org/TR/2018/REC-WCAG21-20180605/\" target=\"_blank\" rel=\"noopener noreferrer\">W3C WCAG 2.1, Recommendation 5 июня 2018 года</a> — нормативная Recommendation, доступная к октябрю 2022 года. Используется для критерия 4.1.3 и границы: статус должен быть программно определимым, а статья не заявляет conformance конкретной страницы.</li></ul>"
 }