Self-Updating Screenshots in Your Docs: How to Stop Doing It by Hand

The Problem: Your Docs Are Already Lying to You

The screenshot you took six weeks ago is wrong. I don’t mean subtly wrong — I mean the button you’re pointing to says “Submit Order” in your docs and “Place Order” in the actual product, the modal you’re annotating got a border-radius update, and the sidebar item you labeled “Settings” is now under a gear icon with no label at all. This happens constantly. It happened on the last three projects I worked on, and the tell is always the same: a customer tweets a screenshot of your docs next to a screenshot of your actual UI with a caption like “are these even the same product?”

Manual screenshot workflows look reasonable on paper. Someone writes a step in the contributing guide: “If you change UI, update screenshots in /docs/assets/screenshots.” That works for exactly one sprint. By sprint two, the person who wrote the rule has switched to a different ticket, the designer who changed the button color didn’t know they needed to update docs, and the PR reviewer approved without checking because nobody wants to be the person who blocks a merge over a screenshot. I’ve watched this play out repeatedly. The checklist item becomes cargo-cult documentation — it exists, people feel vaguely guilty about ignoring it, and they ignore it anyway.

The real cost is not the twenty minutes it takes to open your browser, navigate to the right state, hit Cmd+Shift+4, crop, rename, and drop it into the right folder. The real cost is remembering to do that every single time someone changes a label, adjusts padding, renames a nav item, or ships a dark mode variant. That’s not a documentation problem. That’s a memory problem, and memory problems don’t get fixed by writing better contributing guides. They get fixed by removing the human from the loop entirely.

Which is exactly what “self-updating screenshots” means. Here’s the actual definition, because I’ve seen it used loosely: automated browser capture runs on CI as part of your normal pipeline, a diff step compares the new captures to your committed baselines, and if anything changed, either the PR fails for human review or — depending on your threshold — the new screenshots are committed automatically. “Deterministic output” is the key property you’re designing for. Same URL, same viewport, same auth state, same seed data → same pixel output, every time. The moment your capture is non-deterministic (because you’re loading live data, or animations haven’t settled, or fonts render differently on Linux vs macOS), your diffs are noise and you’ll start ignoring them, which puts you right back where you started.

The tools that do this — Playwright, Puppeteer, Percy, Chromatic, Argos — all operate on the same core loop:

1. Spin up a headless browser pointed at your app (local build or staging)
2. Authenticate, navigate to the right state, wait for network idle
3. Capture a full-page or element-scoped screenshot
4. Compare against the stored baseline using pixel diff or a perceptual hash
5. Either block the PR or auto-commit the update

The part that trips people up first is step 3 — specifically “wait for network idle.” Headless browsers are faster than human perception, which means if you capture immediately after navigation, you’ll catch loading spinners, skeleton screens, and partially painted layouts. Playwright’s waitForLoadState('networkidle') helps, but it’s not sufficient for apps that poll or stream data. I usually pair it with a custom wait for a specific DOM element that only appears when the page is fully ready:

await page.goto('/dashboard');
await page.waitForSelector('[data-testid="dashboard-loaded"]', { state: 'visible' });
await page.screenshot({ path: 'docs/assets/dashboard.png', fullPage: true });

That data-testid attribute has to be something your engineers actually add and maintain — which sounds like overhead, but it’s the same discipline you need for reliable E2E tests anyway. If your app doesn’t have those hooks yet, self-updating screenshots will expose every flaky rendering assumption you’ve been ignoring.

How Self-Updating Screenshots Actually Work (First Principles)

The whole system collapses to a three-step loop that runs on every deploy, every merge, or on a cron schedule — your choice. A headless browser renders your actual UI at a specific viewport, takes a pixel-accurate screenshot, then either diffs it against a stored baseline (snapshot testing) or pushes the new image straight to wherever your docs live (doc-generation). That’s it. The complexity isn’t in the concept; it’s in making step one produce the same pixels every single time.

Why Headless Chrome Is the Foundation

Puppeteer came first and proved the model worked. I used it for about a year before switching to Playwright, and the reason was blunt: Playwright gives you a single API for Chromium, Firefox, and WebKit, its auto-wait behavior is genuinely smarter, and the locator API makes targeting elements for cropping way less fragile. Puppeteer’s API still requires more manual waitForSelector calls and more “did it actually finish rendering?” guesswork. For doc screenshots specifically, you want zero guesswork. Here’s what launching a browser and capturing a clipped element looks like in Playwright:

const { chromium } = require('playwright');

const browser = await chromium.launch();
const page = await browser.newPage();

await page.setViewportSize({ width: 1280, height: 800 });
await page.goto('http://localhost:3000/dashboard', { waitUntil: 'networkidle' });

// Crop to just the component you care about
const element = page.locator('[data-screenshot="revenue-chart"]');
await element.screenshot({ path: 'docs/img/revenue-chart.png' });

await browser.close();

That data-screenshot attribute trick is something I wish someone had told me earlier. Don’t rely on CSS class names for screenshot targeting — they change when devs refactor. Add explicit data attributes to components that need to be screenshotted, treat them like a contract, and your pipeline becomes resilient to cosmetic changes in the markup.

Deterministic Rendering: The Three Things That Will Betray You

Fonts are the first ambush. A screenshot taken on a Mac with system fonts differs from one taken in a Linux CI container even with the same Chromium version. The fix is to embed your fonts explicitly — don’t rely on system font fallbacks. In your test environment, serve a @font-face that points to a file in your repo, not a CDN. Animations are the second one. Any CSS animation or transition that’s mid-state when the screenshot fires will produce a different image every time. I kill them wholesale in the screenshot environment:

await page.addStyleTag({
  content: `*, *::before, *::after {
    animation-duration: 0s !important;
    transition-duration: 0s !important;
  }`
});

Viewport size is the third. Pick one canonical viewport and never deviate. I use 1280x800 for desktop and 390x844 for mobile, stored as constants in a shared config file. The moment someone hard-codes a different size in a one-off script, you get phantom diffs that cost 20 minutes to diagnose.

Snapshot Testing vs. Doc-Generation: Two Different Jobs

These look similar on the surface but they serve opposite masters. Snapshot testing asks “did anything change?” — it’s a regression guard, and a surprise diff means something needs a human decision. You commit the baseline images to your repo and the CI job fails if pixels shift. Playwright’s built-in expect(page).toHaveScreenshot() handles this with configurable thresholds for anti-aliasing tolerance. Doc-generation screenshots ask “what does it look like right now?” — you always want the latest, so you never compare, you just overwrite and publish. The artifact gets pushed to an S3 bucket, a GitHub Pages branch, or directly into a docs repo via the GitHub API. Mixing these two workflows in the same script is how you end up with a confusing mess where some images are committed and some are uploaded and nobody remembers which is which.

# Snapshot test (CI gate — fails on unexpected diff)
npx playwright test screenshot.spec.ts

# Doc-generation (always publish latest — no comparison)
node scripts/capture-docs-screenshots.js && \
  aws s3 sync ./docs/img s3://your-docs-bucket/img --delete

The commit step in doc-generation pipelines is worth slowing down on. If you’re writing images back to a git repo, you need a bot user with push access and a deliberate branch strategy — otherwise you get merge conflicts when two PRs both update a screenshot simultaneously. One pattern that works cleanly: the pipeline writes to an orphan screenshots branch, and your docs site reads from that branch directly. Your main branch history stays clean and screenshot churn doesn’t pollute your commit log with hundreds of binary blob updates.

Option A: Playwright for Full Control

Playwright gives you a real browser under programmatic control, which means your screenshots match what users actually see — not some headless rendering approximation. I switched to it from Puppeteer after hitting one too many situations where Puppeteer’s Chromium version lagged behind my app’s CSS expectations. Run this to get started:

npm init playwright@latest

That command scaffolds a playwright.config.ts, a tests/ directory with an example spec, and optionally installs browser binaries. The scaffolding also drops a GitHub Actions workflow in .github/workflows/playwright.yml — delete it or repurpose it, but don’t ignore it. The config file is where you’ll spend most of your setup time, specifically the use block for viewport, locale, and base URL. Set those globally or your screenshots will vary across specs in annoying ways.

Your first screenshot script is a single test file. Don’t overthink it:

import { test } from '@playwright/test';

test('capture login screen', async ({ page }) => {
  await page.goto('/login');
  await page.screenshot({ path: 'docs/login-screen.png', fullPage: true });
});

The fullPage: true option is the one you’ll forget and regret. Without it, you get a viewport-height crop, and if your docs page has any scroll content at all, it’ll look wrong. Now, the harder part: dynamic content. Timestamps, user avatars, session tokens — anything that changes between runs will cause diffs that make automated comparison useless. I mask them in-place before taking the screenshot:

await page.locator('.timestamp').evaluate(el => el.textContent = '...');
await page.locator('.user-avatar').evaluate(el => (el as HTMLImageElement).src = '/static/placeholder.png');

This mutates the DOM in the browser context, which means the change is visual-only and doesn’t touch your app state. Way cleaner than CSS tricks or fake data fixtures. Do this for every piece of content that varies by session, time, or user — otherwise your CI pipeline will fail every single run on a “diff” that isn’t actually a regression.

For CI, the command is straightforward but the artifact story matters:

npx playwright test --reporter=html

This generates a full HTML report in playwright-report/. In GitHub Actions, upload it as an artifact and you get a visual diff explorer that’s genuinely useful for reviewing screenshot changes. Add this to your workflow:

- uses: actions/upload-artifact@v3
  with:
    name: playwright-report
    path: playwright-report/
    retention-days: 30

Now the gotcha that burned me for two days: Ubuntu CI runners and macOS dev machines render fonts differently. Even with the same Chromium binary, subpixel hinting diverges enough to produce pixel-level diffs on every run — not from real UI changes, but from font rendering. The fix has two parts. First, add --font-hinting=none to your Chromium launch args in playwright.config.ts:

use: {
  launchOptions: {
    args: ['--font-hinting=none', '--disable-font-subpixel-positioning']
  }
}

Second — and this is the more durable fix — use a Docker base image for both local dev and CI so the font stack is identical. The mcr.microsoft.com/playwright:v1.44.0-jammy image from Microsoft has all the browser deps pre-installed. Once I pinned both environments to that image, my pixel diffs dropped to zero on unchanged UI. The tradeoff: your local npx playwright install becomes redundant inside Docker, and you need to remember to update the image tag when you bump the Playwright version. Pin them together in your package.json and a .env or Makefile variable so they stay in sync.

Option B: Chromatic + Storybook for Component-Level Screenshots

If you’re already running Storybook, this is the path of least resistance — and the match makes sense conceptually too. You’re not taking a screenshot of a page, you’re taking a screenshot of a component in a known state. That’s a fundamentally different thing. Page-level screenshots capture whatever your app renders at a given route, which includes nav, auth state, data loading behavior, and a dozen other variables. Story-level screenshots capture exactly what you told Storybook to render, nothing more. I switched to this approach for a component library specifically because I needed screenshots that stayed stable regardless of what the surrounding app was doing.

Getting wired up

The setup is genuinely minimal:

npm install --save-dev chromatic

Then grab your project token from the Chromatic dashboard (under Manage → Configure) and either drop it in your CI environment or run it locally:

npx chromatic --project-token=<your-token>

To make this repeatable, add it to your package.json:

"scripts": {
  "chromatic": "chromatic --project-token=${CHROMATIC_PROJECT_TOKEN}"
}

Set CHROMATIC_PROJECT_TOKEN as a secret in GitHub Actions, CircleCI, or whatever you’re using. The first run will snapshot every story and mark them all as accepted baselines. Subsequent runs diff against those baselines and flag changes. That’s the core loop.

The --auto-accept-changes flag — be careful here

This flag automatically accepts all visual diffs as the new baseline without requiring a human to review them. On the surface it sounds like exactly what you want for a “self-updating screenshots” workflow. In practice, you should only use it in specific, narrow circumstances — like when you’re running on your main branch after a deliberate UI update has already been reviewed and merged. The thing that caught me off guard was using this flag on a feature branch and accidentally promoting a half-finished component state as the canonical baseline. Chromatic’s whole value proposition is the review step. Strip that out and you’re just burning snapshot budget. Use --auto-accept-changes in your main branch CI pipeline only, after code review has already happened.

Free tier limits and what happens when you hit them

Check chromatic.com/pricing for current numbers since they update these periodically, but the free tier caps you on snapshots per month. A “snapshot” is one story rendered at one viewport — so if you’re testing responsive variants, your count multiplies fast. When you hit the limit mid-month, new builds don’t get snapshotted. They don’t fail loudly by default; the build just shows zero changes detected, which looks like a pass. That silent behavior is the gotcha. Add a check in your CI pipeline for the exit code and the build output, or you’ll think everything is fine when Chromatic is actually just not running.

The honest trade-off that matters for MDX docs

Chromatic publishes your Storybook to a hosted URL — something like https://<hash>--<project>.chromatic.com. Your screenshots live there, not in your repo. This is fine for visual regression in CI. It’s a problem if your goal is embedding screenshots in MDX docs, a README, or a design system documentation site that you control. You can’t ![screenshot](./button.png) from inside Chromatic. You’d have to programmatically download snapshots from their API and commit them, which defeats a lot of the convenience. If your end goal is “screenshots checked into the repo alongside my docs,” Chromatic is solving a different problem than the one you have. It’s a great visual regression tool. It’s not a screenshot-as-artifact pipeline.

Wiring It Into GitHub Actions: The Full Config

The default GITHUB_TOKEN cannot push commits back to your repo in a way that triggers further workflow runs — this is a GitHub security constraint, not a bug. If you try to use it for the commit-back step, the push will silently succeed but the PR creation will fail with a cryptic permissions error. I lost two hours to this. You need a dedicated PAT (Personal Access Token) with repo scope, stored as a secret — I call mine DOCS_BOT_TOKEN. Create a separate GitHub account for your bot user if you care about audit trails; otherwise a PAT from your own account works fine for smaller teams.

Here’s the complete workflow file. Drop this in .github/workflows/update-screenshots.yml:

name: Update Screenshots

on:
  push:
    branches:
      - main

jobs:
  screenshots:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'

    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.DOCS_BOT_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Cache Playwright browsers
        uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            playwright-${{ runner.os }}-

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium
        env:
          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: ${{ steps.cache.outputs.cache-hit == 'true' && '1' || '0' }}

      - name: Run screenshot tests
        run: npx playwright test --update-snapshots
        env:
          BASE_URL: ${{ secrets.STAGING_URL }}

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.DOCS_BOT_TOKEN }}
          commit-message: "chore: update screenshots [skip ci]"
          branch: auto/screenshot-updates
          title: "📸 Automated screenshot updates"
          body: |
            Screenshots were updated automatically after changes merged to main.
            Review the diffs visually before merging.
          labels: automated, screenshots
          delete-branch: true

The if: github.event_name == 'push' && github.ref == 'refs/heads/main' guard is non-negotiable. Without it, every feature branch push triggers this job, you get screenshot PRs for half-finished work, and your teammates start ignoring all automated PRs — including the legitimate ones. The guard keeps this workflow scoped to post-merge state, which is the only point where screenshots actually need to reflect reality. One edge case: if you run integration tests on a staging branch before merging to main, adjust the branch name accordingly.

The Playwright browser cache is the biggest practical win in this whole setup. The first run without caching hits around 90 seconds just for playwright install — it’s downloading 130MB+ of Chromium. With the cache keyed to package-lock.json, subsequent runs skip that entirely. The restore-keys fallback matters here: if you update a non-Playwright dependency and the lock file changes, you still restore the nearest old cache instead of downloading fresh. The only time you’re doing a full download is when you explicitly bump the Playwright version, which is correct behavior.

peter-evans/create-pull-request is the right tool for the auto-PR step instead of rolling your own git commands. The thing that caught me off guard is that it’s idempotent by default — if no files changed, it won’t create a duplicate PR. It also handles the case where the auto/screenshot-updates branch already exists from a previous run: it force-pushes and updates the existing PR rather than opening a second one. That said, read the v6 migration notes before upgrading from v5 — the token input behavior changed and using an old config silently falls back to GITHUB_TOKEN, which loops you right back to the permissions problem described above.

• The [skip ci] in the commit message is essential — without it, the commit that create-pull-request makes to the screenshot branch triggers another workflow run, which triggers another commit, and so on until GitHub rate-limits you.
• Don’t use --with-deps if you’re caching — it installs OS-level dependencies every run regardless of cache state. Run sudo npx playwright install-deps chromium as a separate cached step, or accept that you’ll pay ~15 seconds for apt installs on every run.
• The delete-branch: true option cleans up the auto-branch after the PR merges, which prevents accumulation of stale branches over months of usage.
• Scope your PAT tightly — repo scope is broad. If your org allows fine-grained PATs, use those with only contents: write and pull-requests: write on the specific repo.

Making Screenshots Actually Deterministic

The first time I ran my screenshot pipeline twice and got different images, I assumed it was a timing issue. It was — but not the one I expected. CSS animations were mid-frame, a chart was still interpolating its bars, and a loading spinner was caught at a different rotation each run. One line fixes most of this:

await page.addStyleTag({
  content: '*, *::before, *::after { animation: none !important; transition: none !important; }'
});

Add this immediately after navigation, before you do anything else. The transition: none part is the thing people forget — hover states and color changes on focus all use transitions, and if your test data setup triggers a state change, you’ll get blur or a half-transitioned color. I also add animation-duration: 0s !important as a belt-and-suspenders move for anything that uses JS-driven animation libraries which sometimes ignore the animation shorthand.

Skip networkidle, wait for what you actually care about

networkidle sounds safe. It isn’t. It waits for no network activity for 500ms, which means you’re at the mercy of analytics pings, ad calls, third-party chat widgets, and anything else the page decides to fire. I’ve seen pages take 8 seconds to hit networkidle because a marketing pixel keeps retrying a failed request. Wait for the specific selector that proves your content is rendered:

await page.waitForSelector('[data-screenshot-ready]', { timeout: 5000 });

Add a data-screenshot-ready attribute to your component once the data has loaded and painted. This sounds like extra work — it’s 10 minutes of work that saves you from flaky screenshots forever. If you can’t modify the component, wait for a selector that’s only present after data loads, like a table row or a chart SVG path. The timeout of 5000ms is intentional: if your component doesn’t render in 5 seconds, the screenshot would be wrong anyway and you want the pipeline to fail loudly.

Seed your data or your screenshots are fiction

Unseed test data is the silent killer of screenshot workflows. Your dashboard screenshot shows “47 active users” on Tuesday and “3 active users” on Friday because someone ran it against the dev database. Every chart, every count, every username needs to come from a fixture. I keep a fixtures/screenshot-seed.sql file that gets applied before each run in CI:

// In your Playwright global setup
import { execSync } from 'child_process';

export default async function globalSetup() {
  execSync('psql $DATABASE_URL < fixtures/screenshot-seed.sql');
}

For apps that use API mocking, page.route() is cleaner than a real database. Intercept the endpoints your screenshots depend on and return static JSON. The upside is zero database dependency; the downside is you have to keep the mocked responses in sync with your actual API shape. I use real seeds for integration-level screenshots and route mocking for isolated component screenshots. Pick the tool that matches the abstraction level.

One worker, no race conditions

Playwright's default behavior runs tests in parallel, which is great for speed and terrible for writing files to the same output directory. Two tests writing screenshots/dashboard.png simultaneously gives you a corrupted PNG or one test silently overwriting the other's work. The fix is one flag:

npx playwright test --workers=1

Or lock it in your config so you never forget:

// playwright.config.ts
export default defineConfig({
  workers: process.env.CI ? 1 : undefined,
});

I only enforce single-worker in CI, where the screenshots are actually committed. Locally, parallelism is fine for development runs. This does mean your screenshot generation step is slower in CI — a suite of 30 screenshots takes around 60–90 seconds sequentially. That's an acceptable trade for screenshots that are actually correct.

1280×800 and why you shouldn't overthink viewport size

I spent a day trying different viewports before settling on 1280×800 and never looking back. It's wide enough that responsive layouts don't collapse into mobile mode, narrow enough that you don't get enormous empty sidebars, and it matches the default render width of most documentation platforms like Docusaurus and Mintlify. Screenshots taken at this size embed in docs without needing resizing and look natural next to the text. Go wider — say 1920×1080 — and you'll crop or scale down in every doc page, which adds work and softens the image. Go narrower and you'll trigger tablet breakpoints you didn't intend to capture.

// playwright.config.ts
use: {
  viewport: { width: 1280, height: 800 },
  deviceScaleFactor: 2, // retina — worth it for modern docs
},

The deviceScaleFactor: 2 gives you retina-quality PNGs. The file size roughly doubles, but on a doc site serving images over a CDN with compression, the practical difference is minimal and the visual quality improvement on high-DPI screens is significant. If file size is genuinely constrained, drop it to 1 — but try the retina version first before optimizing away something users will notice.

Embedding Screenshots in Your Docs (Without Them Going Stale Again)

The first decision that actually matters: repo vs. CDN. I switched to committing screenshots directly into the repo because it made PRs self-contained — a UI change, a screenshot update, and the docs fix all land in the same commit. Reviewers see the diff, the old screenshot next to the new one, no context-switching. The downside is real though: a repo with 300 PNGs starts feeling bloated fast, and git clone times for new contributors go from 4 seconds to 45. S3 or a CDN gives you stable URLs, smaller clone sizes, and you can swap the image without touching the repo — but now your docs and your images are out of sync by default, and there's no git history on what the UI looked like in January. My rule: under 50 screenshots, commit them. Over that, you need a plan.

Relative paths save you from a specific kind of pain that hits when you rename a branch or restructure your docs. Instead of ![Login screen](https://docs.yoursite.com/img/login.png), use ![Login screen](../assets/screenshots/login.png). In MDX especially, a hard-coded absolute URL will silently break when you promote staging to production with a different domain, or when you set up a preview deployment on a different subdomain. The path resolves at build time, not at request time, so it's honest about what it depends on.

Docusaurus and Mintlify: Where the Files Actually Need to Go

Both tools are opinionated about this and the docs undersell how strict they are. In Docusaurus, anything you drop into static/ gets copied verbatim to the build output. So static/img/screenshots/dashboard.png becomes accessible at /img/screenshots/dashboard.png in production. In your MDX file you reference it as ![Dashboard](../../../static/img/screenshots/dashboard.png) — or use the useBaseUrl hook if you're on a subpath. The thing that caught me off guard: if you put screenshots next to your .mdx files in docs/, they do get processed, but Docusaurus runs them through its asset pipeline and you lose control of the final filename, which breaks any external links. Mintlify is simpler — drop images into a top-level images/ folder and reference them as /images/screenshots/dashboard.png. It just works, but there's no relative path support; everything is root-relative, which means you need to be consistent about your folder structure from day one.

Git LFS: The Threshold Where It Actually Pays Off

Git LFS makes sense once your screenshot folder crosses roughly 100MB total, or once you're committing new screenshots on every sprint cycle and history is growing by 20MB+ a week. The setup is four commands:

git lfs install
git lfs track '*.png'
git lfs track '*.jpg'
git add .gitattributes
git commit -m "Track images with Git LFS"

After that, PNGs get stored as pointer files in the repo and the actual binaries live in LFS storage. GitHub gives you 1GB of LFS storage free and 1GB/month bandwidth — that sounds like a lot until CI is cloning the repo 80 times a day to run screenshot tests. At that point you're paying $5/month per data pack (50GB storage + 50GB bandwidth). The gotcha nobody mentions: git lfs clone is not the same as git clone. If your CI pipeline uses a standard shallow clone without LFS support, your img tags will render broken pointer files in the build. You need to explicitly add git lfs pull to your CI steps or configure the runner to use GIT_LFS_SKIP_SMUDGE=0.

For a broader look at the tooling ecosystem — hosted doc platforms, screenshot automation SaaS, and the CI glue that holds it together — the guide on Essential SaaS Tools for Small Business in 2026 covers the full space with current pricing and tier limits.

When to Use Each Approach

I'll be direct: most teams pick the wrong tool because they evaluate it in isolation instead of asking "what problem am I actually solving?" Screenshots for documentation and screenshots for visual regression are different problems. Using the same tool for both is like using a hammer to drive screws — technically works, but you'll be annoyed every time.

Playwright self-hosted CI: full control, screenshots in repo

This is the right call when your budget is tight and you want screenshots committed directly alongside your docs. The whole thing runs in GitHub Actions (free tier covers you unless you're running hundreds of browser sessions), your screenshots live in docs/assets/ like any other file, and you own the entire pipeline. No third-party service goes down and breaks your deploy. The config looks like this:

# .github/workflows/screenshots.yml
- name: Capture docs screenshots
  run: npx playwright test --project=chromium tests/screenshots/
  env:
    BASE_URL: http://localhost:3000

- name: Commit updated screenshots
  run: |
    git config user.name "github-actions"
    git add docs/assets/screenshots/
    git diff --staged --quiet || git commit -m "chore: update docs screenshots"
    git push

The gotcha nobody warns you about: Playwright's font rendering differs slightly between Linux CI and macOS dev machines. Your screenshots will look subtly wrong — blurry text, different antialiasing — if you're taking them locally and committing them, then running comparisons in CI. Fix this by only ever generating screenshots in CI, never locally. Add a .gitattributes rule to treat PNGs as binary, otherwise git diff output becomes useless noise.

Chromatic: you're already using Storybook

If Storybook is already in your project, Chromatic is a 15-minute setup. You get visual regression diffs on every PR, a review UI where you accept or reject changes, and it integrates with GitHub status checks so you can block merges on unreviewed visual changes. The free tier gives you 5,000 snapshots per month. That sounds like a lot until you have 80 components with 4 story variants each and you're running on 3 branches simultaneously — do the math, you'll hit it faster than expected. Paid plans start at $149/month as of their current pricing page.

What Chromatic is not good at: generating screenshots you embed in markdown docs. It's a review workflow tool, not a screenshot pipeline. The snapshots live on Chromatic's servers with their URL scheme. You can't just drop them into your README. I've seen teams try to hack around this with their API and it's not worth the effort.

Percy / BrowserStack: the enterprise path

Percy makes sense when cross-browser comparison is a genuine requirement — not "we should probably test Firefox" but "our enterprise clients file bugs about Safari rendering and we have a QA SLA." If you already have a BrowserStack contract, Percy is often bundled or heavily discounted, so the incremental cost is low. The cross-browser matrix is legitimately useful: you can compare a component snapshot in Chrome, Firefox, and Safari side-by-side in one PR review. The setup requires a Percy token and their SDK wrapper around your existing test runner:

npm install --save-dev @percy/cli @percy/playwright

# Then in your test:
import { percySnapshot } from '@percy/playwright';
await percySnapshot(page, 'Dashboard - logged in state');

The honest trade-off: Percy's free tier is 5,000 snapshots/month and the paid tier jumps to $599+/month. That gap is brutal for small teams. The docs are decent but their SDK versioning has historically been messy — I've hit breaking changes between minor versions that killed CI for half a day. If you don't have a BrowserStack contract already, I wouldn't start here.

The hybrid setup I actually run

Playwright for doc screenshots committed to the repo. Chromatic for visual regression on component PRs. These solve genuinely different problems and don't overlap in a way that creates redundant cost. Playwright runs on a schedule (nightly) and when specific doc pages change, generating fresh PNGs that get committed back to main. Chromatic runs on every PR that touches src/components/, triggered by path filtering in the GitHub Actions workflow:

# In your PR workflow:
on:
  pull_request:
    paths:
      - 'src/components/**'
      - 'stories/**'

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: chromaui/action@v1
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true  # Only test stories affected by changed files

The onlyChanged: true flag is critical — without it you'll burn your snapshot budget on unrelated components every time someone edits a button. With it, a PR touching only the Modal component only runs Modal stories. My monthly Chromatic usage dropped by about 60% after adding that flag. The doc screenshots stay cheap because they're just Playwright on GitHub Actions free runners, and nobody's paying a per-snapshot fee for them.

Rough Edges I Hit That the Docs Don't Mention

The one that burned me the most: Playwright's fullPage: true option does not do what you think it does when any parent element has overflow: hidden set. The screenshot will silently clip — no error, no warning, just a truncated image that looks plausible enough to pass visual review. I wasted a full afternoon wondering why my sidebar component screenshots always cut off at 600px before I figured out what was happening. The fix is manual: you have to scroll the clipped container yourself before capturing.

// Before screenshotting a component inside an overflow:hidden parent
await page.evaluate(() => {
  document.querySelector('.your-scrollable-container').scrollTop = 0;
});

// Or if you need the full content height, temporarily override the CSS
await page.addStyleTag({ content: '.your-scrollable-container { overflow: visible !important; }' });
await page.screenshot({ path: 'output.png', fullPage: true });

The second thing: GitHub Actions artifact URLs look stable but they absolutely are not. The default retention period is 90 days, which means any artifact URL you paste into a Notion doc, an external README, or a Slack message will return a 404 by the end of the quarter. I watched a whole onboarding doc go dead because someone linked directly to screenshot artifacts from a CI run. If your screenshots need to be referenceable outside the repo, push them to a proper store — S3, Cloudflare R2, even GitHub Pages on a dedicated branch — and update the link there. Treat artifact URLs as temporary cache, not permalink storage.

Chromatic's free tier snapshot quota hits differently in a monorepo context. Their pricing counts every story across every branch, not just main. So if you have 400 Storybook stories and five engineers each working on feature branches, that's potentially thousands of snapshots per day — Chromatic charges per snapshot, and the free tier evaporates fast. I switched one project to only run Chromatic on PRs targeting main, which at least cuts down the branch noise:

# .github/workflows/chromatic.yml
on:
  pull_request:
    branches:
      - main  # Only run on PRs into main, not every push to every branch

That alone dropped our monthly snapshot count by roughly 70%. If you're in a monorepo with multiple packages, also check whether you're accidentally running Chromatic once per package — I've seen setups that triggered it four times per commit because the workflow was defined in a shared config that each package inherited.

Font rendering on the ARM-based GitHub-hosted runners is a legitimately annoying problem right now. The newer runners use Apple M1-equivalent silicon, and the antialiasing output differs enough from x86 that pixel-diff tools will flag changes that aren't real regressions. Until the ecosystem catches up, pin your runner explicitly:

jobs:
  screenshots:
    runs-on: ubuntu-22.04  # NOT ubuntu-latest — that maps to ARM on newer accounts

ubuntu-latest is the trap here. GitHub silently updates what ubuntu-latest resolves to, and if your account gets migrated to the new runner pool, your baselines will start failing overnight without any code change on your end. Pin to ubuntu-22.04, lock your Playwright version in package.json, and only upgrade both deliberately after testing your baselines locally on the same arch. The font-rendering delta is small enough to look like a bug in your component rather than an environment mismatch, which makes it genuinely hard to diagnose the first time.

---

---