End-to-end тестирование с Playwright

01Место E2E в пирамиде тестирования

В основании пирамиды тестирования много быстрых unit-тестов, в середине — меньше интеграционных, а на вершине — небольшое число E2E-тестов. E2E-тесты самые реалистичные, но и самые медленные и дорогие в поддержке, поэтому используйте их для критичных сценариев: регистрация, вход, поиск, добавление в корзину, checkout, сброс пароля, ключевые действия в админке. Не проверяйте каждое сообщение валидации через браузер — это задача unit- или компонентных тестов. В здоровом наборе от десятков до нескольких сотен E2E-тестов, которые параллельно выполняются за минуты, и каждый защищает то, поломка чего ударит по пользователям или выручке.

02Установка и первый тест

Установите через npm init playwright@latest — команда создаст конфиг, пример теста и workflow для GitHub Actions и скачает браузеры. Тест — это async-функция, получающая фикстуры; самая важная из них — page, новая вкладка браузера в изолированном browser context (как новый профиль инкогнито) для каждого теста. Находите элементы локаторами, ориентированными на пользователя, такими как getByRole, getByLabel и getByText, выполняйте над ними действия и проверяйте через expect. Playwright автоматически ждёт, пока элементы станут видимыми, доступными и стабильными, прежде чем кликнуть, а web-first assertions вроде toBeVisible и toHaveURL повторяются, пока не пройдут или не истечёт таймаут. Ручные ожидания почти никогда не нужны.

1import { test, expect } from "@playwright/test";
2 
3test("user can search and open a product", async ({ page }) => {
4  await page.goto("/");
5  await page.getByRole("searchbox", { name: "Search" }).fill("running shoes");
6  await page.getByRole("button", { name: "Search" }).click();
7 
8  const results = page.getByRole("listitem").filter({ hasText: "Trail" });
9  await expect(results.first()).toBeVisible();
10 
11  await results.first().getByRole("link").click();
12  await expect(page).toHaveURL(/\/products\//);
13  await expect(page.getByRole("heading", { level: 1 })).toContainText("Trail");
14});

03Локаторы, которые переживают редизайн

Нестабильные и хрупкие тесты обычно появляются из-за плохих селекторов. CSS-путь вроде div > div:nth-child(3) > button ломается, когда дизайнер добавляет обёртку. Предпочитайте локаторы, отражающие то, что видят пользователи и вспомогательные технологии: сначала getByRole с доступным именем, затем getByLabel для полей форм, getByPlaceholder, getByText и getByTestId как явный контракт, когда ничего другого стабильного нет. Локаторы ленивые и строгие: они вычисляются заново при каждом действии, а если локатор совпадает с несколькими элементами, Playwright выбрасывает ошибку, а не кликает не туда. Комбинируйте и фильтруйте локаторы, чтобы сузить область, например до строки с конкретным номером заказа. Бонус: локаторы по ролям подталкивают приложение к лучшей доступности.

• Хорошо: page.getByRole("button", { name: "Place order" })
• Хорошо: page.getByLabel("Email")
• Избегайте: page.locator(".btn.btn-primary:nth-child(2)")

04Конфигурация, projects и аутентификация

playwright.config.ts задаёт базовый URL, браузеры (projects), повторы, репортеры и способ запуска приложения. Распространённый паттерн — setup project, который один раз логинится и сохраняет storage state браузера (cookies и localStorage) в файл; остальные projects переиспользуют его, так что большинство тестов стартуют уже аутентифицированными, без повторного прохождения UI логина. webServer запускает приложение перед тестами и ждёт его готовности. Сохраняйте трейсы для упавших повторов — это даёт полную запись для отладки падений в CI. Не коммитьте сохранённый файл аутентификации; добавьте папку в .gitignore.

1import { defineConfig, devices } from "@playwright/test";
2 
3export default defineConfig({
4  testDir: "./e2e",
5  fullyParallel: true,
6  forbidOnly: !!process.env.CI,
7  retries: process.env.CI ? 2 : 0,
8  reporter: [["html"], ["list"]],
9  use: { baseURL: "http://localhost:3000", trace: "on-first-retry" },
10  projects: [
11    { name: "setup", testMatch: /.*\.setup\.ts/ },
12    { name: "chromium", dependencies: ["setup"],
13      use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/user.json" } },
14    { name: "mobile", dependencies: ["setup"],
15      use: { ...devices["iPhone 15"], storageState: "playwright/.auth/user.json" } },
16  ],
17  webServer: { command: "npm run start", url: "http://localhost:3000", reuseExistingServer: !process.env.CI },
18});

05Фикстуры и page objects

Фикстуры — это dependency injection в Playwright: тест объявляет, что ему нужно (page, request или собственная фикстура, например залогиненный админ или заранее созданный товар), а Playwright подготавливает и убирает это вокруг теста. Собственные фикстуры заменяют цепочки beforeEach и делают тесты короткими. Page object model оборачивает локаторы и действия страницы в класс, чтобы изменение UI исправлялось в одном месте. Держите page objects тонкими: они предоставляют действия на языке пользователя (addToCart, checkout), а проверки оставляют тестам. Используйте фикстуру request, чтобы создавать тестовые данные через API, — это гораздо быстрее, чем прокликивать UI.

1import { test as base, expect } from "@playwright/test";
2 
3type Fixtures = { product: { slug: string } };
4 
5export const test = base.extend<Fixtures>({
6  product: async ({ request }, use) => {
7    const res = await request.post("/api/test/products", { data: { name: "E2E shoe", price: 50 } });
8    const product = await res.json();
9    await use(product);                                   // run the test
10    await request.delete("/api/test/products/" + product.slug); // clean up
11  },
12});
13 
14test("product page shows price", async ({ page, product }) => {
15  await page.goto("/products/" + product.slug);
16  await expect(page.getByTestId("price")).toHaveText("$50.00");
17});

06Отладка и CI

У Playwright сильные инструменты. npx playwright test --ui открывает UI mode с режимом наблюдения и перемещением во времени по каждому шагу. --debug открывает инспектор для пошагового выполнения действий. codegen записывает ваши клики в тест — хорошая отправная точка, которую потом нужно почистить. Trace viewer показывает каждое действие, снимок DOM, сетевой запрос и лог консоли упавшего теста — так отлаживаются падения в CI без локального воспроизведения. В CI устанавливайте браузеры через npx playwright install --with-deps, запускайте параллельно с workers, разбивайте большие наборы на несколько машин через --shard и загружайте HTML-отчёт и трейсы как артефакты. Официальный Docker-образ содержит все зависимости браузеров.

1# .github/workflows/e2e.yml (steps)
2- uses: actions/checkout@v4
3- uses: actions/setup-node@v4
4  with: { node-version: 22, cache: npm }
5- run: npm ci
6- run: npx playwright install --with-deps
7- run: npx playwright test --shard=${{ matrix.shard }}/4
8- uses: actions/upload-artifact@v4
9  if: ${{ !cancelled() }}
10  with: { name: report-${{ matrix.shard }}, path: playwright-report/ }

07Как Playwright управляет браузерами

Playwright выполняет код тестов в Node.js и общается с браузерами через постоянное соединение: Chrome DevTools Protocol для Chromium и собственные пропатченные протоколы для Firefox и WebKit. Такой дизайн вне процесса браузера позволяет одному тесту управлять несколькими страницами, контекстами и даже браузерами и напрямую наблюдать за сетевым трафиком. Browser contexts — дешёвые изолированные сессии внутри одного процесса браузера, поэтому каждый тест получает новый контекст за миллисекунды. Playwright привязывает к каждому релизу конкретные сборки браузеров; начиная с 1.57 для Chromium используются сборки Chrome for Testing, а устанавливаются они через npx playwright install. Для дополнительной уверенности можно запускать тесты и в брендовых Chrome или Edge через опцию channel.

08Управление сетью: моки, HAR и API-тестирование

page.route перехватывает запросы, совпадающие с шаблоном URL, чтобы вы могли ответить на них фиксированными данными, изменить их или прервать для имитации сбоев. Так тестируется сценарий «платёжный провайдер недоступен», не ломая настоящего провайдера. routeFromHAR воспроизводит записанный трафик для стабильных демо или офлайн-тестов. Фикстура request — полноценный HTTP-клиент, который при желании разделяет cookies с browser context, поэтому можно создавать данные, вызывать внутренние эндпоинты или писать чистые API-тесты в том же фреймворке. Комбинируйте их: создайте заказ через API, а затем проверьте, что UI его показывает, — это быстро и проверяет оба слоя.

1test("shows a friendly error when payments fail", async ({ page }) => {
2  await page.route("**/api/payments/intent", (route) =>
3    route.fulfill({ status: 503, json: { error: "unavailable" } }),
4  );
5  await page.goto("/checkout");
6  await page.getByRole("button", { name: "Pay now" }).click();
7  await expect(page.getByRole("alert")).toContainText("try again");
8});

09Визуальное регрессионное тестирование

expect(page).toHaveScreenshot() делает скриншот и попиксельно сравнивает его с сохранённым эталоном, падая, если разница превышает порог. Первый прогон создаёт эталон; обновляйте его осознанно через --update-snapshots. Скриншоты отличаются между операционными системами и из-за рендеринга шрифтов, поэтому генерируйте и сравнивайте эталоны в одном окружении, обычно в официальном Docker-образе Playwright в CI. Снижайте шум: маскируйте динамические области (даты, рекламу, аватары) опцией mask, отключайте анимации, дожидайтесь загрузки шрифтов и по возможности снимайте отдельные компоненты, а не целые страницы. Снимки доступности через toMatchAriaSnapshot сравнивают дерево доступности как текст — это менее хрупко, чем пиксели, и ловит структурные регрессии.

1await expect(page).toHaveScreenshot("checkout.png", {
2  fullPage: true,
3  mask: [page.getByTestId("order-date"), page.locator(".promo-banner")],
4  animations: "disabled",
5  maxDiffPixelRatio: 0.01,
6});

10Масштабирование набора: параллелизм, шардирование и контроль нестабильности

По умолчанию Playwright параллельно выполняет тестовые файлы в нескольких worker-процессах; fullyParallel распараллеливает и тесты внутри файла. Каждый worker получает свой браузер, поэтому тесты не должны делить изменяемые данные: создавайте уникальные записи для каждого теста или используйте worker-scoped фикстуры, создающие один аккаунт на worker (поможет testInfo.workerIndex). В CI шардируйте на несколько машин через --shard=1/4 и объединяйте blob-отчёты через npx playwright merge-reports в один HTML-отчёт. Отслеживайте нестабильность: тест, прошедший на повторе, помечается как flaky; разбирайте этот список еженедельно и устраняйте первопричину — обычно это общее состояние, пропущенные await или анимации. --repeat-each и --fail-on-flaky-tests помогают воспроизводить и контролировать. В последних версиях также есть AI-агенты для тестов, которые планируют, генерируют и чинят тесты, но их результат всё равно нужно ревьюить.