Как автоматически создавать скриншоты продукта для документации

Автор: Fraser Hardy

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

Вы передвинули одну кнопку. Теперь в 14 статьях справки показан старый интерфейс, и кому-то нужно войти в систему, найти нужный демо-аккаунт, изменить размер окна и переснять каждое изображение. Никто не хочет этим заниматься, поэтому работа не делается, а документация незаметно начинает лгать.

Решение — перестать делать скриншоты продукта вручную. Чтобы создавать скриншоты продукта автоматически, напишите скрипт, который входит в демо-аккаунт с заготовленными данными, открывает каждую страницу в безголовом браузере с фиксированным размером окна, снимает конкретные элементы (а не весь экран) в разрешении 2x, маскирует всё, что меняется между запусками, и сохраняет каждое изображение под постоянным именем файла. Затем запускайте этот скрипт в CI при каждом изменении интерфейса. Playwright делает всё это примерно в 60 строках.

Ниже скрипт, которым мы бы действительно пользовались, детали, обеспечивающие единообразный результат, и то, что по-прежнему требует участия человека.

Почему скриншоты продукта, сделанные вручную, устаревают

Скриншоты, сделанные вручную, подводят по скучным причинам:

Автоматизация скриншотов полностью решает первые три проблемы и даёт шанс справиться с четвёртой. Если у вас расходится с реальностью вся документация (а не только изображения), более широкая версия этой проблемы разобрана в статье как поддерживать документацию в актуальном состоянии, когда вы выпускаете обновления каждую неделю.

Что нужно до того, как писать код

Чтобы автоматические скриншоты документации работали, нужны три вещи. Если пропустить любую из них, результат получится нестабильным и некрасивым.

1. Демо-аккаунт с заготовленными данными

Вашему скрипту нужно входить в аккаунт, который всегда выглядит одинаково: то же название компании, те же 12 проектов, те же вымышленные коллеги с правдоподобными именами. Напишите скрипт заполнения (scripts/seed-demo.ts или другой, подходящий вашему стеку), который очищает и заново создаёт этот аккаунт. Реалистичность важна. Панель, полная «Тестовый проект 1» и «asdf», выглядит в статье справки сломанной.

2. Стабильные селекторы для снимаемых элементов

Вы будете снимать элементы, поэтому нужен надёжный способ их находить. CSS-классы из Tailwind или CSS-in-JS постоянно меняются. Добавьте вместо них специальный атрибут:

<section data-docs="billing-summary">...</section>

Это ничего не стоит, переживает рефакторинг и сообщает каждому инженеру: «этот элемент появляется в документации, подумайте, прежде чем удалять».

3. Список снимков

Обычный список всех изображений, которые использует ваша документация: какая страница, какой элемент, что маскировать и имя выходного файла. Храните его в коде, рядом со скриптом. Этот список позже также ответит на вопрос «какие скриншоты показывают страницу оплаты?».

Рабочий скрипт для скриншотов на Playwright

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

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

// scripts/docs-login.mjs
import { chromium } from 'playwright';

const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`${BASE_URL}/login`);
await page.getByLabel('Email').fill(process.env.DEMO_EMAIL);
await page.getByLabel('Password').fill(process.env.DEMO_PASSWORD);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.context().storageState({ path: '.auth/demo.json' });
await browser.close();

Затем сам скрипт скриншотов:

// scripts/docs-screenshots.mjs
import { chromium } from 'playwright';
import { mkdir } from 'node:fs/promises';

const BASE_URL = process.env.BASE_URL ?? 'http://localhost:3000';
const OUT_DIR = 'docs/images';

const shots = [
  {
    name: 'dashboard-overview',
    path: '/dashboard',
    element: '[data-docs="overview-panel"]',
    mask: ['[data-docs="last-synced"]', '[data-docs="avatar"]'],
  },
  {
    name: 'billing-summary',
    path: '/settings/billing',
    element: '[data-docs="billing-summary"]',
  },
  {
    name: 'invite-teammate-dialog',
    path: '/settings/team',
    element: '[role="dialog"]',
    before: (page) => page.getByRole('button', { name: 'Invite teammate' }).click(),
  },
];

const browser = await chromium.launch();
const context = await browser.newContext({
  storageState: '.auth/demo.json',
  viewport: { width: 1280, height: 800 },
  deviceScaleFactor: 2,
  colorScheme: 'light',
  locale: 'en-US',
  timezoneId: 'America/New_York',
  reducedMotion: 'reduce',
});
const page = await context.newPage();

// Every "Updated 3 minutes ago" and date picker now shows the same moment.
await page.clock.setFixedTime(new Date('2026-03-02T10:00:00'));

await mkdir(OUT_DIR, { recursive: true });

for (const shot of shots) {
  await page.goto(BASE_URL + shot.path);
  if (shot.before) await shot.before(page);

  const target = page.locator(shot.element);
  await target.waitFor({ state: 'visible' });

  await target.screenshot({
    path: `${OUT_DIR}/${shot.name}.png`,
    animations: 'disabled',
    caret: 'hide',
    mask: (shot.mask ?? []).map((selector) => page.locator(selector)),
    maskColor: '#e3d4ff',
    // Hide things that should never appear in docs.
    style: '#chat-widget, .cookie-banner, .dev-toolbar { display: none !important; }',
  });

  console.log(`saved ${shot.name}.png`);
}

await browser.close();

Запустите его командой node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs на локальном приложении или на копии для тестирования с заготовленным демо-аккаунтом. Вы получите папку чётких PNG с именами, в точности совпадающими со списком снимков.

Четыре этапа конвейера автоматизации скриншотов: подготовка демо-данных, составление списка снимков, запуск в CI при слиянии или по ночам, а изменившиеся изображения появляются в документации как дифф для проверки

Настройки, обеспечивающие единообразие скриншотов

Основная польза заключена в нескольких параметрах. Вот зачем нужен каждый из них.

Фиксированный размер окна. 1280x800 означает, что вёрстка ломается в одних и тех же точках каждый раз. Выберите один размер и придерживайтесь его во всех изображениях, чтобы ваш центр помощи не выглядел как коллаж.

deviceScaleFactor: 2. Это отрисовывает изображение в плотности retina, так что элемент шириной 600 пикселей превращается в изображение шириной 1200 пикселей. Оно выглядит чётко на современных ноутбуках и телефонах, а в статье его можно показывать вполовину меньшим. Файлы становятся больше; пропустите их через оптимизатор вроде oxipng или конвертируйте в WebP, если это важно.

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

Маскирование динамического содержимого. Всё, что отличается между двумя запусками без изменений кода, — шум: относительные метки времени, живые счётчики, «3 человека онлайн», случайные цвета аватаров, меняющаяся подсказка дня. Параметр mask в Playwright закрашивает эти элементы сплошным прямоугольником. Лучше исправлять данные в источнике (заготовленные имена, замороженные часы) и маскировать только то, чем вы не можете управлять.

Замороженные часы, локаль и часовой пояс. page.clock.setFixedTime фиксирует Date.now(), так что «Срок через 2 дня» говорит одно и то же всегда. Локаль и часовой пояс не дают раннеру CI в другом регионе вывести 02/03/2026 вместо 3/2/2026.

Анимации отключены, курсор скрыт. Недоигравшее плавное появление или мигающий курсор появятся в одном запуске и не появятся в другом.

Сравнение «до» и «после»: необработанный скриншот с живой меткой времени, настоящим адресом почты и случайным аватаром рядом с тем же скриншотом, где эти области замаскированы, а адрес почты заменён демо-данными

Перезапуск скриншотов в CI

Скрипт, о запуске которого нужно помнить, лишь немного лучше ручной работы. Поместите его в CI.

Самый простой вариант: при каждом слиянии в main (или по ночам, если ваш набор тестов медленный) запускайте приложение, заполняйте демо-аккаунт, запускайте скрипт и открывайте pull request, если хоть одно изображение изменилось. Git показывает различия изображений рядом на GitHub, так что рецензент может взглянуть на «billing-summary.png изменился» и подтвердить, что это намеренное изменение.

# .github/workflows/docs-screenshots.yml
name: Docs screenshots
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npm run seed:demo
      - run: npm run start &
      - run: npx wait-on http://localhost:3000
      - run: node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs
        env:
          DEMO_EMAIL: ${{ secrets.DOCS_DEMO_EMAIL }}
          DEMO_PASSWORD: ${{ secrets.DOCS_DEMO_PASSWORD }}
      - uses: peter-evans/create-pull-request@v6
        with:
          branch: docs/screenshots
          title: "Update docs screenshots"
          add-paths: docs/images

Одно честное предупреждение: шрифты в macOS и Linux отрисовываются немного по-разному. Если часть скриншотов снимается на вашем ноутбуке, а часть в CI, при каждом запуске будут «меняться» изображения, которые на самом деле не изменились. Создавайте их только в одном месте (в CI или в официальном образе Docker Playwright локально), и различия останутся тихими.

Где скриптовые скриншоты всё же не справляются

Этот подход хорош, но это всё равно работа. Будьте реалистами:

Есть и другие варианты. В Cypress есть cy.screenshot(), и он отлично подходит, если ваша команда уже работает в Cypress. Puppeteer работает на более низком уровне и ориентирован на Chromium. shot-scraper — удобная консольная обёртка над Playwright, если вы предпочитаете файл YAML вместо скрипта. Для разовых маркетинговых снимков ручной инструмент вроде CleanShot X с постоянным размером окна, честно говоря, вполне подходит. Скриптовый путь окупается, когда изображений больше пары десятков и их нужно поддерживать актуальными.

Автоматизация скриншотов без написания скрипта

Именно эту часть работы мы создали Ellie Docs, чтобы снять её с ваших плеч. Вы подключаете репозиторий GitHub, и Ellie читает код, чтобы сопоставить ваши функции и экраны, видимые пользователям. Затем она запускает ваше приложение в песочнице, входит как тестовый пользователь и снимает реальные скриншоты продукта под учётной записью пользователя, размещая их прямо в статьях справки, которые она составляет.

Редактор статей Ellie Docs с опубликованной статьёй «Начало работы», в которую встроен автоматически снятый скриншот экрана онбординга приложения, и панель «Скриншоты» со списком снятых изображений

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

Опубликованная статья центра помощи со встроенным скриншотом экрана продукта «Подключите свою почту»

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

Частые вопросы

Какого разрешения должны быть скриншоты документации? Снимайте в 2x (deviceScaleFactor: 2) из фиксированного окна шириной около 1280 пикселей, затем показывайте вполовину меньшими. Так изображения будут чёткими на экранах retina без огромных макетов.

Снимать всю страницу или только часть? Обычно часть. Обрежьте по элементу, о котором шаг, оставив немного окружающего контекста, чтобы читатель мог его найти. Снимки всей страницы используйте редко, для моментов вроде «вот общая компоновка».

Как не допустить реальные данные клиентов в скриншоты? Никогда не снимайте с боевых аккаунтов. Используйте демо-аккаунт с заготовленными данными, вымышленными именами и адресами example.com, а всё, что нельзя заготовить, например сторонние виджеты, маскируйте.

Как часто запускать автоматические скриншоты? При каждом слиянии в main, если запуск быстрый, и по ночам, если нет. Суть в том, чтобы никому не нужно было об этом помнить.

Если хотите, чтобы это сделали за вас, попробуйте Ellie Docs бесплатно. Подключите репозиторий, и вы получите центр помощи с реальными скриншотами вашего приложения, карта не нужна.