Агенты Playwright Test

Введение​

Playwright поставляется с тремя готовыми агентами Playwright Test: 🎭 planner, 🎭 generator и 🎭 healer.

Этих агентов можно использовать независимо друг от друга, последовательно или в виде цепочки вызовов в агентном цикле. Их последовательное использование обеспечит покрытие вашего продукта тестами.

• 🎭 planner исследует приложение и создает план тестирования в формате Markdown
• 🎭 generator преобразует план в формате Markdown в файлы Playwright Test
• 🎭 healer запускает набор тестов и автоматически исправляет упавшие тесты

Начало работы​

Начните с добавления определений агентов Playwright Test в проект с помощью команды init-agents. Эти определения нужно создавать заново при каждом обновлении Playwright, чтобы получать новые инструменты и инструкции.

npx playwright init-agents --loop=vscode

npx playwright init-agents --loop=claude

npx playwright init-agents --loop=codex

npx playwright init-agents --loop=opencode

примечание

Для корректной работы агентных функций в VS Code требуется VS Code v1.105 (выпущенная 9 октября 2025 года).

После создания агентов вы можете использовать любой удобный вам инструмент ИИ, чтобы поручить им создание тестов Playwright.

🎭 Planner​

Агент Planner исследует приложение и создает план тестирования для одного или нескольких сценариев и пользовательских потоков.

Входные данные

• Четкий запрос для planner (например, «Составь план для оформления заказа гостем».)
• seed test, который подготавливает среду, необходимую для взаимодействия с приложением
• (необязательно) Документ с требованиями к продукту (PRD) для контекста

Запрос

• Обратите внимание, что seed.spec.ts включен в контекст planner.
• Planner запустит этот тест, чтобы выполнить всю необходимую для тестирования инициализацию, включая глобальную настройку, зависимости проекта и все необходимые фикстуры и хуки.
• Planner также будет использовать этот исходный тест в качестве примера для всех сгенерированных тестов. В качестве альтернативы можно указать имя файла в запросе.

import { test, expect } from './fixtures';

test('seed', async ({ page }) => {
  // this test uses custom fixtures from ./fixtures
});

Результат

• План тестирования в формате Markdown, сохраненный как specs/basic-operations.md.
• План понятен человеку, но достаточно точен для генерации тестов.

Пример: specs/basic-operations.md

# TodoMVC Application - Basic Operations Test Plan

## Application Overview

The TodoMVC application is a React-based todo list manager that demonstrates standard todo application functionality. The application provides comprehensive task management capabilities with a clean, intuitive interface. Key features include:

- **Task Management**: Add, edit, complete, and delete individual todos
- **Bulk Operations**: Mark all todos as complete/incomplete and clear all completed todos  
- **Filtering System**: View todos by All, Active, or Completed status with URL routing support
- **Real-time Counter**: Display of active (incomplete) todo count
- **Interactive UI**: Hover states, edit-in-place functionality, and responsive design
- **State Persistence**: Maintains state during session navigation

## Test Scenarios

### 1. Adding New Todos

**Seed:** `tests/seed.spec.ts`

#### 1.1 Add Valid Todo

**Steps:**
1. Click in the "What needs to be done?" input field
2. Type "Buy groceries"
3. Press Enter key

**Expected Results:**
- Todo appears in the list with unchecked checkbox
- Counter shows "1 item left"
- Input field is cleared and ready for next entry
- Todo list controls become visible (Mark all as complete checkbox)

#### 1.2 Add Multiple Todos
...

🎭 Generator​

Агент Generator использует план в формате Markdown для создания исполняемых тестов Playwright. По ходу выполнения сценариев он проверяет селекторы и утверждения. Playwright поддерживает подсказки для генерации и предоставляет каталог утверждений для эффективной структурной и поведенческой проверки.

Входные данные

• План в формате Markdown от specs/

Запрос

• Обратите внимание, что basic-operations.md включен в контекст generator.
• Так generator узнает, откуда взять план тестирования. В качестве альтернативы можно указать имя файла в запросе.

Результат

• Набор тестов в каталоге tests/
• В сгенерированных тестах могут быть исходные ошибки, которые агент healer сможет исправить автоматически

Пример: tests/add-valid-todo.spec.ts

// spec: specs/basic-operations.md
// seed: tests/seed.spec.ts

import { test, expect } from '../fixtures';

test.describe('Adding New Todos', () => {
  test('Add Valid Todo', async ({ page }) => {
    // 1. Click in the "What needs to be done?" input field
    const todoInput = page.getByRole('textbox', { name: 'What needs to be done?' });
    await todoInput.click();

    // 2. Type "Buy groceries"
    await todoInput.fill('Buy groceries');

    // 3. Press Enter key
    await todoInput.press('Enter');

    // Expected Results:
    // - Todo appears in the list with unchecked checkbox
    await expect(page.getByText('Buy groceries')).toBeVisible();
    const todoCheckbox = page.getByRole('checkbox', { name: 'Toggle Todo' });
    await expect(todoCheckbox).toBeVisible();
    await expect(todoCheckbox).not.toBeChecked();

    // - Counter shows "1 item left"
    await expect(page.getByText('1 item left')).toBeVisible();

    // - Input field is cleared and ready for next entry
    await expect(todoInput).toHaveValue('');
    await expect(todoInput).toBeFocused();

    // - Todo list controls become visible (Mark all as complete checkbox)
    await expect(page.getByRole('checkbox', { name: '❯Mark all as complete' })).toBeVisible();
  });
});

🎭 Healer​

Если тест завершается с ошибкой, агент healer:

• Повторно выполняет шаги, завершившиеся с ошибкой
• Изучает текущий интерфейс, чтобы найти эквивалентные элементы или потоки
• Предлагает исправление (например, обновление локатора, изменение ожидания или исправление данных)
• Повторно запускает тест, пока он не пройдет или пока защитные ограничения не остановят цикл

Входные данные

• Имя упавшего теста

Запрос

Результат

• Успешно пройденный тест или пропущенный тест, если healer считает, что функциональность не работает.

Артефакты и соглашения​

Статические определения агентов и сгенерированные файлы имеют простую и удобную для аудита структуру:

repo/
  .github/                    # agent definitions
  specs/                      # human-readable test plans
    basic-operations.md
  tests/                      # generated Playwright tests
    seed.spec.ts              # seed test for environment
    tests/create/add-valid-todo.spec.ts
  playwright.config.ts

Определения агентов​

Внутри определения агентов представляют собой наборы инструкций и инструментов MCP. Их предоставляет Playwright, и при каждом обновлении Playwright их нужно создавать заново.

Пример для субагентов Claude Code:

npx playwright init-agents --loop=vscode

Спецификации в specs/​

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

Тесты в tests/​

Сгенерированные тесты Playwright, по возможности соответствующие спецификациям один к одному.

Исходные тесты seed.spec.ts​

Исходные тесты предоставляют готовый контекст page для запуска.