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,92 @@
+// `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). Automate projects are drop-in supported but NOT seedable — their
+  // baseline comes from the first remote run — and anything else is a wrong token.
+  let { SEEDABLE_PROJECT_TYPES, seedingUnsupportedError } = await import('../dropin/config.js')
+    .then(m => m.default || m);
+  let projectType = percy.client.tokenType();
+  if (!SEEDABLE_PROJECT_TYPES.includes(projectType)) {
+    exit(1, seedingUnsupportedError(projectType));
+  }
+
+  // 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/automate.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// Screenshot seam for the toHaveScreenshot drop-in — the AUTOMATE-project dispatch target.
+//
+// This is a thin wrapper around the repo's own `percyScreenshot()` (index.js): the drop-in hands
+// off to the EXACT Percy-on-Automate entry point a hand-written `percyScreenshot(page, name)`
+// test would use, so it inherits the session-details lookup, the CLI `/percy/automateScreenshot`
+// handoff and the remote capture — nothing is reimplemented here and the two entry points can
+// never drift apart.
+//
+// SEMANTICS (vs the web/app flows): the capture happens on the REMOTE BrowserStack browser via
+// the Automate session — no local pixels or DOM ever leave the test process, and the comparison
+// tag identity (browser/os/width/device) comes from the real session, not from the Playwright
+// config. That has two consequences surfaced here:
+//   • The suite MUST be running on BrowserStack Automate (e.g. via browserstack-node-sdk). A
+//     local browser has no session to capture through — that is a configuration error, reported
+//     with a clear message instead of percyScreenshot's raw JSON-parse noise.
+//   • Locator subjects and raw-pixel options (mask/clip/…) cannot apply to a remote capture;
+//     they degrade to a full-page capture and are surfaced once at warn level.
+const utils = require('@percy/sdk-utils');
+const { Utils } = require('../utils');
+
+const log = utils.logger('playwright-dropin');
+
+// Lazy-required at capture time: the root module may itself be mid-load when the drop-in entry is
+// evaluated (specs import both as ESM), and a top-level require here trips Node's CJS↔ESM
+// interop on a partially-initialized module.
+function rootPercyScreenshot(...args) {
+  return require('../index.js').percyScreenshot(...args);
+}
+
+// toHaveScreenshot options that only make sense for a LOCAL capture — the remote Automate
+// capture cannot apply them. `fullPage` is the one local capture option with a POA equivalent
+// and is mapped through instead.
+const LOCAL_ONLY_OPTS = Object.freeze([
+  'clip', 'mask', 'maskColor', 'omitBackground', 'scale', 'animations', 'caret', 'style', 'stylePath'
+]);
+
+// One-per-run notices — every assertion in a suite hits the same degradations, so warn once.
+let _localOptsWarned = false;
+let _locatorWarned = false;
+function _resetNotices() { _localOptsWarned = false; _locatorWarned = false; }
+
+// A Locator exposes `.page()`; a Page does not.
+function resolvePage(pageOrLocator) {
+  return pageOrLocator && typeof pageOrLocator.page === 'function'
+    ? pageOrLocator.page()
+    : pageOrLocator;
+}
+
+// Take a Percy-on-Automate screenshot for a Page or Locator subject by delegating to the SDK's
+// own `percyScreenshot`. Returns percyScreenshot's return value (the comparison detail when
+// `sync` is set, undefined otherwise or on a swallowed error; the sync classifier owns the
+// undefined case). Throws ONLY the configuration error below — percyScreenshot catches its own
+// runtime errors. `deps` is injectable for tests.
+async function screenshotViaAutomate(pageOrLocator, name, { sync } = {}, options = {}, deps = {}) {
+  const percyScreenshot = deps.percyScreenshot || rootPercyScreenshot;
+  const sessionDetails = deps.sessionDetails || (page => Utils.sessionDetails(page));
+  const page = resolvePage(pageOrLocator);
+
+  if (page !== pageOrLocator && !_locatorWarned) {
+    _locatorWarned = true;
+    log.warn('Percy: element screenshots are not supported on Automate projects — capturing the ' +
+      'full page for Locator subjects (the snapshot name is unchanged, so baselines stay stable)');
+  }
+
+  const ignored = LOCAL_ONLY_OPTS.filter(k => options && options[k] !== undefined);
+  if (ignored.length && !_localOptsWarned) {
+    _localOptsWarned = true;
+    log.warn(`Percy: ignoring toHaveScreenshot option(s) on an Automate project: ${ignored.join(', ')} — ` +
+      'the capture happens on the remote BrowserStack browser, not from local pixels');
+  }
+
+  // Session preflight. `getSessionDetails` only answers on a BrowserStack Automate browser — on a
+  // local browser the executor script evaluates to nothing and percyScreenshot would surface an
+  // opaque JSON-parse error. Detect that here and raise a CONFIGURATION error (same class as a
+  // wrong token: the user must fix their setup, so it is allowed to fail the assertion) with the
+  // actual fix in the message. Detection is per-assertion, not latched — hybrid suites that run
+  // some Playwright projects locally and some on BrowserStack keep working for the remote ones.
+  let session = null;
+  try {
+    session = await sessionDetails(page);
+  } catch { /* handled below — an unreachable/undecodable session is the same config error */ }
+  if (!session || !session.hashed_id) {
+    const err = new Error('Percy: the configured token is for a Percy on Automate project, but ' +
+      'this browser is not a BrowserStack Automate session — run the suite on BrowserStack ' +
+      '(e.g. via browserstack-node-sdk), or use a web/app project token for local runs.');
+    err.isConfigurationError = true;
+    throw err;
+  }
+
+  const poaOptions = {};
+  if (options && options.fullPage !== undefined) poaOptions.fullPage = options.fullPage;
+  if (sync) poaOptions.sync = true;
+
+  return percyScreenshot(page, name, poaOptions);
+}
+
+module.exports = { screenshotViaAutomate, resolvePage, LOCAL_ONLY_OPTS, _resetNotices };

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;