Visual Regression тестирование: гайд от А до Я

Функциональный тест зелёный, кнопка кликается, форма отправляется — а юзер смотрит на экран и видит, что иконка съехала на 4 пикселя влево и наезжает на текст. Классический разрыв между unit/E2E-тестами и реальностью UI. Visual regression закрывает эту дыру: ты автоматически сравниваешь скриншоты до и после изменения, и любое расхождение становится фейлом теста.

Что это и зачем

Визуальная регрессия — это автотест, который:

• Открывает страницу/экран в одинаковом состоянии.
• Делает скриншот.
• Сравнивает с эталоном (baseline) попиксельно или с помощью visual diff.
• Если расхождение > threshold — тест красный.

Главная ценность — ловит то, что не покрывает функциональное тестирование: смещения, переливающиеся цвета, кривые шрифты после миграции, поломанные тени, ошибки рендера на разных DPI.

Где это критично

• Дизайн-системы и UI-библиотеки. Один компонент используется в 50 местах — изменил padding, не заметил, поломал 30 экранов.
• E-commerce / pricing pages. Цена сместилась, скидка не там — конверсия упала, никто не знает почему.
• Маркетинговые лендинги. Каждый пиксель важен, а билды собираются ежедневно.
• Мобильные игры. UI меняется часто, новые экраны добавляются спринтами. Тут особенно ценно — функциональным тестом 100% не покроешь.
• Cross-browser / cross-platform. Visual regression — единственный способ поймать что на Safari иконка SVG рендерится иначе чем в Chrome.

Где не надо

• Highly dynamic content: ленты соцсетей, news feed, real-time charts. Скриншоты будут красными всегда — ложно-позитивные результаты.
• Анимации и transitions без специальной подготовки — нужно либо отключать анимации, либо ждать стабильного состояния.
• MVP-стадия: UI ещё меняется каждую неделю. Baselines надо обновлять чаще чем смотреть. Хаос.

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

• Baseline capture: первый раз тест делает screenshot и сохраняет как «эталон» (обычно в репо или в облаке тула).
• Test run: при следующем запуске делается новый screenshot.
• Diff computation: пиксельное сравнение или AI-based diff. Расхождение измеряется в процентах или в количестве отличающихся пикселей.
• Review: если diff > threshold, разработчик смотрит на скриншоты до/после, принимает решение — это баг или ожидаемое изменение. Если ожидаемое — обновляет baseline.

Тулы — обзор

Cloud-сервисы (платные, удобные)

• Percy (BrowserStack) — самый известный. Интеграция с Selenium, Cypress, Playwright, Puppeteer. Cross-browser, parallel snapshot processing, PR-comment с визуальным diff. От $149/мес.
• Chromatic — заточен под React/Vue/Angular + Storybook. Каждый компонент в Storybook автоматически становится visual-тестом. Идеален если у вас есть дизайн-система. Free tier на 5000 snapshots.
• Applitools — самый умный AI diff. Не падает на анти-алиасинге, понимает «эту фичу переместили на 3 пикселя — это норма». Дорого ($прайс по запросу), но если бюджет позволяет — лучший в классе.

Open-source

• BackstopJS — старая школа, JSON-конфиг, headless Chrome. Бесплатно, гибко. Self-hosted.
• lost-pixel — open-source, интеграция со Storybook и Playwright. Можно self-host или использовать их облако.

Встроенные в фреймворки

• Playwright Screenshots — нативная команда await expect(page).toHaveScreenshot(). Baseline хранится в репо. Бесплатно, без отдельной инфраструктуры. Идеально для старта.
• Cypress Visual Testing — через плагины (cypress-image-snapshot, Percy/Applitools-интеграции).
• Storybook Visual Testing — нативная поддержка через Chromatic.

Главная проблема: ложные срабатывания

80% времени с visual regression уходит на борьбу с flaky screenshots. Источники нестабильности:

• Динамическое время — у вас на экране клок «Last updated 3 min ago». Каждый прогон — новое значение. Решение: мокать время через Date.now override, или замаскировать элемент.
• Рандом — генерация UUID, случайные баннеры, A/B-тестируемые элементы. Решение: фиксированный seed для рандома в тестовом окружении.
• Шрифты — Web Fonts загружаются после render, скриншот пойман в момент fallback-fonts. Решение: ждать document.fonts.ready перед snapshot.
• Анимации — элемент в середине fade-in, момент пойман на 40% opacity. Решение: * { animation-duration: 0s !important; transition-duration: 0s !important; } в тестовом CSS.
• Анти-алиасинг — на разных GPU/драйверах одна и та же кривая рендерится с разными краевыми пикселями. Решение: pixel-level threshold (3-5% allowed diff) или AI diff (Applitools умеет).
• Loading states — изображения подгружаются асинхронно. Решение: ждать всех img на load или мокать через сервис-воркер.

Best practices

Detеrministic state

Перед snapshot привести систему в идентичное состояние:

• Мокать backend API (MSW, WireMock, Mirage) — одинаковые данные при каждом прогоне.
• Зафиксировать time/date: clock.tick() в Cypress, page.clock в Playwright.
• Отключить анимации глобально в test-окружении.
• Ждать конкретного события «всё загрузилось» (a network idle + custom signal), не sleep.

Маскирование dynamic regions

Если не получается полностью застабилизировать — маскируйте. Playwright: await expect(page).toHaveScreenshot({ mask: [page.locator('.timestamp')] }) — закрасит чёрным область с динамическим контентом, остальное сравнит.

Branch-based baseline

Делать baseline на main, тестировать против неё в feature-branches. Когда merge — новые baseline становятся master. Так нет хаоса «у меня локально другой эталон».

Threshold tuning

Не ставьте 0% diff — будет постоянно красное от анти-алиасинга. 0.1-0.5% — типичный starting point. Если падают тесты на real-changes — снижайте. Если шумят — повышайте.

Размер скриншотов и storage

Скриншоты тяжёлые. 1000 тестов × 5 экранов × 3 viewport = 15000 файлов. В Git это не лежит — используйте либо облачный тул (Percy/Chromatic хранят у себя), либо Git LFS, либо S3.

Storybook + Chromatic — золотой стандарт для веба

Если у вас компонентная архитектура (React/Vue/Angular):

• Каждый компонент в Storybook с пачкой stories (разные пропсы, состояния).
• Chromatic подключается одной командой и автоматически генерирует visual test на каждую story.
• На каждый PR — Chromatic комментирует «изменены такие-то компоненты, посмотри здесь».
• Покрытие получается очень большое за минимум усилий, потому что Storybook у вас и так был.

Для мобильных приложений

• Native iOS / Android: snapshot-testing от PointFree для iOS (популярный), screenshot-tests-for-android от Facebook (старый, но рабочий), Paparazzi (нативный JVM, не требует эмулятора).
• React Native: react-native-storybook + Chromatic, либо @storybook/react-native + lost-pixel.
• Unity: нет out-of-the-box тула. Делают вручную через ScreenCapture + image diff библиотеку, интегрируют в build pipeline. Применимо для UI Canvas (HUD, popups), не для 3D-сцен с динамикой.

CI интеграция

Минимальный pipeline:

• Установить тул (npm/pip).
• Запустить тесты с baseline-режимом на main — сохранить эталоны.
• В PR-пайплайне: запустить с compare-режимом — фейлить если diff.
• Запостить визуальный diff в коммент PR (Percy/Chromatic это делают автоматически, для open-source тулов — отдельно).
• Optional: auto-merge baseline после ручного approve («yes, this change is intentional»).

Когда лучше не внедрять

• Команда из 1 разработчика и QA, продукт меняется каждую неделю — overhead обновления baseline превысит пользу.
• UI на 90% состоит из dynamic content (data tables, feeds, charts) — слишком много маскирования, тесты теряют смысл.
• Нет процесса review diff'ов — никто не смотрит на скриншоты, тесты просто фейлятся → их игнорируют → выключают. Лучше не заводить.

С чего начать

• Выберите 5-10 самых важных экранов: главный, страница оплаты, корзина, профиль, ключевые popups.
• Возьмите Playwright Screenshots (бесплатно, в репо) или Chromatic free tier (для Storybook).
• Зафиксируйте mock-данные и время. Отключите анимации в тестовом CSS.
• Прогоните 2-3 раза подряд — убедитесь что тесты стабильны на одинаковом коде.
• Намеренно сломайте что-нибудь (поменяйте padding на 5px) — проверьте что тест краснеет.
• Подключите в CI как blocking тест на PR.
• Через 2 недели смотрите статистику: сколько раз поймал реальные регрессии vs ложные срабатывания. Корректируйте threshold.

Полезные ссылки

• Playwright — Test Snapshots
• Cypress — Visual Testing guide
• Storybook — Visual Testing
• Percy by BrowserStack
• Chromatic
• Applitools
• BackstopJS (open-source)
• lost-pixel (open-source)