Агенты Playwright Test

Введение

Playwright поставляется с тремя Playwright Test Agents «из коробки»: 🎭 planner, 🎭 generator и 🎭 healer.

Эти агенты можно использовать независимо, последовательно или как цепочку вызовов в агентном цикле (agentic loop). Последовательное использование агентов позволяет получить тестовое покрытие для вашего продукта.

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

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

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

VS Code

npx playwright init-agents --loop=vscode

Claude Code

npx playwright init-agents --loop=claude

OpenCode

npx playwright init-agents --loop=opencode

примечание

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

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

🎭 Planner

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

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

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

Промпт

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

Example: seed.spec.ts

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

test('seed', async ({ page }) => {
  // этот тест использует пользовательские фикстуры из ./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 поддерживает подсказки для генерации и предоставляет каталог утверждений (assertions) для эффективной структурной и поведенческой валидации.

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

• 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:

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

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

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

Промпт

Результат

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

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

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

repo/
  .github/                    # определения агентов
  specs/                      # человекочитаемые планы тестирования
    basic-operations.md
  tests/                      # сгенерированные Playwright‑тесты
    seed.spec.ts              # seed‑тест для подготовки окружения
    tests/create/add-valid-todo.spec.ts
  playwright.config.ts

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

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

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

npx playwright init-agents --loop=vscode

Specs в specs/

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

Tests в tests/

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

Seed‑тесты seed.spec.ts

Seed‑тесты предоставляют готовый к использованию контекст page для инициализации выполнения.