Настройка Playwright: установка, конфигурация и запуск первого теста

Настройка Playwright занимает около пяти минут: установите пакет, скачайте бинарные файлы браузеров и запустите сгенерированный пример теста. Сложности начинаются позже — настройка проектов, совместное использование состояния аутентификации и сохранение работоспособности конфигурации на CI-машине. Это руководство проведёт вас по всему пути: от пустой папки до надёжного тестового конвейера.

Что на самом деле устанавливает настройка Playwright

Настройка Playwright: установка, конфигурация и запуск тестов - Что на самом деле устанавливает настройка Playwright.

Когда вы запускаете инициализатор, Playwright делает больше, чем просто добавляет зависимость. Он создаёт каркас рабочего тестового проекта и скачивает бинарные файлы браузеров для Chromium, Firefox и WebKit.

Типичный каркас выглядит так:

playwright.config.ts        # центральная конфигурация
package.json
package-lock.json           # или yarn.lock / pnpm-lock.yaml
tests/
  example.spec.ts           # минимальный стартовый тест

В файле playwright.config.ts определяются браузеры, таймауты, повторные попытки, проекты и репортёры. Папка tests/ содержит ваши спецификации. Бинарные файлы браузеров хранятся вне вашего проекта, чтобы их можно было переиспользовать в разных репозиториях.

Системные требования

Перед началом убедитесь в соответствии окружения:

• Node.js: последняя версия 22.x, 24.x или 26.x
• Windows: Windows 11+, Windows Server 2019+ или WSL
• macOS: 14 (Sonoma) или новее
• Linux: Debian 12/13 или Ubuntu 22.04/24.04/26.04 (x86-64 или arm64)

Шаг 1: Установка Playwright

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

npm init playwright@latest
# или
yarn create playwright
# или
pnpm create playwright

Во время интерактивного запроса вы выбираете:

1. TypeScript или JavaScript — TypeScript используется по умолчанию и даёт лучшую поддержку в редакторе.
2. Имя папки тестов — по умолчанию tests, или e2e, если папка tests уже существует.
3. Рабочий процесс GitHub Actions — рекомендуется, если вы планируете запускать тесты в CI.
4. Установить браузеры Playwright — оставьте включённым, если вы не управляете бинарными файлами отдельно.

Вы можете повторно запустить инициализатор позже; он не перезапишет существующие тесты.

Если вы предпочитаете работать в редакторе, расширение для VS Code может создавать и запускать тесты без обращения к терминалу. Для рабочих процессов с участием агентов существует отдельный CLI, который устанавливает навыки для таких инструментов, как Claude Code и GitHub Copilot:

npm install -g @playwright/cli@latest
playwright-cli install
playwright-cli install --skills

Это создаёт каталог .playwright, добавляет его в .gitignore и скачивает настроенный браузер, если он отсутствует.

Шаг 2: Запуск примера теста

По умолчанию тесты запускаются в безголовом режиме и параллельно в Chromium, Firefox и WebKit.

npx playwright test

Полезные варианты:

npx playwright test --headed                 # увидеть окно браузера
npx playwright test --project=chromium       # запустить один браузер
npx playwright test tests/example.spec.ts    # запустить один файл
npx playwright test --ui                     # открыть режим UI

Режим UI даёт вам режим наблюдения, просмотр шагов в реальном времени и отладку с перемещением во времени. Это самый быстрый способ понять, почему локатор не сработал.

Чтение HTML-отчёта

После запуска откройте отчёт:

npx playwright show-report

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

Шаг 3: Настройка проектов и браузеров

Настройка Playwright: установка, конфигурация и запуск тестов - Шаг 3: Настройка проектов и браузеров.

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

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: 'http://localhost:3000',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

Повторные попытки важны в CI: один нестабильный сетевой вызов не должен приводить к сбою сборки. Локально оставляйте повторные попытки на нуле, чтобы замечать реальную нестабильность.

Шаг 4: Добавление глобальной настройки и завершения

Большинству наборов тестов нужно, чтобы что-то произошло один раз перед всеми тестами — заполнение базы данных, вход в систему или генерация токена. Playwright предлагает два подхода, и они не равнозначны.

Вариант A: Зависимости проектов (рекомендуется)

Определите проект настройки и сделайте другие проекты зависимыми от него. Это интегрируется с тестовым раннером, поэтому записываются трассировки и работают фикстуры.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'setup db',
      testMatch: /global\.setup\.ts/,
      teardown: 'cleanup db',
    },
    {
      name: 'cleanup db',
      testMatch: /global\.teardown\.ts/,
    },
    {
      name: 'chromium with db',
      use: { ...devices['Desktop Chrome'] },
      dependencies: ['setup db'],
    },
  ],
});

Файлы настройки и завершения — это обычные тесты:

// tests/global.setup.ts
import { test as setup } from '@playwright/test';

setup('create new database', async () => {
  console.log('creating new database...');
});

Вариант B: globalSetup в конфигурации

Устаревшая опция запускает одну экспортируемую функцию перед всеми тестами. Она работает, но не даёт видимости в HTML-отчёте, записи трассировок и поддержки фикстур.

import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: require.resolve('./global-setup'),
  globalTeardown: require.resolve('./global-teardown'),
  use: {
    baseURL: 'http://localhost:3000/',
    storageState: 'state.json',
  },
});

Распространённый шаблон — аутентификация один раз и сохранение сессии:

import { chromium, type FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  const { baseURL, storageState } = config.projects[0].use;
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(baseURL!);
  await page.getByLabel('User Name').fill('user');
  await page.getByLabel('Password').fill('password');
  await page.getByText('Sign in').click();
  await page.context().storageState({ path: storageState as string });
  await browser.close();
}

export default globalSetup;

Затем тесты запускаются уже аутентифицированными, поскольку storageState загружается из state.json.

Если вам нужны трассировки из неудачной глобальной настройки, оберните тело в try...catch и остановите трассировку перед повторным выбрасыванием ошибки.

Шаг 5: Обновление Playwright и браузеров

Версии Playwright привязаны к конкретным сборкам браузеров. Обновляйте их вместе:

npm install -D @playwright/test@latest
npx playwright install --with-deps

Проверьте установленную версию с помощью npx playwright --version. В Linux --with-deps устанавливает системные библиотеки, необходимые браузерам — пропуск этого флага является наиболее частой причиной сбоев в CI.

Распространённые проблемы настройки Playwright

Где настройка Playwright встречается с реальной автоматизацией

Playwright отлично управляет браузером, но не управляет идентификацией. Если вашим тестам или скраперам нужно работать с множеством аккаунтов — логинами продавцов на маркетплейсах, рекламными аккаунтами, профилями в соцсетях — каждой сессии нужен изолированный отпечаток и собственный прокси. Этот слой обеспечивает антидетект-браузер.

AdsPower создаёт изолированные профили браузера с уникальными отпечатками по параметрам Canvas, WebGL, сети и user agent, а также поддерживает настройку прокси для каждого профиля. Команды, работающие с множеством аккаунтов, часто сочетают его с Playwright, чтобы каждый запуск автоматизации начинался с чистой, согласованной идентичности, а не с общего состояния браузера. Для шаблонов, специфичных для маркетплейсов, смотрите руководство по использованию AdsPower с Amazon Seller Central, а для партнёрских рабочих процессов — руководство по мультиаккаунтингу в MaxBounty.

Это не замена настройке Playwright — это дополнение. Playwright отвечает за навигацию, утверждения и отчётность; слой профилей управляет контекстом аккаунта под ними.

Связанное чтение

• Топ-10 антидетект-браузеров и облачных телефонов 2026 - Независимый рейтинг 2026 года топ-10 платформ антидетект-браузеров и облачных телефонов, оценённых по глубине отпечатков, поддержке мобильных устройств, автоматизации и ценообразованию.
• AdsPower vs Maskfog vs Nstbrowser: как выбрать браузер с отпечатками в 2026 году - Сравните антидетект-браузеры AdsPower, Maskfog и Nstbrowser: возможности отпечатков, параметры прокси, автоматизация, командная работа и цены, чтобы выбрать правильный инструмент для масштаба вашего бизнеса.
• AdsPower vs Kameleo: сравнение антидетект-браузеров 2026 - Сравнение AdsPower и Kameleo для мультиаккаунтинга и веб-скрапинга: отпечатки, автоматизация, цены, бесплатные тарифы и для кого подходит каждый инструмент в 2026 году.

Источники и дополнительное чтение

• Установка | Playwright - Введение
• Глобальная настройка и завершение | Playwright - Введение
• Установка | Playwright - Предварительные требования

Часто задаваемые вопросы

Сколько времени занимает настройка Playwright?

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

Нужно ли устанавливать браузеры отдельно?

Обычно нет. npm init playwright@latest скачивает их по умолчанию. Вручную npx playwright install нужен только после обновления Playwright или при настройке машины без инициализатора.

В чём разница между globalSetup и зависимостями проектов?

Зависимости проектов выполняются как обычный проект, поэтому они отображаются в HTML-отчёте, записывают трассировки и поддерживают фикстуры. globalSetup — это одна функция, которая выполняется перед всем и лишена этих возможностей. Документация Playwright рекомендует зависимости проектов.

Может ли Playwright работать в headed-режиме в CI?

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

Как запустить только один браузер во время разработки?

Используйте npx playwright test --project=chromium. Это пропускает другие проекты и значительно сокращает цикл обратной связи.

Поддерживает ли Playwright мобильное тестирование?

Да. Playwright включает нативную эмуляцию мобильных устройств для Chrome на Android и Mobile Safari, настраиваемую через пресеты устройств в ваших проектах.

Заключение

Надёжная настройка Playwright — это три вещи: правильная установка, конфигурация, соответствующая вашему CI-окружению, и стратегия глобальной настройки, которая не конфликтует с тестовым раннером. Начните с инициализатора, запустите пример теста, затем добавляйте проекты и проект настройки по мере роста вашего набора тестов. Когда вашей автоматизации потребуется работать с несколькими аккаунтами, а не с одной пользовательской сессией, добавьте антидетект-браузер, чтобы каждый запуск имел собственную чистую идентичность — и пусть Playwright занимается тем, что он делает лучше всего: управляет браузером и сообщает, что сломалось.