Практические заметки: создание инструмента Agentic Playwright Harness для корпоративных интерфейсов

В этом руководстве показано, как пройти путь от сырья до готовой системы для создания инструмента Agentic Playwright Harness для автоматизации пользовательских интерфейсов в корпоративных средах. Основное внимание уделяется выполнимым шагам, четким проверкам и коду, который можно просто добавить в репозиторий без необходимости догадываться о его назначении. На этапе обзора необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат с самого начала помогает избежать неожиданных счетов при переходе от демо-среды к общедоступным средам.

Проблема, которую мы решали

При работе над этапом «Проблема, с которой мы столкнулись», сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает избегать ошибок при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает часы.

Use the harness to add manager role CRM coverage.

check MCP access,
inspect existing coverage,
use Playwright Agents or capture workflows,
reuse framework layers,
run focused tests,
update the graph,
and report evidence.

Ежедневный рабочий процесс

При работе над этапом «Ежедневный рабочий процесс» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Задокументируйте одновременно успешный и восстановительный сценарии работы. Повторные попытки, проверки со стороны человека и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка занимает часы.

Prompt: create tests for manager role flow
  -> check whether MCP is available and allowed
  -> if yes, use official Playwright Agents for exploration or healing
  -> if no, use capture workflows and Playwright CLI evidence
  -> in both paths, follow the same harness standards
  -> verify with npx playwright test

Режим 1: MCP доступен

При работе над этапом Mode 1 MCP Available сначала запишите условия взаимодействия: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули большим скриптам. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает гораздо больше времени. При работе над этапом Mode 1 MCP Available сначала запишите условия взаимодействия: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Регистрируйте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

Official Playwright Agents
  + MCP browser context
  + Harness standards
  + Playwright test verification
  = faster generation with team governance

Режим 2: MCP недоступен

Механизм режима 2 с отсутствием MCP работает наилучшим образом, когда его рассматривают как измеримую поверхность. Сначала соберите один образец успешной работы, один пример сбоя и записку о возврате к предыдущему состоянию, прежде чем расширять объем работы. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Обеспечьте доступ к инструментам с узкими схемами и четкими метками побочных эффектов. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.

Prompt
  + local context files
  + capture workflows
  + playwright-cli snapshots
  + npx playwright test
  + trace/report evidence
  = no-MCP agentic Playwright workflow

Потоки сбора данных: практический уровень CLI

Рабочие процессы захвата: практический этап работает наилучшим образом, если рассматривать его как измеримую поверхность. Сначала зафиксируйте один идеальный пример обработки, один случай сбоя и записку о возврате к предыдущему состоянию, прежде чем расширять объем работ. Документируйте одновременно успешный и восстановительный пути выполнения. Повторные попытки, проверки со стороны людей и обработка некорректных сообщений являются частью продукта, а не этапом последующей доработки. Обеспечьте доступ к инструментам с узкими схемами и четкими метками о побочных эффектах. У операторов должна быть возможность узнать, какие вызовы изменяют состояние системы, прежде чем они автоматически одобрят операцию.

playwright-cli open http://127.0.0.1:4173/login
playwright-cli localstorage-set ...
playwright-cli goto http://127.0.0.1:4173/crm/accounts
playwright-cli snapshot --filename=contexts/captures/crm-manager-accounts-loaded.yml

npm run capture:recipes:generate
npm run capture:recipe -- --list
npm run capture:crm:manager -- --dry-run
npm run capture:crm:manager

Первый день, второй день и далее

Этап Day 1 Day 2 работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Используйте инструменты с узкими схемами и чёткими метками побочных эффектов. У операторов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят действия. Этап Day 1 Day 2 работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам.

День 1: Добавление нового потока

Для первого дня добавьте этап «Add A», определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне обработки данных. Один только токен-носитель не является границей тенантов.

Create manager role flow tests and assert which buttons are accessible and not
accessible.

День 2: Запуск существующих тестов

Для этапа «Выполнение на второй день» определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно успешный и аварийный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не этапом последующей доработки. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне данных. Один только токен-носитель не является границей аренды.

npm test
npm run test:smoke
APP_BASE_URL=http://127.0.0.1:4173 npm run sample:crm:test

Позже: обновлять только то, что изменилось

Только для последующего обновления: перед изменением кода необходимо определить этап, входные данные, ответственного за шаг и критерии завершения. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную цепочку операций. Аутентифицируйтесь у шлюза и повторно авторизуйтесь на уровне данных. Один только токен-носитель не является границей между тенантами. Только для последующего обновления: перед изменением кода необходимо определить этап, входные данные, ответственного за шаг и критерии завершения. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения, стоимость токена или запроса вместе с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам.

Failure on manager reports page
  -> inspect Playwright output and trace
  -> check existing reports capture
  -> refresh manager reports capture if stale
  -> fix the owning layer
  -> rerun the focused test

Уровни фреймворка

При работе над этапом уровней фреймворка сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает избегать ошибок при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Фиксируйте название инструмента, хэш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает часы.

Layer                                           Purpose
AGENTS.md and .github/copilot-instructions.md   Tell agents how to behave
contexts/*.yml                                  Store command, strategy, graph, loop, and capture rules
contexts/capture-recipes.yml                    Defines repeatable capture workflows as YAML recipes
contexts/captures/                              Stores curated page context
specs/                                          Human-readable flow plans
fixtures/                                       Shared setup, auth, browser context, page instantiation
pages/                                          Locators and user actions
assertions/                                     Reusable web-first expectations
data/                                           Test data builders
tests/                                          Executable Playwright specs
graphs/                                         Generated source, coverage, duplicate, and visual reports

Интеллект графа с учетом исходного кода

При работе над этапом Source-Aware Graph Intelligence сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Задокументируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка агента занимает часы.

npm run source:manifest -- --root=path/to/app --output=source-manifest.json --url=http://localhost:3000 --name=my-app

scripts/source-adapters/generic-source.mjs

generic scanner creates baseline manifest
  -> agent reviews source, tests, captures, and graph gaps
  -> agent enriches missing auth, roles, states, and workflow intent
  -> capture workflow becomes curated reusable page context
  -> Playwright tests verify behavior
  -> graph reports remaining gaps and duplicate risks

npm run source:manifest:crm
npm run source:manifest:crm:check

npm run graph:view

graphs/index.html#coverage
graphs/index.html#candidates
graphs/index.html#inputs

Пример: улучшена покрытость ролей менеджера

При работе над этапом оценки покрытия роли менеджера примеров сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Оцените уровень воспроизведения ответов на фиксированном наборе вопросов перед настройкой подсказок. Частая смена подсказок редко помогает улучшить качество поиска. При работе над этапом оценки покрытия роли менеджера примеров сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость в использовании токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

Before graph
  -> identify missing manager coverage
  -> generate/update manager capture workflow
  -> capture manager page states
  -> add page-object and assertion helpers
  -> add manager role tests
  -> rerun graph

Пример приложения для тестирования CRM:

Этап примерного приложения для тестирования CRM работает наилучшим образом, если рассматривать его как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Обеспечьте доступ к инструментам с узкими схемами и четкими метками о побочных эффектах. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.

Как команды могут это внедрить

Этап «Как команды могут внедрить изменения» работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный и восстановительный сценарии работы. Повторные попытки, проверки со стороны людей и обработка некорректных сообщений являются частью продукта, а не этапом последующей доработки. Обеспечьте доступ к инструментам с узкими схемами и чёткими метками о побочных эффектах. Администраторам необходимо знать, какие вызовы изменяют состояние системы, прежде чем они автоматически одобрят их.

Этап 1: Добавление инструкций для агентов

Этап «Добавление агента» первой фазы работает наилучшим образом, если рассматривать его как измеримую сферу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Используйте инструменты с узкими схемами и чёткими метками о побочных эффектах. У операторов должна быть возможность узнать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят действия. Этап «Добавление агента» первой фазы работает наилучшим образом, если рассматривать его как измеримую сферу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам.

Фаза 2: Согласование рамок Playwright Framework

На этапе 2 «Синхронизация» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Конфигурацию следует хранить отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф. Аутентификация происходит на шлюзе, а повторная авторизация — на уровне обработки данных. Один только токен-носитель не является границей между тенантами.

specs/
tests/
fixtures/
pages/
assertions/
data/
contexts/captures/

Этап 3: Добавление рабочих процессов захвата

Для этапа добавления захвата на третьей фазе необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Необходимо задокументировать как успешный, так и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Аутентификация происходит на шлюзе, а повторная авторизация — на уровне данных. Один только токен-носитель не является границей между тенантами.

npm install -g @playwright/cli@latest

npm run capture:recipes:generate
npm run capture:recipe -- --list
npm run capture:crm:manager -- --dry-run
npm run capture:crm:manager

Фаза 4: Добавление проверки графа

На этапе Phase 4 Add Graph необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной функцией, а не с запутанной структурой обработки данных. Аутентификация происходит на входе, а повторная авторизация — на уровне обработки данных. Одного только токена недостаточно для определения границ использования ресурсов. На этапе Phase 4 Add Graph необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения, стоимость токенов или запросов. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам.

npm run graph:view

Этап 5: Использование тех же команд в CI

При работе над этапом «Использование стадии» сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает избегать ошибок при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Фиксируйте название инструмента, хэш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает часы.

npm run typecheck
npm test
npm run test:smoke
npm run graph:view

Примеры запросов, которые могут использовать команды

При работе над примерами запросов, которые могут использоваться командами, сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный сценарии работы. Повторные попытки, проверки со стороны людей и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки. Храните в кэше стабильные инструкции системы и схемы инструментов. Пересылка одинаковых данных является распространенной причиной избыточных ресурсов.

Use the harness to add coverage for this role-based business flow.

check MCP access
refresh or read the source manifest
inspect existing specs, tests, captures, and graph coverage
use MCP agents or the relevant capture workflow
reuse framework layers
run focused Playwright tests
update the graph
report evidence

Use the harness to debug this failing test.

inspect Playwright output, trace, and artifacts
check existing captures for the affected page or state
refresh source manifest or affected capture only if stale
fix the owning layer
rerun focused verification

Use the harness to review missing coverage.

refresh or read the source manifest
run graph view
identify missing role, state, route, capture, and assertion coverage
check duplicate risks
recommend next flows
avoid creating tests unless asked

Use the harness to refactor repeated selectors and assertions.

inspect existing tests, page objects, and assertion helpers
preserve behavior
move repeated selectors to page objects
move repeated expectations to assertion helpers
run typecheck and focused tests
update graph if coverage ownership changed

Что получают команды

При работе над этапом «Что получают команды» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Зафиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает много времени. При работе над этапом «Что получают команды» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

Заключение

Этап «Заключительные размышления» работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Обеспечьте доступ к инструментам с узкими схемами и чёткими метками о побочных эффектах. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.

prompt
  -> mode router
  -> context
  -> capture workflow or MCP exploration
  -> framework layers
  -> Playwright verification
  -> evidence
  -> graph feedback

Справочные материалы

Этап справочных материалов работает наилучшим образом, когда его рассматривают как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ.

Чек-лист операционной деятельности

Этап чек-листа операционной деятельности работает наилучшим образом, когда его рассматривают как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ.

Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым документам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задач.

Показывайте инструменты с узкими схемами и четкими метками побочных эффектов. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически согласятся на их выполнение.

Вводите ручное утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты функционала для бизнеса.

Напишите краткий руководство: как обновлять ключи, как опустошать очередь, как откатывать последнюю загрузку данных.

Документируйте как успешный, так и восстановительный пути работы. Повторные попытки, ручное утверждение и обработка некорректных сообщений являются частью продукта, а не дополнительными улучшениями.

Перед внедрением стека заморозьте версии, сохраните эталонный отчет для критически важных процессов и убедитесь в наличии шагов для отката. В совместных средах необходимы ограничения на частоту запросов, проверки принадлежности и четко определенный ответственный за обновление секретов. Лучше надежность без изысков, чем красивые одноразовые демонстрации.

Примечание к пакету fa507de22687: не включайте ключи поставщиков в репозиторий, установите лимит токенов на сессию и храните транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.