PER-8985 feat: toHaveScreenshot drop-in — route existing Playwright assertions through Percy

.github/workflows/lint.yml

@@ -11,14 +11,14 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
         with:
-          node-version: 14
+          node-version: 20
       - name: Get yarn cache directory path
         id: yarn-cache-dir-path
         run: echo "::set-output name=dir::$(yarn cache dir)"
       - uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0
         with:
           path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: v1/${{ runner.os }}/node-14/${{ hashFiles('**/yarn.lock') }}
-          restore-keys: v1/${{ runner.os }}/node-14/
+          key: v1/${{ runner.os }}/node-20/${{ hashFiles('**/yarn.lock') }}
+          restore-keys: v1/${{ runner.os }}/node-20/
       - run: yarn
       - run: yarn lint

.github/workflows/test.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node: [14]
+        node: [20, 22]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions-ecosystem/action-regex-match@9e6c4fb3d5e898f505be7a1fb6e7b0a278f6665b # v2.0.2
@@ -41,6 +41,9 @@ jobs:
           key: v1/${{ runner.os }}/node-${{ matrix.node }}/${{ hashFiles('**/yarn.lock') }}
           restore-keys: v1/${{ runner.os }}/node-${{ matrix.node }}/
       - run: yarn
+      # Playwright >=1.39 no longer downloads browsers on package install — fetch the one the
+      # suite launches explicitly (system deps included for the runner image).
+      - run: npx playwright install --with-deps chromium
       - name: Set up @percy/cli from git
         if: ${{ github.event_name == 'workflow_dispatch' }}
         env:

.github/workflows/typecheck.yml

@@ -11,14 +11,14 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
         with:
-          node-version: 14
+          node-version: 20
       - name: Get yarn cache directory path
         id: yarn-cache-dir-path
         run: echo "::set-output name=dir::$(yarn cache dir)"
       - uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0
         with:
           path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: v1/${{ runner.os }}/node-14/${{ hashFiles('**/yarn.lock') }}
-          restore-keys: v1/${{ runner.os }}/node-14/
+          key: v1/${{ runner.os }}/node-20/${{ hashFiles('**/yarn.lock') }}
+          restore-keys: v1/${{ runner.os }}/node-20/
       - run: yarn
       - run: yarn test:types

.nycrc

@@ -1,5 +1,5 @@
 {
-  "exclude": ["test"],
+  "exclude": ["test", "dropin", "bin"],
   "check-coverage": true,
   "branches": 100,
   "lines": 100,

README.md

@@ -61,6 +61,74 @@ $ percy exec -- node script.js
 - `options` - [See per-snapshot configuration options](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#per-snapshot-configuration)
 
 
+## toHaveScreenshot drop-in
+
+Route your existing Playwright `expect(...).toHaveScreenshot()` assertions through Percy with
+**one config line and no test changes**:
+
+```js
+// playwright.config.js
+require('@percy/playwright/dropin'); // registers the toHaveScreenshot override
+
+module.exports = defineConfig({ /* your config */ });
+```
+
+```bash
+PERCY_TOKEN=<web-project-token> npx percy exec -- npx playwright test
+```
+
+Just the standard `percy exec` — no wrapper, no extra flags. Capture dispatches automatically by
+your **project token**:
+
+| Project | Flow |
+|---|---|
+| **Web** | Every `toHaveScreenshot()` becomes a Percy web snapshot: the live page is serialized with the same capture `percySnapshot()` uses (readiness gate, responsive capture, cross-origin iframes) and Percy renders it server-side. Locator subjects become element-scoped snapshots. |
+| **App** | The captured PNG uploads straight through the comparison ingest — no render flow, exactly how App Percy ingests screenshots. |
+| anything else | A clear wrong-token configuration error (use `percyScreenshot()` for Automate). |
+
+The assertion **always passes locally** — the visual verdict moves to Percy's review UI, and a
+missing/invalid token or any Percy error **never fails your suite** (the whole run falls back to
+native `toHaveScreenshot`).
+
+### Your committed baselines become the first build — automatically
+
+On a **new (empty) Percy project**, `percy exec` detects this package plus the Playwright baseline
+PNGs already committed in your repo (`*-snapshots` directories) and establishes the baseline before
+your tests run:
+
+1. **Build #1** — your committed screenshots are uploaded directly (the suite does NOT run for
+   this) and the build is auto-approved server-side: these are the baselines you've already
+   blessed.
+2. **Build #2** — your actual command runs and diffs against that baseline immediately.
+
+With no committed screenshots, the first run itself becomes the auto-approved baseline (matching
+native Playwright's "first run writes the baselines" behavior). The Percy API decides first-ness
+from the project token — the flag can never re-baseline an established project.
+
+### Existing projects: `percy playwright:setup-baseline`
+
+On a project that already has builds, `percy exec` never re-baselines — it prints a notice and
+carries on. To deliberately (re-)establish the baseline from your committed screenshots (no tests
+run, auto-approved):
+
+```bash
+PERCY_TOKEN=<web-project-token> npx percy playwright:setup-baseline
+```
+
+An optional CI gate is available via `reporter: [['@percy/playwright/dropin/reporter']]` with
+`{ "gate": "fail-on-changes" }`.
+
+### Disabling the drop-in
+
+To keep `toHaveScreenshot()` **fully native** (local pixel compare, including the
+missing-baseline behavior) while still using `percySnapshot()`/`percyScreenshot()` under
+`percy exec`, either set `{ "enabled": false }` in `.percy-playwright-dropin.json` or export
+`PERCY_DROPIN_DISABLE=true` (the env var also turns off `percy exec`'s baseline seeding). The
+override steps aside entirely — no snapshots are posted for `toHaveScreenshot()` assertions.
+
+Requires `@playwright/test` >= 1.49 (the override hooks Playwright's expect internals; on
+unsupported versions it degrades to a no-op **with a loud warning** — never silently).
+
 ## Percy on Automate
 
 ## Usage

commands/setup-baseline.mjs

@@ -0,0 +1,91 @@
+// `percy playwright:setup-baseline` — explicitly (re-)establish a Percy project's baseline from
+// the Playwright baseline screenshots committed in the repo, WITHOUT running any tests.
+//
+// Discovered by @percy/cli through this package's `"@percy/cli": { "commands": [...] }` entry
+// (the same mechanism @percy/storybook uses), so installing @percy/playwright is all it takes.
+// Unlike the automatic first-build seeding `percy exec` performs on an empty project, this
+// command works on ESTABLISHED projects too: the build is created with the explicit
+// `dropin-baseline-setup` attribute the API accepts as a deliberate, user-triggered re-baseline
+// and auto-approves at finalize.
+//
+// ESM on purpose: @percy/cli-command and @percy/cli-exec are ESM-only; the CLI imports command
+// modules with dynamic import, so this file never enters the (CJS) SDK require graph.
+import command from '@percy/cli-command';
+
+const BASELINE_SOURCE = 'playwright-dropin-baseline';
+
+export const setupBaseline = command('setup-baseline', {
+  description: 'Upload committed Playwright baseline screenshots as the auto-approved Percy baseline (no tests run)',
+
+  examples: [
+    '$0'
+  ],
+
+  percy: {
+    skipDiscovery: true
+  }
+}, async function * ({ percy, log, exit }) {
+  if (!percy) exit(1, 'Percy is disabled');
+
+  // Web projects seed rendered snapshots; app projects seed raw comparison uploads (no render
+  // flow — like App Percy). Anything else is a wrong token.
+  let { SUPPORTED_PROJECT_TYPES, wrongTokenError } = await import('../dropin/config.js')
+    .then(m => m.default || m);
+  let projectType = percy.client.tokenType();
+  if (!SUPPORTED_PROJECT_TYPES.includes(projectType)) {
+    exit(1, wrongTokenError(projectType, { context: 'playwright:setup-baseline' }));
+  }
+
+  // The provider owns all Playwright knowledge (config resolution, snapshot discovery, identity
+  // mapping); the CLI's exec package owns the upload loop. Nothing is reimplemented here.
+  let { default: provider } = await import('../dropin/baseline/provider.js');
+
+  // uploadBaselines ships in the companion @percy/cli release — an older CLI resolves the
+  // package but not the export. Fail with guidance, not a bare TypeError.
+  let uploadBaselines;
+  try {
+    ({ uploadBaselines } = await import('@percy/cli-exec'));
+  } catch { /* handled below */ }
+  if (typeof uploadBaselines !== 'function') {
+    exit(1, 'playwright:setup-baseline requires a newer @percy/cli — ' +
+      'upgrade with `npm i -D @percy/cli@latest` and retry.');
+  }
+
+  let { baselines = [], degraded, reason } =
+    (await provider.discoverBaselines({ cwd: process.cwd(), log })) || {};
+
+  if (degraded) {
+    exit(1, `Could not map your committed Playwright baselines (${reason}). ` +
+      'Custom snapshot path templates and projects without an explicit browser/viewport ' +
+      'cannot be mapped automatically.');
+  }
+  if (!baselines.length) {
+    exit(1, 'No committed Playwright baseline screenshots found ' +
+      '(looked for Playwright\'s *-snapshots directories).');
+  }
+
+  log.info(`Uploading ${baselines.length} committed baseline snapshot(s) as the project baseline...`);
+
+  let res = await percy.client.createBuild({
+    projectType,
+    source: BASELINE_SOURCE,
+    dropinBaselineSetup: true
+  });
+
+  let buildId = res.data.id;
+  let seeded = await uploadBaselines(percy.client, buildId, baselines, { log, projectType });
+  await percy.client.finalizeBuild(buildId);
+
+  if (!seeded) exit(1, 'No baseline snapshots could be uploaded.');
+
+  log.info(`Baseline established from ${seeded}/${baselines.length} snapshot(s) and ` +
+    `auto-approved: ${res.data.attributes['web-url']}`);
+});
+
+// Topic wrapper so the command surfaces as `percy playwright:setup-baseline`.
+export const playwright = command('playwright', {
+  description: 'Playwright drop-in utilities',
+  commands: [setupBaseline]
+});
+
+export default playwright;

dropin/baseline/config-reporter.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// Playwright reporter used ONLY to capture the RESOLVED config outside a test run.
+//
+// Baseline discovery (discover.js) reconstructs snapshot identity from the resolved config
+// (projects' browserName/viewport, snapshot path templates). Inside a test run that config came
+// from globalSetup's FullConfig; the CLI-driven seeding flow runs BEFORE any test run, so
+// resolve-config.js spawns `npx playwright test --list --reporter=<this file>` — Playwright
+// resolves its own config (including TS configs) and hands it to `onBegin`, which serializes the
+// minimal shape discovery needs to the file named by PERCY_PW_CONFIG_OUT. `--list` performs test
+// discovery only; no test executes.
+const fs = require('fs');
+
+const screenshotTpl = obj =>
+  obj && obj.expect && obj.expect.toHaveScreenshot && obj.expect.toHaveScreenshot.pathTemplate;
+
+class PercyConfigReporter {
+  onBegin(config) {
+    const out = process.env.PERCY_PW_CONFIG_OUT;
+    if (!out) return;
+
+    const shape = {
+      rootDir: config.rootDir,
+      snapshotDir: config.snapshotDir,
+      snapshotPathTemplate: config.snapshotPathTemplate,
+      expect: screenshotTpl(config)
+        ? { toHaveScreenshot: { pathTemplate: screenshotTpl(config) } }
+        : undefined,
+      projects: (config.projects || []).map(p => ({
+        name: p.name || '',
+        use: {
+          browserName: p.use && p.use.browserName,
+          viewport: p.use && p.use.viewport
+        },
+        snapshotPathTemplate: p.snapshotPathTemplate,
+        expect: screenshotTpl(p)
+          ? { toHaveScreenshot: { pathTemplate: screenshotTpl(p) } }
+          : undefined
+      }))
+    };
+
+    // Local-only handoff: resolve-config.js (the spawning side) reads this file immediately and
+    // deletes it in its `finally` — nothing here is uploaded or persisted beyond the one call.
+    fs.writeFileSync(out, JSON.stringify(shape));
+  }
+
+  // Keep `--list` output clean; this reporter only writes the config file.
+  printsToStdio() {
+    return false;
+  }
+}
+
+module.exports = PercyConfigReporter;