feat(cli-pdf): native PDF visual testing via POST /percy/pdf/snapshot

[RaghavsBrowserStack]

What

Adds first-class PDF visual testing to the CLI. An SDK hands over PDF bytes; the CLI rasterizes the document and creates one Percy snapshot per page, optionally blocking on synchronous comparison results.

This is the in-CLI replacement for the external percy-pdf solution, which can be retired once this ships.

const { postPdfSnapshot } = require('@percy/sdk-utils');

const result = await postPdfSnapshot({
  name: 'Burglary Insurance Policy',
  sync: true,
  pdf: { content: fs.readFileSync('policy.pdf').toString('base64') },
  excludePages: [4, 7]
});
// result.body.data.pages[] -> one entry per page, each with its own diff-info

Why not the old approach

percy-pdf wrapped the CLI from the outside: it unzipped a 5.8 MB pdf.js viewer, served it over http-server, generated a percy snapshot YAML config per document, and captured pages by having Percy's renderer run the viewer and deleting already-captured div.page children from the DOM between snapshots so scope: .canvasWrapper would land on the next page.

That design carried three bugs that are unrepresentable in this one:

1. Page filtering mislabelled snapshots. The per-page execute script was assigned inside a forEach over every previously-pushed snapshot, so all snapshots ended up with the last page's script. Any gap from excludePages meant every later page captured the wrong page under the right name.
2. Page 1 and the second-to-last page could not be excluded — page 1 was structurally the base snapshot, and the second-to-last was entangled with the viewer's page-prefetch step. excludePages: [1] now just works.
3. Page counts were read from the baseline directory even when comparing a release, so a release with extra pages silently lost them.

How it's implemented

Rendering happens in the discovery browser

The CLI already launches Chromium eagerly — percy.start() runs if (!this.skipDiscovery) yield this.#discovery.start(), whose start handler calls percy.browser.launch(). During a PDF-only run that browser sits completely idle: every discovery queueInfo line reports {"queued":0,"pending":0,"total":0}, because percy.upload() bypasses discoverSnapshotResources.

So pdf.js runs in a browser page rather than in Node. An earlier revision of this PR rasterized with @napi-rs/canvas (Skia); that shipped ~25MB of platform-specific native prebuilds to duplicate a renderer already present and running, and has been removed. A second benefit: rendering is now the CLI's pinned Chromium revision, so page rasters are as reproducible as the rest of Percy's pipeline instead of tracking a separately versioned native dependency.

@percy/cli-pdf (new package) — helpers and pdf.js assets

No reference to @percy/core, which is what lets core list it as an optionalDependency without a cycle. Its only heavyweight cost is pdfjs-dist's ~34MB of library, fonts and cmaps, which nobody installs unless they snapshot a PDF.

Module	Responsibility
pages.js	resolvePages() — parses 3, [1,2,5], "1-5", "1,3,8", "2-"; applies excludePages; validates against the real page count
browser-scripts.js	The functions that execute inside the page (openDocument, measurePages, renderPage, destroyDocument) plus the scale/dimension limits
assets.js	pdfjsAssets() — the installed pdfjs-dist paths the asset server and page injection need

The wrapper DOM is not in this package — it is shared with @percy/cli-upload, see below.

@percy/core/src/pdf-rasterize.js — the browser work

rasterizePdf(percy, buffer, options) stands up a throwaway loopback origin (Server.serve) exposing pdf.js, its worker, standard_fonts, cmaps and the document itself; opens an isolated page on it; injects pdf.js; then measures and renders each selected page to a PNG data URL.

Serving the assets over a real origin is what makes standard fonts work. pdf.js fetches standardFontDataUrl / cMapUrl over HTTP at render time, and the base-14 fonts (Helvetica, Times…) aren't embedded in most documents — without a reachable origin pdf.js renders wrong metrics or drops glyphs and only warns. isEvalSupported: false is still passed, because the PDF itself is untrusted input.

It calls percy.browser.launch() explicitly. That's idempotent (if (this.readyState != null) return), and it makes PDF snapshots work under skipDiscovery, where the eager launch doesn't happen.

@percy/core — the endpoint

POST /percy/pdf/snapshot → src/pdf-snapshot.js, which validates the request, decodes the base64 document (50 MB cap and %PDF- magic-byte check, matching /percy/comparison/upload), lazily imports @percy/cli-pdf, and fans out.

Each page carries resources and no tag, so createSnapshotsQueue's task handler picks client.sendSnapshot over sendComparison: these are real web snapshots, not comparisons. resources is passed as a function (the lazy-resource pattern cli-upload uses) so the root-DOM and resource-object construction is deferred into the queue task.

Concurrency, precisely

Stage	Behaviour
Rendering pages → PNG	Sequential, one page.eval per page against a single browser page.
Queuing the N snapshots	All at once, non-blocking. All pages are pushed via percy.upload() in a single synchronous pass.
Uploading	Concurrent, up to the snapshots queue's concurrency (discovery.concurrency, default 10).
Polling for completion	One shared batched poll. WaitForJob collects every pending job id and issues a single getStatus (job_status?...&id=a,b,c) per interval, so a 10-page PDF costs one request per poll, not ten.
Fetching final details	Parallel — Promise.all over handleSyncJob.

Only rasterization is serial; nothing blocks page-by-page.

Sync mode attaches { resolve, reject } per page (mirroring the /percy/comparison route), then aggregates each page's handleSyncJob result. handleSyncJob converts failures into { error } rather than rejecting, so one bad page yields a partial result instead of losing every other page's.

@percy/sdk-utils — the shared seam

postPdfSnapshot(), exported alongside postSnapshot, so all SDKs can re-export it.

Pages are extracted, not rendered

percy-api can skip the renderer entirely for image-backed snapshots. Comparison#upload_snapshot? (app/models/percy/comparison.rb) gates on exactly two things:

unless user_agent&.include?('@percy/cli-upload')   # substring match
unless resource_url&.include?('http://local/')     # the ROOT resource URL

When both hold, start_comparison_job.rb calls extract_and_process_upload_snapshot, which recovers the image by matching the root resource against /<img\s+src="([^"]+)"\s+width="(\d+)px"\s+height="(\d+)px"/ and returns before RenderJob is enqueued.

An earlier revision of this PR was not taking that path, so every PDF page was fully re-rendered by the renderer fleet despite the CLI already having produced the exact PNG. Measured on the same 3-page document:

	Per-page processing
Rendered (no marker)	19s, 11s, 9s
Extracted	1s, 1s, 1s

The endpoint now tags the build's User-Agent with @percy/cli-pdf/<version> and @percy/cli-upload/<version>. The gate is a substring match, so naming both unlocks extraction while keeping the UA honest about which code actually ran, rather than impersonating the upload command.

One wrapper, shared with cli-upload

That wrapper HTML is a contract with percy-api, not cosmetics — and a mismatch is not an error: extraction raises, percy-api rescues it, and the snapshot silently falls back to being rendered at ~10x the processing cost, with nothing surfaced to the user.

It therefore has exactly one definition, buildImageSnapshotHtml / createImageSnapshotResources in @percy/core's utils.js. cli-upload's getImageResources delegates to it, and the PDF path uses it. core cannot import cli-upload (cli-upload -> cli-command -> core would cycle), but cli-upload already reaches core's utils through @percy/cli-command/utils, so this needs no new dependency. cli-upload's existing suite passes unchanged, confirming byte-identical output.

core/test/image-snapshot-resources.test.js pins percy-api's regex verbatim so drift fails CI instead of degrading silently in production.

Operator note: upload_extraction_allowed? only short-circuits on a project's default base branch. Elsewhere it mirrors the base comparison's upload_snapshot_extracted flag, so baselines taken before this change must be regenerated before comparison builds will extract.

Two contract decisions worth calling out

The document travels as base64 in an ordinary JSON body, and the sync response is always a JSON object, never a bare array. Both exist so every SDK can call this with the HTTP client it already has. Concretely, for the .NET wrapper: the request goes through its existing Dictionary<string, object> → JsonSerializer helper, and the response through its existing JObject.Parse — no multipart, no streaming, no new HTTP machinery. The cost is base64's 33% inflation, which is the right trade for a one-line integration across ~26 SDKs.

Sync response shape

{
  "success": true,
  "data": {
    "pdf-name": "Burglary Insurance Policy",
    "page-count": 3,
    "pages-snapshotted": 3,
    "status": "success",
    "pages": [
      { "page": 1, "snapshot-name": "Burglary Insurance Policy | Page 1",
        "screenshots": [ { "diff-info": { "diff-ratio": 0 } } ] },
      { "page": 2, "snapshot-name": "Burglary Insurance Policy | Page 2",
        "screenshots": [ { "diff-info": { "diff-ratio": 0.00085774 } } ] }
    ]
  }
}

page and snapshot-name are set after the API payload is spread in, so the values we submitted always win over whatever the API echoes back — otherwise a change in the API's naming would silently break the caller's page mapping.

Notes for reviewers

• Snapshot names match percy-pdf exactly (<name> | Page N) so teams migrating keep their approved baselines instead of orphaning every one.
• No percy pdf <dir> command, deliberately. percy.syncMode() force-disables sync under skipUploads/deferUploads/delayUploads, which is exactly what the snapshot and upload commands set. A command could therefore never return comparison results, so PDF support is reachable only through this endpoint under percy exec.
• Oversized pages are fitted, not rejected. Legal (1224×2016 at scale 2) and A3 exceed Percy's 2000 px cap and are precisely the documents this targets, so fitScale() reduces the scale deterministically from the page's own dimensions and warns. Deterministic from page geometry means the same document always rasterizes identically, which is what a stable baseline needs.
• pdfjs-dist pinned to 4.x, not 6.x — 6.x requires Node >= 22.13, while 4.8.69 needs only Node >= 18, matching the CLI's engine range.
• standardFontDataUrl and cMapUrl are configured explicitly. Without them pdf.js renders standard fonts with wrong metrics or drops CJK glyphs and only warns, which would surface as a mysterious visual diff rather than an error.
• isEvalSupported: false — PDFs are untrusted input arriving over the local API, and this is the one pdf.js switch that permits code execution.
• standardFontDataUrl / cMapUrl are served, not configured away. Without them pdf.js renders standard fonts with wrong metrics or drops CJK glyphs, and only warns — which would surface as a mysterious visual diff rather than an error.
• new Function(pdfjsSource) mirrors page.insertPercyDom() (page.js:239); the input is pdfjs-dist's own vendored file, never user data.
• Baselines from the earlier revision of this PR must be regenerated, since the rasterizer changed from Skia to Chromium.

A bug caught during development

The first end-to-end run reported max diff-ratio=0 for a document that genuinely differed — both the passing and failing functional tests passed vacuously.

The wrapper (then a PDF-local buildPageHtml, since replaced by the shared one) ran encodeURI over an already percent-encoded image URL, turning %20 into %2520. The <img src> then matched no registered resource, so every page rendered as the same blank sheet and all pages collapsed to a single image hash. It surfaced only by noticing that page 2 and page 3 shared a current-image hash in the raw sync payload.

Fixed to HTML-escape only. The guards now live in packages/core/test/image-snapshot-resources.test.js ("does not re-encode an already-encoded URL", "keeps the img src and the image resource URL identical") and packages/core/test/pdf-snapshot.test.js ("attaches a root DOM whose img src matches the image resource", "gives each page a distinct image resource"). This is a failure mode that reports green, so it is worth guarding directly.

Node compatibility

pdfjs-dist is pinned to 2.16.105, the last line that declares no engines constraint. 3.x and later declare node: ">=18", and since yarn enforces engines across the whole tree, anything newer breaks yarn install on the repo's Node 14 CI — not just for PDF users, but for everyone. @percy/cli-pdf therefore declares >=14, matching its sibling packages.

Testing

Suite	Result
@percy/cli-pdf	32/32 pass
@percy/core (test/pdf-snapshot.test.js, 19 specs)	19/19 pass
@percy/sdk-utils (postPdfSnapshot, 5 specs)	5/5 pass
eslint on all changed files	clean

Verified end to end against a real Percy project using a Selenium + Mocha harness that drives a browser, downloads a PDF via a download button, and hands the bytes to this endpoint:

• unchanged document → all 3 pages diff-ratio 0, exit 0
• document changed on page 2 only → exit 1, page 2 … diff-ratio 0.00085774, while pages 1 and 3 report 0

That last line is the point of per-page snapshots: a one-page change in a multi-page document is localised rather than flagging the whole file.

Follow-ups

• SDK wrappers exposing postPdfSnapshot. A Percy.PdfSnapshot(string name, byte[] pdf, Dictionary<string, object>? options) implementation for percy-selenium-dotnet is written against this contract and reuses its existing Request() helper unchanged; it will be raised separately.
• Customer-facing docs, and a deprecation notice on percy-pdf pointing here.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Workspace UI (inherited)

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 9b191b40-9138-4295-8f7d-168fa307c7b6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}