Kuidas luua toote ekraanipilte dokumentatsiooni jaoks automaatselt

autor: Fraser Hardy

Brauseriaken, mis näitab rakenduse töölauda, kus kaamera pildiotsija nurgad raamivad diagrammi paneeli ja selle kõrval on virnas valmis ekraanipiltide failid

Sa liigutasid üht nuppu. Nüüd näitavad 14 abiartiklit vana paigutust ja keegi peab sisse logima, õige demokonto üles leidma, akna suurust muutma ja iga pildi uuesti tegema. Keegi ei taha seda tööd, nii et seda ei tehta ja dokumentatsioon hakkab vaikselt valetama.

Lahendus on lõpetada toote ekraanipiltide käsitsi tegemine. Toote ekraanipiltide automaatseks loomiseks kirjuta skript, mis logib sisse seedatud demokontole, külastab iga lehte kindla suurusega peata brauseris, jäädvustab konkreetseid elemente (mitte kogu ekraani) 2x eraldusvõimega, maskeerib kõik, mis jooksude vahel muutub, ja salvestab iga pildi stabiilse failinime all. Seejärel käivita see skript CI-s alati, kui kasutajaliides muutub. Playwright teeb seda kõike umbes 60 real.

Allpool on skript, mida me tegelikult kasutaksime, detailid, mis teevad väljundi ühtlaseks, ja osad, mis vajavad ikka inimest.

Miks käsitsi tehtud toote ekraanipildid aeguvad

Käsitsi tehtud ekraanipildid ebaõnnestuvad igavatel põhjustel:

Ekraanipiltide automatiseerimine lahendab esimesed kolm täielikult ja annab sulle võimaluse neljandaga võidelda. Kui sinu dokumentatsioon triivib üldiselt (mitte ainult pildid), käsitleb selle probleemi laiemat versiooni kuidas dokumentatsiooni ajakohasena hoida, kui ilmub iga nädal uut.

Mida vajad enne koodi kirjutamist

Kolm asja panevad automatiseeritud dokumentatsiooni ekraanipildid tööle. Jäta mõni neist vahele ja saad ebakindla, inetu väljundi.

1. Seedatud demokonto

Sinu skript peab sisse logima kontole, mis näeb alati ühesugune välja: sama ettevõtte nimi, samad 12 projekti, samad võltsmeeskonnakaaslased usutavate nimedega. Kirjuta seemneskript (scripts/seed-demo.ts või mis iganes sinu tehnoloogiapaketile sobib), mis selle konto kustutab ja uuesti loob. Realistlikkus loeb. Töölaud, mis on täis “Test Project 1” ja “asdf”, näeb abiartiklis katki välja.

2. Stabiilsed selektorid asjadele, mida jäädvustad

Sa teed elementidest ekraanipilte, nii et vajad usaldusväärset viisi nende leidmiseks. Tailwindi või CSS-in-JS-i CSS-klassid muutuvad pidevalt. Lisa selle asemel pühendatud atribuut:

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

See ei maksa midagi, see elab ümberkorraldused üle ja ütleb igale inseneridele “see element ilmub dokumentatsioonis, mõtle enne kustutamist”.

3. Kaadrite nimekiri

Lihtne nimekiri kõigist piltidest, mida sinu dokumentatsioon kasutab: milline leht, milline element, mida maskeerida ja väljundfaili nimi. Hoia see koodis, skripti kõrval. See nimekiri on ka hilisem vastus küsimusele “millised ekraanipildid näitavad arvelduse lehte?”

Töötav Playwrighti ekraanipiltide skript

Playwright on selle jaoks tänapäeval parim tööriist. See juhib päris Chromiumi, Firefoxi või WebKiti, saab teha ühest elemendist ekraanipildi ja sellel on sisseehitatud valikud maskeerimiseks ja animatsioonide külmutamiseks.

Esmalt logi üks kord sisse ja salvesta sessioon, et iga ekraanipiltide jooks algaks autentituna:

// 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();

Seejärel ekraanipiltide skript ise:

// 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();

Käivita see käsuga node scripts/docs-login.mjs && node scripts/docs-screenshots.mjs oma kohaliku rakenduse või seedatud demokontoga staging-koopia vastu. Saad kausta teravaid PNG-sid, mis on nimetatud täpselt nagu kaadrite nimekiri.

Ekraanipiltide automatiseerimise konveieri neli etappi: seeda demoandmed, defineeri kaadrite nimekiri, käivita see CI-s ühendamisel või öösiti, ja muutunud pildid ilmuvad dokumentatsioonis ülevaadatava diffina

Seadistused, mis muudavad ekraanipildid ühtlaseks

Enamik väärtust on käputäies valikutes. Siin on, miks igaüks seal on.

Fikseeritud vaateaken. 1280x800 tähendab, et paigutus läheb katki iga kord samades kohtades. Vali üks suurus ja jää selle juurde kõigil piltidel, et sinu abikeskus ei näeks välja nagu kollaaž.

deviceScaleFactor: 2. See renderdab retina-tihedusega, nii et 600 px laiune element muutub 1200 px laiuseks pildiks. See näeb terav välja tänapäevastel sülearvutitel ja telefonides ning artiklis saad seda kuvada poole suuruses. Failid muutuvad suuremaks; lase need läbi optimeerija nagu oxipng või teisenda WebP-ks, kui see sulle korda läheb.

Elementide ekraanipildid, mitte terved lehed. Ainult arvelduse kokkuvõtte kaardi ekraanipilt ütleb lugejale, kuhu vaadata. Terve lehe jäädvustus sunnib teda otsima. See tähendab ka, et külgriba muutus ei puuduta sinu arvelduse pilti, nii et vaatad üle ainult selle, mis tegelikult muutus.

Dünaamilise sisu maskeerimine. Kõik, mis erineb kahe jooksu vahel ilma koodimuudatuseta, on müra: suhtelised ajatemplid, reaalajas loendurid, “3 inimest võrgus”, juhuslikud avatari värvid, vahelduv päeva näpunäide. Playwrighti mask valik värvib nende elementide peale tahke kasti. Eelista andmete parandamist allikas (seedatud nimed, külmutatud kell) ja maskeeri ainult see, mida sa ei kontrolli.

Külmutatud kell, lokaat ja ajavöönd. page.clock.setFixedTime kinnitab Date.now(), nii et “Tähtaeg 2 päeva pärast” ütleb igavesti sama. Lokaat ja ajavöönd takistavad teises piirkonnas asuvat CI-jooksutajat renderdamast 02/03/2026 asemel 3/2/2026.

Animatsioonid välja, kursor peidetud. Pooleldi valmis hajumine või vilkuv kursor ilmub ühes jooksus ja mitte järgmises.

Enne ja pärast võrdlus: toores ekraanipilt reaalajas ajatempli, päris e-posti aadressi ja juhusliku avatariga, selle kõrval sama ekraanipilt, kus need alad on maskeeritud ja e-post asendatud demoandmetega

Ekraanipiltide uuesti käivitamine CI-s

Skript, mida pead meeles pidama käivitama, on vaid veidi parem kui käsitsi tegemine. Pane see CI-sse.

Lihtsaim versioon: iga main-i ühendamise puhul (või öösiti, kui sinu testikomplekt on aeglane) käivita rakendus, seeda demokonto, käivita skript ja ava pull request, kui mõni pilt muutus. Git näitab GitHubis piltide diffe kõrvuti, nii et ülevaataja saab pilgu peale visata “billing-summary.png muutus” ja kinnitada, et see on kavandatud muudatus.

# .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

Üks ausalt hoiatus: fondid renderduvad macOS-is ja Linuxis veidi erinevalt. Kui mõned ekraanipildid tulevad sinu sülearvutist ja mõned CI-st, “muudab” iga jooks pilte, mis tegelikult ei muutunud. Genereeri need ainult ühes kohas (CI-s või kohalikult ametliku Playwrighti Dockeri kujutisega) ja diffid püsivad vaiksed.

Kus skriptitud ekraanipildid ikka alla jäävad

See lähenemine on suurepärane ja see on ikka töö. Ole selles realistlik:

Teisi võimalusi on. Cypressil on cy.screenshot() ja see töötab hästi, kui sinu meeskond juba Cypressis elab. Puppeteer on madalama taseme ja Chromiumile keskendunud. shot-scraper on mugav Playwrighti ümber ehitatud CLI-pakend, kui eelistad YAML-faili skripti asemel. Üksikute turundusekraanipiltide jaoks on käsitsi tööriist nagu CleanShot X püsiva akna suurusega ausalt öeldes täiesti okei. Skriptitud tee tasub ära, kui sul on rohkem kui paar tosinat pilti, mis peavad ajakohased püsima.

Ekraanipiltide automatiseerimine ilma skripti kirjutamata

See on osa tööst, mille võtmiseks me Ellie Docsi ehitasime. Ühendad GitHubi repositooriumi ja Ellie loeb koodi, et kaardistada sinu funktsioonid ja kasutajale suunatud ekraanid. Seejärel käivitab see sinu rakenduse liivakastis, logib sisse testkasutajana ja jäädvustab sisseloginud toote tõelised ekraanipildid, mis paigutatakse otse sellesse koostatud abiartiklitesse.

Ellie Docsi artiklite redaktor, mis näitab avaldatud alustamisartiklit, kuhu on manustatud rakenduse sisseelamisekraani automaatselt jäädvustatud ekraanipilt, ja paneeli Ekraanipildid, mis loetleb jäädvustatud pildi

Kuna iga artikkel on seotud funktsioonidega, mida see kirjeldab, märgitakse ühendatud PR, mis muudab ühte neist funktsioonidest, õigete artiklite vastu ja sa vaatad soovitatud uuenduse üle, enne kui miski avalikuks läheb. Sa ei hoolda kaadrite nimekirja ega selektorite faili.

Avaldatud abikeskuse artikkel, kuhu on manustatud toote ekraanipilt ekraanist "ühenda oma postkast"

Kui sulle meeldib Playwrighti skripti omada, hoia see. See on hea lahendus. Kui eelistad, et ekraanipildid, nende ümber olevad artiklid ja hooldus oleksid sinu eest tehtud, seda Ellie teebki. Ka nende piltide ümber olevate sõnade kirjutamine on omaette oskus; vaata kuidas kirjutada abikeskuse artikleid, mida inimesed päriselt kasutavad.

Levinud küsimused

Mis eraldusvõimega peaksid dokumentatsiooni ekraanipildid olema? Jäädvusta 2x (deviceScaleFactor: 2) fikseeritud vaateaknast, mis on umbes 1280 pikslit lai, ja kuva seejärel poole suuruses. See annab teravad pildid retina-ekraanidel ilma tohutute paigutusteta.

Kas peaksin tegema ekraanipildi tervest lehest või ainult ühest osast? Tavaliselt ühest osast. Kärbi elemendi järgi, mille kohta samm käib, väikese ümbritseva kontekstiga, et lugeja selle üles leiaks. Kasuta terve lehe pilte säästlikult, hetkedeks “siin on üldine paigutus”.

Kuidas hoida päris kliendiandmed ekraanipiltidest väljas? Ära jäädvusta kunagi tootmiskontodelt. Kasuta seedatud demokontot võltsnimede ja example.com e-kirjadega ning maskeeri kõik, mida sa seedida ei saa, näiteks kolmanda osapoole vidinad.

Kui tihti peaksid automatiseeritud ekraanipildid jooksma? Iga main-i ühendamise puhul, kui jooks on kiire, öösiti, kui see ei ole. Point on selles, et keegi ei pea meeles pidama.

Kui tahad, et see sinu eest tehtaks, proovi Ellie Docsi tasuta. Ühenda repositoorium ja sul on abikeskus sinu rakenduse tõeliste ekraanipiltidega, kaarti pole vaja.