Intro: A Cypress-to-Playwright migration effort is described, starting with manually translating a single spec to surface concrete decisions and creating a MIGRATION_RULES.md that maps commands, retries, and authentication/state handling to the new framework.

Supporting detail: After migration, the test suite runs in about 11 minutes using four workers, a significant improvement from prior runtimes, with the old commands.js replaced by roughly 180 typed fixtures, and plans to extend the workflow to Jest snapshots and smarter fixture design.

Trap and caution: Two critical issues emerged—an undocumented custom command caused silent bugs due to a misinterpreted conditional confirm dialog, highlighting the need for AI to report missing commands and caveats; and overly forgiving Playwright assertions produced boring green tests that tested nothing, requiring refined rules to preserve assertion intent.

Innovation step: A screenshot-diff gate was introduced to visually verify migrations against the Cypress baseline, catching drift that assertions alone might miss.

Process detail: Migrations are batched in groups of five specs per session to keep context fresh and limit failures, with a cycle of translation, three execution runs, and a pass/fail report before the next batch.

Key lessons: Start migrations by hand to surface decisions, prioritize failure reporting, batch migrations with fresh sessions, validate non-failing tests by deliberate breakage, and use visual diffs as a low-cost, comprehensive drift detector.

Timeline note: A developer describes migrating a 90-spec Cypress suite to Playwright in about four days using Claude Code, combining hand-translation with rule-based automation rather than a full naive conversion.

Rule that matters: Do not delete a Cypress spec until its Playwright counterpart passes 10 consecutive times, enabling safe, incremental migration.

Context: The original Cypress suite grew to about 90 specs over three years, with a 600-line custom commands file, flaky CI, and a 38-minute runtime, with migration aiming for real multi-tab support, parallelism, and a single cross-browser runner.

Step 2 detail: Convert migration rules into agent instructions (Claude Code) and embed them in the project so the AI can apply them across other specs while referencing a worked example.