Привет, Хабр! Меня зовут Антон, я фронтенд‑разработчик в Домклик. Наша команда отвечает за библиотеку «Продуктовых сниппетов» — те самые карточки недвижимости, которые вы видите в нашей поисковой выдаче.

Проблема в том, что у нас более 40 видов таких карточек: сниппеты вторичной, первичной, загородной и краткосрочной недвижимости, причём каждый тип имеет несколько размеров под разные разрешения. Все они живут в одной монорепозиторной библиотеке на React 19. Любая правка в общих стилях, глобальных дизайн-токенах или элементарное обновление компонентов дизайн-системы превращалось в игру «Сапёр»: поправишь отступ в одном типе сниппета — поехала вёрстка или поплыл паддинг в другом. Об этом мы узнавали либо на этапе тестирования релиза, либо, что ещё хуже, от пользователей после релиза.

Расскажу, как мы внедрили полноценное визуальное регрессионное тестирование (Visual Regression Testing) на основе Storybook, Playwright и Jest, а также о трудностях, с которыми столкнулись при стабилизации скриншотов, и как заставили тесты работать стабильно.

Почему не Snapshot-тесты в Jest

Многие путают классическое DOM Snapshot-тестирование (проверка структуры HTML-кода) с визуальным (сравнение реальных картинок-рендеров). Snapshot-тесты нам не подошли по следующим причинам:

1. Тонны бесполезного кода. Любое изменение префикса автогенерации классов (например, в CSS-модулях) полностью ломает текстовый снимок. В результате диффы получаются огромными, нечитаемыми и бесполезными.

2. Слепота по отношению к реальному интерфейсу. Компилятор тестов может показать, что HTML-структура идеальна. Однако, если элемент перекрыт свойством z-index, кнопка съехала из-за position: absolute, или сломался flex-wrap, то текстовый Snapshot этого просто не заметит.

Нам был нужен инструмент, который за считанные секунды «сфотографирует» более 40 вариантов сниппетов в реальном headless-браузере и попиксельно сравнит их. Мы выбрали связку @storybook/test-runner + playwright + jest-image-snapshot.

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

Мы сделали довольно простую, но устойчивую архитектуру:

1. Storybook — источник истины в интерфейсе. Каждый сниппет существует как Story: разные размеры, состояния и типы недвижимости. Storybook в данном случае выступает как единый каталог интерфейсных сценариев.

2. Test Runner (Jest + Storybook Test Runner). Он проходит по всем Story, рендерит их в Headless Chrome (через Playwright) и делает скриншоты каждого состояния.

3. Jest Image Snapshot — мозг сравнения. Он сравнивает эталон с текущим рендером.

Конфигурация Test Runner. Вот наш test-runner-jest.config.js:

const { getJestConfig } = require('@storybook/test-runner');

// Получаем базовый конфиг раннера
const defaultOptions = getJestConfig();

module.exports = {
  ...defaultOptions,
  // выделяем максимум 30 сек на один тест
  testTimeout: 30000,
  // запускаем только файлы историй
  testMatch: ['<rootDir>/src/**/*.stories.[jt]s?(x)', '<rootDir>/src/**/*.story.[jt]s?(x)'],
  testPathIgnorePatterns: [
    'node_modules',
    '.cache',
    'dist',
    'lib',
  ],
  // ограничить количество воркеров, чтобы Chrome не «съел» всю память и не падал по таймауту
  maxWorkers: '50%',
  // компиляция кода перед его запуском
  transform: { ...defaultOptions.transform },
};

Скрипты запуска. Чтобы разработчику было максимально просто пользоваться инструментом, мы сделали два npm-скрипта:

"screenshot:test": "npm run build-storybook && (serve storybook-static -p 6006 & wait-on http://127.0.0.1:6006 && test-storybook)",
"screenshot:update": "npm run build-storybook && (serve storybook-static -p 6006 & wait-on http://127.0.0.1:6006 && test-storybook --updateSnapshot)"

Три главные проблемы стабилизации и как мы их решили

Когда мы запустили первые тесты, папки с диффами (diff) начали забиваться ложными падениями. Картинки «мигали» из‑за сетевых задержек, динамических шрифтов и прочего. Вот как мы решили эти проблемы.

1. Сетевой хаос в галереях. Внутри наших сниппетов есть галереи картинок недвижимости. При запуске тестов Playwright делал скриншот до того, как тяжёлые изображения успевали долететь по сети. Мы решили полностью отказаться от загрузки реальных сетевых картинок в тестах. Через page.evaluate мы находим все контейнеры галерей и принудительно очищаем атрибуты src и srcset у тегов img и source. Это заставляет компоненты мгновенно отрендерить встроенные в код легковесные дизайн-заглушки. Скорость прогона выросла почти в 2 раза!

2. Скриншоты всей страницы и лишние поля. Изначально мы пытались делать скриншоты стандартного контейнера #storybook-root, но на практике это приводило к множеству проблем: обёртка от Storybook имела фиксированные стили, такие как height: 100vh; padding: 16px;, и в итоге карточка товара получалась аккуратной, но вокруг неё оставались огромные пустые области белого фона. Мы отказались от идеи фотографировать страницу целиком и нацелились строго на внутреннее содержимое — сниппет, который имеет уникальный атрибут [data-test="product-snippet"]. Мы доверились нативному методу elementHandle.screenshot(). Playwright сам изолирует этот DOM‑элемент, вычисляет его пиксельные границы и делает снимок ровно по его контуру, полностью игнорируя всё, что происходит вокруг. А чтобы картинкам хватало «воздуха» и рамки карточки не смотрелись слишком впритык, мы в этом же шаге через JS добавляем элементу аккуратные белые паддинги в 16 пикселей.

3. Микрошум браузера и сглаживание шрифтов. Даже когда мы изолировали сниппет, убрали картинки в галереи и договорились запускать тесты строго локально на рабочих машинах, скриншоты всё равно умудрялись периодически «мигать». Причина в том, что Headless‑браузер — штука капризная. Стоит операционной системе в момент теста чуть сильнее нагрузить процессор, как Chromium может на доли миллисекунды затянуть отрисовку субпиксельного сглаживания текста или выдать едва заметный микросдвиг в рендеринге теней и скруглённых углов. Чтобы не переснимать эталоны после каждого случайного «чиха» системы, мы настроили три «золотых» параметра чувствительности в jest-image-snapshot. Они научили инструмент игнорировать невидимый человеческому глазу цифровой шум:

   • customDiffConfig: { threshold: 0.1 } — порог чувствительности к изменению цвета конкретного пикселя. Значение 0.1 означает, что если цвет пикселя на новом скриншоте отличается от эталона менее чем на 10% (например, из‑за тонкостей отрисовки полупрозрачных элементов или градиентов), то Jest вообще не посчитает этот пиксель изменившимся.

   • blur: 1 перед анализом добавляет сравниваемым изображениям лёгкое размытие в 1 пиксель. Это самый простой и эффективный способ победить «прыгающий» антиалиасинг шрифтов: тонкие серые пиксели на краях букв слегка размываются и сливаются с фоном, предотвращая ложные падения из‑за того, что текстовый движок браузера отрисовал букву на долю пикселя правее.

   • failureThreshold: 0.003 и failureThresholdType: 'percent' — наш главный предохранитель, определяющий суммарный допуск. Значение 0.003 разрешает до 0,3% изменений от всей площади сниппета.

Финальный код нашего test-runner.ts

Вот к какой оптимизированной конфигурации мы пришли:

import { TestRunnerConfig } from '@storybook/test-runner';
import { toMatchImageSnapshot } from 'jest-image-snapshot';

const config: TestRunnerConfig = {
  setup() {
    expect.extend({ toMatchImageSnapshot });
  },
  async postVisit(page, context) {
    // Ждем появления корневого контейнера Storybook
    await page.waitForSelector('#storybook-root');

    // Ждем, когда сетевая активность утихнет (шрифты, базовые ассеты)
    await page.waitForLoadState('networkidle', { timeout: 3000 }).catch(() => {
      console.warn(`Timeout waiting for networkidle in ${context.id}`);
    });

    // Ждем готовность шрифтов
    await page.evaluate(() => document.fonts.ready);

    const snippetSelector = '[data-test="product-snippet"]';

    await page.evaluate((selector) => {
      //Отключаем картинки в галерее, они крашат скриншоты, т.к. иногда не успевают подгрузиться
      const galleryContainers = document.querySelectorAll('[class*="gallery"]');
      galleryContainers.forEach((container) => {
        const images = container.querySelectorAll('img, source');
        images.forEach((img) => {
          if (img instanceof HTMLImageElement) {
            img.src = '';
            img.srcset = '';
          } else if (img instanceof HTMLSourceElement) {
            img.srcset = '';
          }
        });
      });

      // Подгоняем размеры и добавляем аккуратные паддинги сниппету
      const element = document.querySelector(selector) as HTMLElement;
      if (element) {
        element.style.padding = '16px';
        element.style.boxSizing = 'border-box';
        element.style.background = '#ffffff';
      }
    }, snippetSelector);

    // пауза, чтобы браузер успел отрендерить fallback-заглушки картинок
    await page.waitForTimeout(300);

    // Получаем элемент и делаем скриншот
    const elementHandle = await page.$(snippetSelector);

    if (elementHandle) {
      const screenshot = await elementHandle.screenshot({
        // Отключаем анимации CSS (переходы, мигание курсора), чтобы они не портили diff
        animations: 'disabled',
        caret: 'hide',
      });

      // Сравнение с эталоном
      expect(screenshot).toMatchImageSnapshot({
        customSnapshotIdentifier: context.id,
        customSnapshotsDir: 'screenshots/reference',
        customDiffDir: 'screenshots/diff',
        // Порог чувствительности к изменению цвета пикселя - 10% разницы в цвете. Помогает игнорировать микро-шум на фото
        customDiffConfig: { threshold: 0.1 },
        // Добавляем размытие для игнорирования пиксельного шума
        blur: 1,
        // Максимально допустимое количество изменений. Если разница между картинками укладывается в эти 0.3%,
        // Jest проигнорирует её и отметит тест как успешно пройденный
        failureThreshold: 0.003,
        failureThresholdType: 'percent',
        // Сглаживание микро-различий (anti-aliasing)
        allowSizeMismatch: true
      });
    }
  },
};

export default config;

Что получили в итоге

Скриншотные тесты закрыли одну из ключевых проблем библиотеки: поиск визуальных регрессий после изменений в общих стилях и компонентах. Также они принесли следующие преимущества:

• Больше уверенности при изменениях. Любые изменения в общих стилях, дизайн-токенах или базовых компонентах больше не нужно проверять вручную во всех возможных сценариях. Теперь мы сразу видим, как конкретное изменение повлияло на каждый тип сниппета и каждое разрешение. Визуальные регрессии выявляются на этапе разработки, а не после релиза. Сейчас разработчику достаточно выполнить одну команду, и примерно за 1—1,5 минуты система автоматически проверяет более 40 видов сниппетов, отображая только реальные отличия.

• Меньше визуальных багов. Скриншотные тесты эффективно обнаруживают проблемы, которые сложно заметить при ревью кода: смещённые отступы, изменение размеров элементов, неожиданные переносы текста или регрессии после обновления компонентов дизайн-системы. Даже незначительные изменения становятся заметными сразу после запуска тестов.

• Стабильная и быстрая инфраструктура. Мы сделали тесты достаточно стабильными, чтобы им доверяли разработчики. Для этого мы отказались от сетевых изображений, настроили допуски для борьбы с шумом браузерного рендеринга и ограничили количество воркеров для стабильной работы Chromium.

Вывод

Скриншотное тестирование не заменяет функциональные или интеграционные тесты, но отлично закрывает задачу контроля визуальных изменений.

Если у вас большая UI-библиотека, то автоматическая проверка скриншотов становится одним из самых эффективных способов защититься от визуальных регрессий и выпускать изменения значительно спокойнее.

Тришин Антон

Frontend-разработчик