Playwright Screenshots for Documentation: What to Automate and What to Review

Playwright can take the screenshot. It cannot decide whether that screenshot still belongs in your docs.

That distinction matters. Playwright's screenshot guide covers the mechanics: full-page captures, element captures, buffers, clipping, image quality, and file output. Those primitives are exactly what a docs team needs to stop retaking the same product screenshot by hand.

But documentation screenshots are not ordinary test artifacts. A product image in a setup guide is part of the instruction. It has to show the right user state, the right public UI, the right viewport, and enough surrounding context for a reader to complete a task. Automation helps only when it creates a reviewable artifact instead of a folder full of mystery PNGs.

Automate repeatable product states first

The best first candidates are screenshots where the product state is repeatable and the cost of staleness is high.

Start with the screenshots that help users finish operational tasks: creating an API key, connecting an integration, changing a billing setting, configuring OAuth, exporting data, or checking an admin permission. These screenshots usually have a known route, a stable UI target, and a docs page that depends on them. They are much better candidates than launch collages, annotated marketing images, or one-off editorial visuals.

Playwright's locator screenshot support is especially useful here because many docs images should show a panel, table, modal, or settings section rather than the entire browser window. Capturing a locator keeps the screenshot tied to the instructional object.

Put the screenshot in a scenario manifest

A Playwright test file can capture a page, but the docs team needs more than executable code. It needs a scenario record that explains why the screenshot exists.

A useful scenario manifest contains:

This manifest is not bureaucracy. It is the maintenance contract. When the UI changes, the reviewer can see what state the screenshot was supposed to show. When capture fails, the engineer can tell whether the route, fixture, selector, or docs path is wrong.

Use Playwright for readiness, not sleeps

Documentation screenshots often fail in a boring way: the browser captures too early.

A skeleton is still visible. A chart has not rendered. A toast covers the button. A font swaps after the screenshot. A menu animation has not finished. The screenshot looks plausible, but it teaches the wrong thing.

Do not hide readiness in a long timeout. Express it in the scenario. The runner should navigate to the route, select the fixture, wait for the loaded state that matters, confirm the target element is visible, and only then capture the intended locator.

Playwright's docs for screenshots show how simple the capture call can be. The hard part is the sentence before it: "This page is now in the state the docs need."

Separate visual tests from docs screenshots

Playwright also supports visual comparisons, and teams often ask whether docs screenshots should just be visual tests.

They overlap, but they are not the same workflow.

A pixel diff is useful evidence, not the final decision. If a button moved because the product shipped a better layout, the docs screenshot probably should change. If the image changed because the capture account lost access to a feature, the screenshot should not publish.

Visual comparison asks whether the UI changed unexpectedly. Documentation screenshot review asks whether the image still teaches the step correctly. The same browser capture can feed both workflows, but the decision record should be separate. Visual testing protects UI behavior. Screenshot review protects public instructions.

Store artifacts with enough context

GitHub Actions artifacts are a good place to store generated screenshots during CI. The important part is naming and metadata.

A screenshot artifact should answer basic questions without asking the reviewer to inspect CI logs. It needs the commit, scenario, route, fixture, viewport, theme, current docs asset, and whether the candidate differs from the approved version.

Use names that are readable in a CI artifact list:

settings-api-keys__one-active-key__desktop-1440__light__pr-1842.png

The file name does not need to carry everything. Pair it with a small JSON record containing route, owner, ready signal, docs path, and review status. That turns a Playwright output file into a docs artifact.

Review what automation cannot know

Automation can detect that an image changed. It cannot know whether the change is useful, public, or misleading.

Review is where docs, product, support, and engineering have different but useful perspectives. Engineering can tell whether the UI state is valid. Docs can tell whether the screenshot still supports the surrounding copy. Support can spot the states users misunderstand. Product can confirm whether the flow is ready to describe publicly. If a banner, toast, wrong account, unreleased flag, or bad crop appears in the image, the reviewer catches it before the docs inherit the mistake.

Publish only after approval

A safe pipeline has two distinct jobs:

1. Generate screenshots from Playwright scenarios.
2. Publish approved docs assets.

Do not collapse those jobs just because CI can write to the docs repo. A technically fresh screenshot can still be wrong. It can show a test account, a transient experiment, a loading state, or a feature that has not launched.

Use review states, but keep the state model simple. A screenshot is generated, changed, needs review, approved, rejected, or blocked on a scenario fix. That is enough to keep CI fast and publishing conservative without turning the workflow into a status taxonomy.

Use Reshot as the artifact layer

Reshot fits between Playwright and the docs repository. Playwright handles browser automation. GitHub Actions or another CI system runs the job. Reshot keeps the scenario, generated screenshot, metadata, review decision, and approved output together.

That lets teams automate the repeatable parts without losing editorial judgment. A practical Reshot setup defines scenarios for the screenshots that matter, runs Playwright when a scenario input changes, stores the generated image with metadata, routes changed screenshots into review, and publishes only the approved asset back to the docs path.

Playwright is the capture engine. Reshot is the place where the capture becomes a documentation artifact with state, ownership, and a decision.

Sources

• [C1] Playwright screenshots - Official screenshot primitives for page, full-page, buffer, and locator capture.
• [C2] Playwright visual comparisons - Official guidance for snapshot and visual comparison testing.
• [C3] GitHub Actions workflow artifacts - Official artifact upload, download, and retention guidance.
• [C4] shot-scraper - Open source CLI project for automated website screenshots.