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

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

Что такое визуальное регрессионное тестирование

Визуальное регрессионное тестирование сравнивает текущий скриншот сэталонным скриншотом (Golden File), чтобы обнаруживать изменения интерфейса на странице по различиям пикселей.

Когда изменение CSS неожиданно влияет на вёрстку других страниц, визуальное регрессионное тестирование может напрямую выявить эту проблему.

expect(page).toHaveScreenshot() Сравнение скриншотов страницы

Пример

test('ПРИМЕР Визуальная регрессия главной страницы', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Первый запуск: сохранить эталонный скриншот
  // Последующие запуски: сравнить с эталонным скриншотом
  await expect(page).toHaveScreenshot('example-homepage.png');
});

При первом запуске Playwright сообщит об ошибке и создаст базовый скриншот:

Error: A snapshot doesn't exist at example-homepage-chromium-darwin.png,
writing actual.

При втором запуске он автоматически сравнит с базовым скриншотом.

Полные параметры toHaveScreenshot

Пример

await expect(page).toHaveScreenshot('homepage.png', {
  fullPage: true,                // Скриншот всей страницы
  maxDiffPixelRatio: 0.01,       // Допускать 1% различия пикселей
  maxDiffPixels: 100,            // Допускать до 100 различий пикселей
  threshold: 0.2,                // Порог различия пикселей (0~1)
  animations: 'disabled',        // Отключить анимации (рекомендуется)
  mask: [                        // Игнорировать определённые области
    page.getByText('Current Time'),
  ],
});

expect(locator).toHaveScreenshot() Сравнение скриншота элемента

Пример

test('Визуальная регрессия панели навигации', async ({ page }) => {
  await page.goto('https://www.example.com/');

  // Сравнивать только скриншот панели навигации
  const navbar = page.getByRole('navigation');
  await expect(navbar).toHaveScreenshot('navbar.png');
});

Управление эталонными файлами

Создание эталонного файла

При первом запуске проверки скриншота Playwright автоматически создает эталонный файл и сохраняет его в-snapshotsкаталоге рядом с тестовым файлом:

tests/
├── example.spec.ts
└── example.spec.ts-snapshots/
    └── example-homepage-chromium-darwin.png

Имя файла содержит название браузера и операционной системы, что обеспечивает независимое управление эталонными снимками для разных платформ.

Обновление эталонного файла

Когда в UI происходят ожидаемые изменения дизайна, необходимо обновить эталонный скриншот:

# 更新所有截图基准
npx playwright test --update-snapshots

# 只更新特定文件
npx playwright test tests/example.spec.ts --update-snapshots

Пояснение параметров визуального сравнения

ОпцияTypeОписание
maxDiffPixelRatioчислоДопустимая доля различий пикселей (0~1), по умолчанию 0
maxDiffPixelsчислоДопустимое количество различий пикселей, по умолчанию 0
thresholdчислоДопуск различия на пиксель (0~1), по умолчанию 0.2
animationsstringОтключать ли анимации:'disabled' | 'allow'
maskLocator[]Игнорируемые области (не учитываются при сравнении различий)

Особенности окружения CI

На результаты отрисовки браузера влияют такие факторы, как операционная система, версия браузера, аппаратное обеспечение, состояние питания и безголовый режим. Чтобы обеспечить согласованность, создавайте Golden Files и запускайте тесты в одной и той же среде. Рекомендуется использовать Docker-контейнер или ту же платформу, что и CI, чтобы исключить различия.

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

# 使用 Playwright Docker 镜像确保渲染一致性
docker run --rm -v $(pwd):/work -w /work \
  mcr.microsoft.com/playwright:v1.52.0-jammy \
  npx playwright test --update-snapshots

Лучшие практики визуального тестирования

  • Создавайте Golden Files и запускайте сравнения на одной и той же платформе
  • Используйтеanimations: 'disabled'чтобы устранить неопределённость, связанную с анимацией
  • Используйтеmaskчтобы игнорировать динамический контент (например, временные метки, рекламные блоки)
  • Отдавайте приоритет визуальному регрессионному тестированию критических страниц (главная страница, вход, оплата)
  • Зафиксируйте эталонные файлы в системе контроля версий
  • Используйте фиксированные версии браузеров и операционных систем в CI
Другие расширения