PPLT-6073: native PDF visual testing via POST /percy/pdf/snapshot

.github/workflows/test.yml

@@ -72,6 +72,7 @@ jobs:
           - '@percy/cli-exec'
           - '@percy/cli-snapshot'
           - '@percy/cli-upload'
+          - '@percy/cli-pdf'
           - '@percy/cli-build'
           - '@percy/cli-config'
           - '@percy/sdk-utils'
@@ -302,6 +303,15 @@ jobs:
         run: yarn test:regression:config
       - name: Run functional discovery tests (token-free)
         run: yarn test:regression:functional
+      # Compares rendered PDF pages byte-for-byte against the linux-x64
+      # goldens. PNG bytes are only reproducible for one platform + Chromium
+      # build (Percy pins a different Chromium snapshot per platform, and glyph
+      # rasterization goes through CoreText on macOS vs FreeType on Linux), so
+      # these goldens were generated on this runner and only this job asserts on
+      # them. Regenerate after a Chromium bump by re-running this step with
+      # UPDATE_PDF_GOLDENS=1 and committing the result.
+      - name: Run PDF rasterization byte tests (token-free)
+        run: yarn test:regression:pdf
       # Visual track runs last and is the ONLY step that creates a Percy build,
       # so the PR's single build carries all visual snapshots (no stray build
       # superseding it on the same commit).

.semgrepignore

@@ -61,3 +61,16 @@ packages/cli-command/src/intelliStory.js
 # to assert no `require()` bindings leak in; the traversal roots are static
 # literals, no user input flows here. semgrep flags the path.join() anyway.
 packages/cli-command/test/noRequireBinding.test.js
+
+# The PDF byte-comparison regression track (test/regression/pdf-render.test.js
+# and its helper) joins paths from three local sources only: `platformKey()`,
+# which is `${process.platform}-${process.arch}`; a slug that slugify() has
+# already reduced to [a-z0-9-] via basename(); and PDF filenames read straight
+# out of the committed fixture directory with fs.readdirSync. No request or
+# user input reaches these joins — the track runs offline against checked-in
+# fixtures and creates no Percy build. semgrep's
+# javascript.lang.security.audit.path-traversal.path-join-resolve-traversal
+# rule flags the joins regardless, and inline `// nosemgrep` is not honored by
+# the CI semgrep version — suppress at the file level with this rationale.
+test/regression/lib/pdf-render.js
+test/regression/pdf-render.test.js

package.json

@@ -26,7 +26,8 @@
     "global:unlink": "lerna exec -- yarn unlink",
     "test:regression": "node test/regression/regression.test.js",
     "test:regression:config": "node test/regression/config-validation.test.js",
-    "test:regression:functional": "node test/regression/functional.test.js"
+    "test:regression:functional": "node test/regression/functional.test.js",
+    "test:regression:pdf": "node test/regression/pdf-render.test.js"
   },
   "devDependencies": {
     "@babel/cli": "^7.11.6",

packages/cli-pdf/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@percy/cli-pdf",
+  "version": "1.32.10-beta.0",
+  "license": "MIT",
+  "description": "Renders PDF documents into per-page images for Percy snapshots",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/percy/cli",
+    "directory": "packages/cli-pdf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "scripts": {
+    "build": "node ../../scripts/build",
+    "lint": "eslint --ignore-path ../../.gitignore .",
+    "test": "node ../../scripts/test",
+    "test:coverage": "yarn test --coverage"
+  },
+  "dependencies": {
+    "@percy/logger": "1.32.10-beta.0",
+    "pdfjs-dist": "^2.16.105"
+  }
+}

packages/cli-pdf/src/assets.js

@@ -0,0 +1,17 @@
+import path from 'path';
+import { createRequire } from 'module';
+
+const cjsRequire = createRequire(import.meta.url);
+
+export function pdfjsAssets() {
+  let root = path.dirname(cjsRequire.resolve('pdfjs-dist/package.json'));
+
+  return {
+    root,
+    buildDir: path.join(root, 'legacy/build'),
+    standardFontsDir: path.join(root, 'standard_fonts'),
+    cmapsDir: path.join(root, 'cmaps'),
+    libPath: path.join(root, 'legacy/build/pdf.js'),
+    workerFile: 'pdf.worker.js'
+  };
+}

packages/cli-pdf/src/browser-scripts.js

@@ -0,0 +1,101 @@
+export const MIN_DIMENSION = 10;
+export const MAX_DIMENSION = 2000;
+
+export const DEFAULT_SCALE = 2;
+export const MAX_SCALE = 5;
+
+// Wall-clock ceiling for a single page's in-page work (open, measure, render).
+// Page#eval resolves off `Runtime.callFunctionOn` with `awaitPromise: true`,
+// which has no timeout of its own -- Page.TIMEOUT only covers navigation. A PDF
+// that wedges pdf.js would otherwise hang the HTTP request forever while
+// holding a browser page and a listening asset server.
+export const PAGE_RENDER_TIMEOUT = 30000;
+
+export function fitScale(requestedScale, { width, height }) {
+  return Math.min(requestedScale, MAX_DIMENSION / width, MAX_DIMENSION / height);
+}
+
+export function assertRasterDimensions(pageNumber, width, height) {
+  if (width < MIN_DIMENSION || height < MIN_DIMENSION) {
+    throw new Error(
+      `Page ${pageNumber} rasterized to ${width}x${height}px, below Percy's ` +
+      `${MIN_DIMENSION}px minimum. Increase \`scale\`.`
+    );
+  }
+}
+
+export async function openDocument(_, { origin }) {
+  let lib = window['pdfjs-dist/build/pdf'] || window.pdfjsLib;
+
+  if (!lib) {
+    throw new Error('pdf.js did not initialise in the page');
+  }
+
+  lib.GlobalWorkerOptions.workerSrc = `${origin}/pdfjs/pdf.worker.js`;
+
+  let doc = await lib.getDocument({
+    url: `${origin}/doc.pdf`,
+    isEvalSupported: false,
+    standardFontDataUrl: `${origin}/standard_fonts/`,
+    cMapUrl: `${origin}/cmaps/`,
+    cMapPacked: true
+  }).promise;
+
+  window.__percyPdf = { lib, doc };
+
+  return { pageCount: doc.numPages };
+}
+
+export async function measurePages(_, { pageNumbers }) {
+  let { doc } = window.__percyPdf;
+  let sizes = [];
+
+  for (let pageNumber of pageNumbers) {
+    let page = await doc.getPage(pageNumber);
+    let { width, height } = page.getViewport({ scale: 1 });
+    sizes.push({ pageNumber, width, height });
+    page.cleanup();
+  }
+
+  return sizes;
+}
+
+export async function renderPage(_, { pageNumber, scale }) {
+  let { doc } = window.__percyPdf;
+  let page = await doc.getPage(pageNumber);
+
+  try {
+    let viewport = page.getViewport({ scale });
+    let width = Math.ceil(viewport.width);
+    let height = Math.ceil(viewport.height);
+
+    let canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+
+    let context = canvas.getContext('2d');
+    context.fillStyle = '#ffffff';
+    context.fillRect(0, 0, width, height);
+
+    await page.render({ canvasContext: context, viewport }).promise;
+
+    return {
+      width,
+      height,
+      dataUrl: canvas.toDataURL('image/png')
+    };
+  } finally {
+    page.cleanup();
+  }
+}
+
+export async function destroyDocument() {
+  let state = window.__percyPdf;
+
+  if (state?.doc) {
+    await state.doc.destroy();
+    delete window.__percyPdf;
+  }
+
+  return true;
+}

packages/cli-pdf/src/index.js

@@ -0,0 +1,15 @@
+export { pdfjsAssets } from './assets.js';
+export { resolvePages, MAX_PAGES } from './pages.js';
+export {
+  openDocument,
+  measurePages,
+  renderPage,
+  destroyDocument,
+  fitScale,
+  assertRasterDimensions,
+  DEFAULT_SCALE,
+  MAX_SCALE,
+  PAGE_RENDER_TIMEOUT,
+  MIN_DIMENSION,
+  MAX_DIMENSION
+} from './browser-scripts.js';

packages/cli-pdf/src/pages.js

@@ -0,0 +1,89 @@
+// Ceiling on how many pages one request may rasterize. Every page is held in
+// memory as a PNG twice over -- once in the rasterizer's result array, once in
+// the resource closure the snapshot queue keeps -- and each additionally crosses
+// CDP as a base64 data URL. A 50MB PDF can carry thousands of pages, so without
+// a cap a single request can exhaust the heap. Callers who genuinely want more
+// can narrow with `pages` and issue several requests.
+export const MAX_PAGES = 250;
+
+function parseSelection(value, pageCount) {
+  if (value == null) return range(1, pageCount);
+  if (typeof value === 'number') return [toPageNumber(value)];
+  if (Array.isArray(value)) return value.map(toPageNumber);
+
+  if (typeof value !== 'string') {
+    throw new Error(`Invalid page selection: expected a number, array or string, got ${typeof value}`);
+  }
+
+  let selected = [];
+
+  for (let part of value.split(',')) {
+    part = part.trim();
+    if (!part) continue;
+
+    let match = /^(\d+)\s*-\s*(\d+)?$/.exec(part);
+
+    if (match) {
+      let from = toPageNumber(match[1]);
+      let to = match[2] == null ? pageCount : toPageNumber(match[2]);
+      if (to < from) throw new Error(`Invalid page range "${part}": end page is before start page`);
+      selected.push(...range(from, to));
+    } else if (/^\d+$/.test(part)) {
+      selected.push(toPageNumber(part));
+    } else {
+      throw new Error(`Invalid page selection "${part}": expected a page number or a range like "2-5"`);
+    }
+  }
+
+  return selected;
+}
+
+function toPageNumber(value) {
+  let n = Number(value);
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`Invalid page number "${value}": page numbers are 1-based integers`);
+  }
+  return n;
+}
+
+function range(from, to) {
+  let out = [];
+  for (let i = from; i <= to; i++) out.push(i);
+  return out;
+}
+
+export function resolvePages({ pages, excludePages } = {}, pageCount) {
+  if (!Number.isInteger(pageCount) || pageCount < 1) {
+    throw new Error(`Invalid page count: ${pageCount}`);
+  }
+
+  let selected = parseSelection(pages, pageCount);
+  let excluded = new Set(excludePages == null ? [] : parseSelection(excludePages, pageCount));
+
+  let outOfRange = [...new Set(selected.filter(p => p > pageCount))];
+  if (outOfRange.length) {
+    throw new Error(
+      `Requested page${outOfRange.length > 1 ? 's' : ''} ${outOfRange.join(', ')} ` +
+      `but the document has only ${pageCount} page${pageCount > 1 ? 's' : ''}`
+    );
+  }
+
+  let resolved = [...new Set(selected)]
+    .filter(p => !excluded.has(p))
+    .sort((a, b) => a - b);
+
+  if (!resolved.length) {
+    throw new Error('No pages left to snapshot after applying `pages` and `excludePages`');
+  }
+
+  if (resolved.length > MAX_PAGES) {
+    throw new Error(
+      `Requested ${resolved.length} pages but the maximum per request is ${MAX_PAGES}. ` +
+      'Narrow the selection with `pages` (for example "1-100") and issue several requests.'
+    );
+  }
+
+  return resolved;
+}
+
+export { parseSelection as _parseSelection };

packages/cli-pdf/test/.eslintrc

@@ -0,0 +1,6 @@
+env:
+  jasmine: true
+rules:
+  import/no-extraneous-dependencies: off
+  no-return-assign: off
+  no-sequences: off

packages/cli-pdf/test/assets.test.js

@@ -0,0 +1,29 @@
+import fs from 'fs';
+import path from 'path';
+import { pdfjsAssets } from '../src/assets.js';
+
+describe('@percy/cli-pdf assets', () => {
+  let assets = pdfjsAssets();
+
+  it('resolves the installed pdfjs-dist root', () => {
+    expect(fs.existsSync(path.join(assets.root, 'package.json'))).toBe(true);
+  });
+
+  it('points at the legacy build directory', () => {
+    expect(fs.existsSync(assets.buildDir)).toBe(true);
+    expect(fs.existsSync(path.join(assets.buildDir, 'pdf.js'))).toBe(true);
+    expect(fs.existsSync(path.join(assets.buildDir, assets.workerFile))).toBe(true);
+  });
+
+  it('points at the font and cmap data pdf.js fetches at runtime', () => {
+    expect(fs.existsSync(assets.standardFontsDir)).toBe(true);
+    expect(fs.existsSync(assets.cmapsDir)).toBe(true);
+    expect(fs.readdirSync(assets.standardFontsDir).length).toBeGreaterThan(0);
+    expect(fs.readdirSync(assets.cmapsDir).length).toBeGreaterThan(0);
+  });
+
+  it('exposes the injectable pdf.js library file', () => {
+    expect(fs.existsSync(assets.libPath)).toBe(true);
+    expect(fs.readFileSync(assets.libPath, 'utf-8')).toContain('getDocument');
+  });
+});