Компонентное тестирование
Введение
Playwright Test позволяет тестировать компоненты вашего веб-приложения изолированно. Тест компонента — это обычный сквозной тест Playwright, который выполняется на небольшой странице галереи историй, обслуживаемой вашим собственным сервером разработки. Для этого не нужны ни отдельная среда выполнения для тестирования компонентов, ни интеграция со сборщиком, ни дополнительные npm-пакеты — всем управляет встроенная фикстура fixtures.mount() из @playwright/test.
import { test, expect } from '@playwright/test';
test('click should expand', async ({ mount }) => {
const component = await mount('components/Expandable/Stateful');
await component.getByRole('button').click();
await expect(component.getByTestId('expanded')).toHaveValue('true');
});
Тесты выполняются в Node.js, а компоненты — в настоящем браузере: выполняются реальные клики, рассчитывается реальная компоновка страницы, доступно визуальное регрессионное тестирование. При этом тесты получают все возможности Playwright Test: параллельное выполнение, параметризацию, повторные запуски и запись трассировок для последующего анализа сбоев.
Экспериментальные пакеты @playwright/experimental-ct-react, -ct-react17 и -ct-vue были удалены и больше не публикуются. Если вы всё ещё используете их, оставайтесь на Playwright 1.62, пока не выполните инструкции из приведённого ниже руководства по миграции.
Зачем нужен подход без привязки к фреймворку
Пакеты @playwright/experimental-ct-* позволяли писать JSX прямо в тесте, например mount(<Button onClick={spy} />). Для этого Playwright сам находил компоненты в тестах, собирал их своей копией Vite со своей конфигурацией, запускал сервер и передавал свойства и обратные вызовы между Node.js и браузером.
Из-за такого устройства пакеты так и остались экспериментальными:
- Поддерживались только совместимые настройки. Псевдонимы путей, плагины и обработку CSS приходилось вручную дублировать в
ctViteConfig. Проекты на webpack, Next.js и с собственным конвейером не могли использовать свою сборку. Для каждого фреймворка требовался отдельный пакет со своим кодом интеграции. - Граница между Node.js и браузером создавала ограничения. JSX из теста компилировался в Node.js и воссоздавался в браузере. Объекты нельзя было передавать напрямую, обратные вызовы работали с ограничениями из-за сериализации, а подмены модулей могли молча игнорироваться.
Новый подход передаёт управление проекту:
- Вы управляете сборкой. Компоненты собирает и отдаёт ваш сервер разработки с вашими плагинами, псевдонимами и CSS. Playwright открывает страницу, как в любом другом тесте.
- Подход работает с разными фреймворками. От фреймворка зависит только страница галереи, небольшой модуль в вашем проекте. Если сервер разработки может отобразить компонент на React, Vue, Svelte, Solid или другом фреймворке, Playwright сможет его протестировать.
- Подход стабилен. Тесты импортируют
testиexpectиз@playwright/test, а fixtures.mount() входит в стандартный набор документированных фикстур. Экспериментальные пакеты и отдельный формат конфигурации больше не нужны.
Как это работает
В основе подхода три понятия:
- История — небольшой компонент-обёртка, который помещает тестируемый компонент в конкретный сценарий с заданными свойствами, тестовыми данными, провайдерами и записываемыми обратными вызовами. Истории лежат рядом с компонентом в файлах
*.story.tsxили.ts/.jsx/.js/.vue. Каждый именованный экспорт задаёт одну историю. - Галерея — страница, которую отдаёт ваш сервер разработки. Она предоставляет функции
window.mount(params)иwindow.unmount()для отображения истории из файлов проекта в элементе#rootи её удаления. Вы реализуете галерею на своём фреймворке. - Фикстура fixtures.mount() открывает галерею (testOptions.baseURL), передаёт идентификатор истории и её свойства в
window.mount()и возвращает Locator для корневого элемента галереи. Выполняйте поиск внутри него, напримерcomponent.getByRole('button').click().
Всё необходимое компоненту настраивается внутри истории, которая выполняется в браузере. Тест наблюдает результат через страницу: DOM, URL и сетевые запросы.
Начало работы
Шаг 1. Подключите навык к агенту
Галерея входит в код вашего приложения. Playwright поставляет навык, с помощью которого агент может настроить её за вас. Установите навыки и попросите Claude Code, GitHub Copilot или другого агента выполнить настройку:
npx playwright init-skills
Set up component testing using the playwright-component-testing skill.
Агент определит фреймворк и сборщик, реализует галерею для вашего стека, добавит проект Playwright в конфигурацию и напишет первую историю и тест.
Галерея выполняет несколько требований:
- Это одна страница в
playwright/gallery/, которую отдаёт ваш сервер разработки. Приложения на Vite используют существующий сервер, а для других проектов можно запустить рядом с приложением отдельный сервер Vite. - Галерея находит файлы
*.story.*и предоставляет две функции.window.mount({ story, props })отображает историю по идентификатору в элементе#root, аwindow.unmount()удаляет её. Если история не найдена или рендеринг завершился ошибкой, вызовmount()в тесте выбрасывает исключение. - Галерея повторно использует корневой элемент рендеринга. При вызове
component.update(props)компонент обновляется без повторного монтирования и сохраняет состояние. - Галерея импортирует глобальные стили так же, как точка входа приложения. В
window.mountможно выполнить общую настройку приложения, аналогичную прежним хукамbeforeMount/afterMount.
Если вы предпочитаете написать галерею вручную, в установленном навыке есть полная спецификация с примерами для React и Vue в файле references/gallery-spec.md. Вся страница занимает несколько десятков строк.
Шаг 2. Настройте Playwright
Добавьте проект в playwright.config.ts и укажите адрес галереи в baseURL:
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'components',
testDir: './tests/components',
use: {
...devices['Desktop Chrome'],
baseURL: 'http://localhost:5173/playwright/gallery/index.html',
serviceWorkers: 'block',
reuseContext: true,
},
},
],
webServer: {
command: 'npm run dev',
url: 'http://localhost:5173/playwright/gallery/index.html',
reuseExistingServer: !process.env.CI,
},
});
Фикстура mount открывает baseURL, поэтому этот адрес должен вести на галерею. serviceWorkers: 'block' не даёт сервис-воркеру приложения подставлять кэшированные ответы в обход подмен через page.route(). reuseContext: true ускоряет компонентные тесты, повторно используя контекст браузера между тестами в одном воркере. Экспериментальные пакеты включали эту оптимизацию автоматически.
Шаг 3. Напишите историю
Истории лежат рядом с тестируемым компонентом. Каждый именованный экспорт задаёт отдельный сценарий:
import { Button } from './Button';
export const Primary = () => <Button title='Submit' />;
export const Disabled = () => <Button title='Submit' disabled />;
Шаг 4: Напишите тест
import { test, expect } from '@playwright/test';
test('renders primary button', async ({ mount }) => {
const component = await mount('components/Button/Primary');
await expect(component.getByRole('button')).toHaveText('Submit');
});
test('disabled button is disabled', async ({ mount }) => {
const component = await mount('components/Button/Disabled');
await expect(component.getByRole('button')).toBeDisabled();
});
Шаг 5: Запустите тесты
npx playwright test --project=components
Истории как методология
Истории — это не просто обходной путь для тестирования, а документация состояний ваших компонентов, в которой можно искать текстовыми средствами и которую можно проверять при ревью. Соглашения помогают сохранить эти свойства:
- Один экспорт на сценарий. Предпочитайте экспорт новой истории параметризации существующей. Файл
Button.story.tsx, экспортирующийPrimary,Disabled,WithLongTitle, читается как спецификация компонента. - Истории находятся рядом с компонентом.
src/components/Button.story.tsxдокументируетsrc/components/Button.tsx. При переименовании и рефакторинге оба файла изменяются вместе. - Идентификаторы историй формируются на основе пути к файлу: путь относительно
src/без расширения.story.*плюс имя экспорта —components/Button/Primary. Также подходит любой уникальный суффикс:mount('Button/Primary'). - История содержит всё, что нужно компоненту: провайдеры, тестовые данные, состояние, обратные вызовы. Тест отвечает только за взаимодействия и проверки.
Поскольку каждая история представляет собой именованное состояние страницы, доступное по идентификатору, галерея также служит живым каталогом: откройте URL галереи в браузере и отобразите любую историю, чтобы изучить её визуально.
Шаблоны тестирования
Записывайте состояние для проверок
Компоненты принимают обратные вызовы, а тестам нужно проверять, что они были вызваны. Вместо передачи обратных вызовов между Node.js и браузером история хранит состояние и предоставляет обратные вызовы — и записывает наблюдаемый результат в скрытую форму рядом с компонентом:
- React
- Vue
import { useState } from 'react';
import { Expandable } from './Expandable';
export const Stateful = () => {
const [expanded, setExpanded] = useState(false);
return <>
<Expandable expanded={expanded} setExpanded={setExpanded} title='Заголовок'>Подробности</Expandable>
<form hidden><input data-testid='expanded' readOnly value={String(expanded)} /></form>
</>;
};
import { defineComponent, h, ref } from 'vue';
import Expandable from './Expandable.vue';
export const Stateful = defineComponent(() => {
const expanded = ref(false);
return () => h('div', [
h(Expandable, {
'expanded': expanded.value,
'onUpdate:expanded': (value: boolean) => expanded.value = value,
'title': 'Title',
}),
h('form', { hidden: true }, [
h('input', { 'data-testid': 'expanded', 'readonly': true, 'value': String(expanded.value) }),
]),
]);
});
});
test('click should expand', async ({ mount }) => {
const component = await mount('components/Expandable/Stateful');
await component.getByRole('button').click();
await expect(component.getByTestId('expanded')).toHaveValue('true');
});
Этот приём лежит в основе подхода:
- Весь сценарий выполняется в браузере. Обратные вызовы не нужно сериализовать и передавать между Node.js и браузером.
- Проверка
toHaveValue()повторяется автоматически, пока не появится нужное значение. Вручную ждать или опрашивать состояние не нужно. - Записывайте каждое наблюдаемое значение в отдельное поле с атрибутом
data-testid. Для скалярных значений используйтеString(...), для структурированных данных —JSON.stringify(...). Чтобы проверить отсутствие изменений, выполните действие и убедитесь, что значение осталось прежним. - Записанное состояние видно, когда история открыта в галерее. Нажимайте на компонент вручную и смотрите, как меняются значения. Так можно вручную проверить тот же сценарий, который покрывает автоматический тест. Оставьте атрибут
hiddenу формы, чтобы она не попадала на эталонный скриншот, или уберите его во время разработки, чтобы видеть состояние рядом с компонентом.
Свойства для отдельного теста
Если сценарию нужны параметры, передайте сериализуемые свойства вторым аргументом mount. Галерея передаст их истории:
import { Button } from './Button';
export const WithTitle = ({ title = 'Default' }: { title?: string }) =>
<Button title={title} />;
import type { WithTitle } from '../../src/components/Button.story';
const component = await mount<typeof WithTitle>('Button/WithTitle', { title: 'Hello' });
mount параметризуется типом истории: передайте тип истории в качестве аргумента типа, и типы пропсов (а также аргументов update()) будут проверяться на соответствие сигнатуре истории. Передавайте в пропсах только простые сериализуемые данные — колбэки должны находиться внутри истории.
Изменение свойств через update()
Чтобы проверить реакцию компонента на изменение свойств без повторного монтирования, вызовите component.update(newProps). История отобразится с новыми свойствами в существующем корневом элементе, а её состояние сохранится:
const component = await mount('components/Counter/Default', { value: 1 });
await expect(component.getByTestId('value')).toHaveText('1');
await component.update({ value: 2 });
await expect(component.getByTestId('value')).toHaveText('2');
Несколько состояний и визуальное сравнение
Каждый вызов mount() открывает страницу заново. Это изолирует тесты и позволяет быстро смонтировать несколько историй в одном тесте:
await expect(await mount('Button/Primary')).toHaveScreenshot('primary.png');
await expect(await mount('Button/Disabled')).toHaveScreenshot('disabled.png');
Делайте скриншот с помощью возвращённого корневого локатора, а не всей страницы, чтобы проверка не затрагивала дополнительные элементы, которые вы можете разместить в галерее.
Обработка сетевых запросов
Используйте page.route() как обычно — регистрируйте маршруты до вызова mount(), поскольку монтирование приводит к навигации:
test('renders the error state', async ({ page, mount }) => {
await page.route('**/api/items', route => route.fulfill({ status: 500 }));
const component = await mount('components/ItemList/Default');
await expect(component.getByRole('alert')).toContainText('Something went wrong');
});
Параметр serviceWorkers: 'block' в конфигурации не позволяет собственному сервис-воркеру приложения возвращать кешированные ответы, из-за которых запросы не попадали бы в обработчики маршрутов. Команды, использующие библиотеки обработчиков MSW, могут вместо этого запускать сервис-воркер внутри истории или декоратора.
Отладка историй
Откройте URL галереи в браузере и вызовите await window.mount({ story: 'components/Button/Primary' }) в консоли DevTools — именно это и делает фикстура mount. Если история не найдена или при рендеринге возникает ошибка, промис window.mount отклоняется, а вызов mount() в тесте выбрасывает исключение с реальной трассировкой стека. Чтобы просматривать галерею без консоли, добавьте в неё необязательную индексную страницу со списком всех обнаруженных историй.
Миграция с экспериментальных пакетов
Экспериментальные пакеты компилировали JSX в файле теста и передавали его в браузер. Подход с галереей переносит сценарий в экспортируемую историю, которая выполняется непосредственно в браузере. Вот как соотносятся эти концепции:
@playwright/experimental-ct-* | Галерея историй |
|---|---|
mount(<Button onClick={spy} />) | История с состоянием: история предоставляет onClick и записывает результат в скрытое поле ввода; тест проверяет его с помощью toHaveValue() |
| Обычные данные в пропсах из теста | По сути без изменений: mount(id, props) |
| Дочерние JSX-элементы / слоты из теста | Отдельный экспорт истории для каждой композиции (Vue: файл .story.vue для сценариев с активным использованием слотов) |
component.update(<Button count={2} />) | component.update({ count: 2 }) |
component.unmount() | component.unmount() |
Хуки beforeMount / afterMount | Тело функции window.mount галереи (глобально) или декораторы историй (для отдельных историй) |
Различные значения hooksConfig для отдельных тестов | Пропсы: mount('App/Routing', { route: '/dashboard' }), которые интерпретирует история |
Фикстура router / обработчики MSW в Node.js | page.route() в тесте или MSW setupWorker внутри истории |
playwright/index.html (стили, тема) | Файл index.html галереи и импорты её входного модуля |
ctViteConfig, ctPort, ctTemplateDir | Больше не нужны — галерея работает через ваш собственный сервер разработки; порт задаётся в webServer и baseURL |
defineConfig из пакета ct | Обычный defineConfig из @playwright/test |
Миграция типичного теста выглядит так:
import { test, expect } from '@playwright/experimental-ct-react';
import Button from '../src/components/Button';
test('counts clicks', async ({ mount }) => {
let clicks = 0;
const component = await mount(<Button title='Submit' onClick={() => ++clicks} />);
await component.getByRole('button').click();
expect(clicks).toBe(1);
});
import { useState } from 'react';
import { Button } from './Button';
export const CountsClicks = () => {
const [clicks, setClicks] = useState(0);
return <>
<Button title='Submit' onClick={() => setClicks(count => count + 1)} />
<form hidden><input data-testid='click-count' readOnly value={String(clicks)} /></form>
</>;
};
import { test, expect } from '@playwright/test';
test('counts clicks', async ({ mount }) => {
const component = await mount('components/Button/CountsClicks');
await component.getByRole('button').click();
await expect(component.getByTestId('click-count')).toHaveValue('1');
});
Выполняйте миграцию постепенно: оставаясь на зафиксированной версии Playwright 1.62, настройте галерею и проект components параллельно со старым проектом CT, переносите тесты по одному, затем удалите зависимость @playwright/experimental-ct-* вместе с playwright/index.html, playwright/index.ts и playwright/.cache и обновите Playwright.
На что стоит обратить внимание:
- Идентификаторы историй — это строки. Переименование или перемещение истории приводит к ошибкам в тестах во время выполнения, а не компиляции. Использование
mount<typeof Story>как минимум связывает типы пропсов с историей на этапе компиляции. - JSX в отдельных тестах больше не используется. Если раньше тесты создавали разные JSX-деревья, теперь для каждой композиции нужен отдельный экспорт истории — в этом и заключается смысл: любая композиция, которую стоит тестировать, заслуживает собственного имени и проверки.
Часто задаваемые вопросы
Как получить доступ к методам компонента или его экземпляру?
Обращение к внутренним методам компонента или его экземпляру из кода теста не рекомендуется и не поддерживается. Вместо этого сосредоточьтесь на наблюдении за компонентом и взаимодействии с ним с точки зрения пользователя: нажимайте на него, проверяйте страницу и отражайте внутренние эффекты в DOM с помощью истории. Тесты становятся менее хрупкими и более полезными, когда не зависят от деталей реализации. Если тест завершается с ошибкой при проверке с точки зрения пользователя, скорее всего, автоматизированный тест обнаружил настоящую ошибку.
Можно ли продолжать использовать плагины сборщика, алиасы и настройки CSS?
Да — это основной принцип такого подхода. Галерея обслуживается вашим собственным сервером разработки, поэтому истории могут отображать всё, что может отображать ваше приложение. Не нужно синхронизировать вторую конфигурацию сборщика.
А как насчёт других фреймворков, кроме React и Vue?
Попросите своего ИИ-агента для программирования реализовать контракт галереи для вашего фреймворка: находить компонент по идентификатору истории, отображать его в #root и повторно использовать корневой узел между вызовами, чтобы update() сохранял состояние. Фикстура mount не знает, какой фреймворк используется на другой стороне, и не зависит от него.