taiko-pixel

Плагин для Taiko — пиксельное сравнение скриншотов с автоматической стабилизацией страницы. Работает как standalone Taiko-функция и как набор Gauge-шагов.

Установка

npm install taiko-pixel

Taiko автоматически обнаружит плагин, так как пакет называется taiko-* и находится в dependencies проекта.

Как это работает

При вызове require('taiko') Taiko сканирует dependencies проекта, находит taiko-pixel и:

1. Вызывает init() плагина, передавая ему доступ к Taiko API
2. Добавляет compareScreen и configure напрямую в объект Taiko

После этого compareScreen доступен через деструктуризацию:

const { goto, compareScreen } = require('taiko');

Алгоритм сравнения

compareScreen('myScreen')
  │
  ├─ 1. Стабилизация — делает скриншоты каждые 200мс,
  │      сравнивает соседние кадры. Выходит, когда diff == 0
  │      (страница перестала меняться)
  │
  ├─ 2. Итоговый скриншот → ActualScreen/myScreen.png
  │
  ├─ 3. Если BaseScreen отсутствует — создаёт его из Actual.
  │      Тест засчитывается, падения нет.
  │
  └─ 4. Сравнение Actual с Base через pixelmatch.
         Если совпадение < identity → тест падает,
         diff-файлы сохраняются в папку отчётов.

Конфигурация

Вызовите configure() до начала тестов:

const { configure } = require('taiko');

configure({
  baseDir: 'tests/screenshots',   // куда сохранять Base/Actual (по умолчанию: 'screenshots')
  stabilizeTimeout: 4000,         // мс ожидания стабилизации (по умолчанию: 4000)
  stabilizeFrequency: 200,        // интервал между кадрами при стабилизации (по умолчанию: 200)
  stabilizeThreshold: 0.01,       // порог pixelmatch при стабилизации (по умолчанию: 0.01)
  compareThreshold: 0.1,          // порог pixelmatch при финальном сравнении (по умолчанию: 0.1)
  overrideScreenshots: false,     // обновить Base вместо падения (по умолчанию: false)
});

Также поддерживается переменная окружения для разового обновления эталонов:

npm_config_overrideScreenshots=true gauge run specs

Использование в Taiko-скриптах

const { openBrowser, goto, compareScreen, configure, closeBrowser } = require('taiko');

configure({ baseDir: 'tests/screenshots' });

(async () => {
  await openBrowser();
  await goto('https://example.com');

  // сравнить всю страницу
  await compareScreen('home-page');

  // сравнить с нестандартным порогом точности (99%)
  await compareScreen('home-page', 0.99);

  // сравнить только область: x=100, y=200, ширина=400, высота=300
  await compareScreen('home-page-header', 0.997, 100, 200, 400, 300);

  await closeBrowser();
})();

Использование с Gauge

1. Подключить файлы шагов

В manifest.json проекта добавить:

{
  "step_files": [
    "node_modules/taiko-pixel/gauge/hooks.js",
    "node_modules/taiko-pixel/gauge/steps.js"
  ]
}

hooks.js регистрирует customScreenshotWriter (скриншоты через Taiko) и настраивает baseDir для каждого проекта через beforeSpec.

2. Теги спек

hooks.js автоматически устанавливает baseDir на Projects/<тег>/PixelMatch/<win|lin>/ для следующих тегов:

MDD, Authentication, Binary_data, Console, ConsoleCloud,
Debugger, ECS, ESB, LoadApp, Spreadsheet, Team_development,
BasicIDE, Restruct, Report_dashboard, Single

Пример спеки:

# Тест главной страницы
tags: MDD

## Проверка вёрстки главной страницы
* И я открою браузер в безголовом режиме
* И я перейду в Панель Управления
* И я сделаю скриншот и сравню его с файлом "main-page"

3. Доступные шаги

| Шаг | Описание | |-----|----------| | И я сделаю скриншот и сравню его с файлом <basicScreen> | Сравнить весь экран с эталоном | | Тогда я сделаю скриншот и сравню его с файлом <basicScreen> | То же самое (альтернативный префикс) | | И я сделаю скриншот и сравню его с файлом <basicScreen>, с точностью <accuracy> | Сравнить с указанным порогом (например, 0.99) | | И я сделаю скриншот и частично сравню его с файлом <basicScreen>, с точностью <accuracy>, начиная с точки (<x>, <y>) и областью <widthCord>x<heightCord> | Сравнить только область экрана | | И я сделаю скриншот | Просто сделать скриншот в отчёт |

Структура файлов скриншотов

Projects/<projectFolder>/PixelMatch/<win|lin>/
  ├── BaseScreen/          # эталоны (коммитятся в репозиторий)
  │   └── my-screen.png
  └── ActualScreen/        # снимки текущего прогона (в .gitignore)
      └── my-screen.png

<gauge_reports_dir>/html-report/pixel_results/   # diff-файлы при ошибках
  ├── my-screen.png        # actual
  ├── my-screen-exp.png    # expected
  └── my-screen-dif.png    # разница (подсвечена)

Обновление эталонов (BaseScreen)

Запустить тесты с флагом обновления — эталоны будут перезаписаны без падений:

npm_config_overrideScreenshots=true gauge run specs --tags MDD

Зависимости

| Пакет | Назначение | |-------|-----------| | pixelmatch | Попиксельное сравнение PNG-изображений | | pngjs | Чтение и запись PNG-файлов | | sharp | Обрезка (crop) области перед сравнением | | taiko (peer) | Предоставляется проектом потребителя |