PER-8985 feat: Percy drop-in example for Playwright toHaveScreenshot()

[Shivanshu-07]

What

Adds a working example of the Percy drop-in for Playwright's built-in toHaveScreenshot() assertions (shipping in @percy/playwright@1.1.2-beta.0 + @percy/cli@1.32.6-beta.1):

• playwright.dropin.config.js — the one required line (require('@percy/playwright/dropin')) plus an explicit browserName/viewport so first-run baseline seeding can map committed screenshots
• tests/dropin/todomvc_tohavescreenshot.spec.js — plain Playwright visual assertions against the repo's TodoMVC app, zero Percy imports (page subject + locator subject)
• npm run test-dropin script and a README section covering the run command, first-run baseline seeding (incl. the full-access-token recommendation), playwright:setup-baseline, and the beta install caveat (--legacy-peer-deps)

Version notes

• @playwright/test bumped 1.53.2 → 1.61.1 for the whole repo. Verified working end to end on 1.61.1 (build finalized, both snapshots posted). ⚠️ On 1.53.2 the drop-in's matcher injection does not engage (Percy: could not inject the toHaveScreenshot override into this Playwright version…) — flagged separately as an SDK compat follow-up; the README states 1.60–1.61 until that's resolved.
• @percy/cli/@percy/playwright floors set to the released betas (caret ranges roll forward to the GA versions).

Testing

PERCY_TOKEN=<web token> npm run test-dropin → capture=snapshot (web) mode line, Snapshot taken: todomvc-initial + todomvc-new-todo, build finalized (verified against production).

🤖 Generated with Claude Code

[aryanku-dev]

Nice example — the spec really does read as plain Playwright with zero Percy imports, which is exactly the point of the drop-in. A few things I'd want resolved before this merges, the first one being a blocker.

1. Beta floors at the repo root break npm install for everyone (blocker).

@percy/playwright@1.1.2-beta.0 declares peerDependencies: { "@percy/cli": ">=1.32.3" }, and the lockfile resolves @percy/cli@1.32.6-beta.2. Under semver, a prerelease does not satisfy a range with no prerelease component:

$ npx semver 1.32.6-beta.2 -r ">=1.32.3"   # -> no match, exit 1
$ npx semver 1.32.6       -r ">=1.32.3"   # -> 1.32.6, exit 0

That's precisely why the README has to tell people --legacy-peer-deps. But the repo's .npmrc pins legacy-peer-deps=false, and README Step 1 of the tutorial still says plain npm install — so a fresh clone should now ERESOLVE at the very first step of the getting-started flow.

Green CI isn't evidence against this: the basic job runs npm ci, which installs the already-resolved tree from the lockfile and never re-runs peer resolution. Could you confirm with rm -rf node_modules && npm install on a clean clone?

2. Related — should this be its own sub-example rather than a root-level bump?

The repo already has the precedent in advanced/: self-contained package.json + package-lock.json + playwright.config.js. Moving this to dropin/ would let the drop-in pin whatever betas it needs while the root example — the one the README calls "Minimum viable integration. Start here." — stays on GA @percy/cli/@percy/playwright and keeps a clean npm install. It also localizes the eventual beta→GA cleanup to one directory, and makes issue #1 disappear entirely. Was there a reason to bump the root instead?

3. Nothing in CI exercises this.

.github/workflows/test.yml's basic job runs npm test, and package.json has no test script — so that step is a no-op, and test-dropin is never invoked anywhere. The whole point of an example repo is that the examples are known-good; right now the drop-in path only has your manual local verification behind it. Worth adding a job (or a dropin job mirroring the advanced one) so a future SDK release can't silently break it.

4. The headline feature isn't actually demonstrated.

The README leads with first-run baseline seeding, but no *-snapshots directory is committed, so a reader who clones and runs npm run test-dropin hits the empty-baseline path, not the seeding path. Committing the generated baselines would make the flagship behaviour work out of the box — and would let CI assert it. Relatedly, please confirm what a zero-baseline first run does here: vanilla toHaveScreenshot() writes the actual and fails the test on first run, so the README's "Your suite passes as usual" needs to be true of the drop-in's interception path too.

Also, .gitignore only covers /node_modules — playwright test writes test-results/ and playwright-report/, so following the walkthrough leaves an untracked mess (and the suggested git add tests/dropin could sweep artifacts in).

Inline notes on the smaller stuff below.

[Shivanshu-07]

All review feedback addressed in 13f2faf, plus the Percy on Automate example added:

Review fixes

• Clean npm install works now (the blocker): exact beta pins per save-exact + an npm overrides entry satisfying the SDK's non-prerelease peer range — --legacy-peer-deps removed from the README entirely; verified from-scratch under this repo's strict .npmrc
• webServer in the drop-in config (tests/dropin/serve.js) — specs no longer bind ports
• Viewport comment rewritten with the real contract (identity from the resolved config; loud degrade when absent)
• README: section relocated before the Automate tutorial, indexed in the Examples table, npx fix, Node 18+
• First-run-on-clean-clone behavior confirmed live and documented (the drop-in suppresses the native missing-baseline failure)

New: drop-in on Percy on Automate

• playwright.dropin.automate.config.js + tests/dropin-automate/ — same one-line registration, browser fixture connects to a real BrowserStack Automate session, spec still has zero Percy imports; npm run test-dropin-automate + README subsection + Examples row

Verified against production on this head: web drop-in build #988 (2 snapshots via the webServer variant), automate drop-in build #63 (remote capture on a live BrowserStack session, capture=remote screenshot (automate)).

🤖 Generated with Claude Code

[Shivanshu-07]

Stable releases are live — this PR is now verified against them end to end, exactly as a customer would run it (1453a33):

• Fresh clone → plain npm i → @percy/cli@1.32.6 + @percy/playwright@1.1.2 from npm latest, no overrides, no flags (the beta-era overrides block is deleted)
• npm run test-dropin → build finalized, 2 snapshots (web)
• npm run test-dropin-automate → build finalized on a real BrowserStack session (remote capture)
• Lockfile regenerated against the stables

One scoping note added to the README: baseline discovery reads Playwright's default config, and this repo deliberately keeps the drop-in config under a custom filename to coexist with the other examples — so the auto-seed/setup-baseline walkthrough is framed for standard single-config projects (verified separately on a from-scratch project: --update-snapshots → playwright:setup-baseline uploaded and auto-approved, head run diffs against it).

🤖 Generated with Claude Code