/convert-cypress-playwright

Convert Cypress to Playwright

You are orchestrating a Cypress→Playwright migration. This command mirrors the phased structure of /il:generate-code but specializes every phase for the unique risks of a test-suite migration: silent data corruption on response parsing, strict-mode violations, BrowserContext isolation, parallelism collisions, and ~30 other documented gotchas. Follow these phases exactly.

Authoritative knowledge source: the cypress-to-playwright skill plus the QA-maintained Confluence rulebook it points to (weldnorthed.atlassian.net page 134491275317). Invoke the skill and fetch the Confluence page before any conversion work — the page contains the full mapping tables, gotchas catalog, and pre-conversion audit checklist. The orchestrator's job is to apply them phase-by-phase and coordinate agents.

---

Phase 1: Parse Arguments & Gather Context

1.1 Parse Arguments

Parse $ARGUMENTS for:

Required positional arguments:

• First: Cypress repo path — absolute or relative path to the existing Cypress codebase
• Second: Playwright target path — absolute or relative path to the target repo. If the directory is empty or doesn't exist, we scaffold fresh. If it contains an existing partial Playwright setup, we augment it.

Optional flags:

• --jira <TICKET-KEY> — link the migration to a Jira ticket for commentary (e.g., --jira QE-456). Without this, no Jira comments are posted.
• --phase scaffold|bulk|audit|validate|all — run only a specific phase. Default: all. Use for resuming partial migrations.
• --scope <domain,domain> — restrict conversion to specific domain folders (e.g., --scope api,auth). Default: all domains.
• --skip-baseline — skip Phase 1.6 Cypress baseline capture. Default is to require a baseline captured the same day as runtime validation.
• --skip-audits — skip Phase 5 quality audits (TypeScript, migration audit, gotchas verification). Default: run them.
• --quiet-jira — suppress all automatic Jira commentary. Only used when --jira is set.

If either required argument is missing, use AskUserQuestion to collect it. Explain what each path should contain.

1.2 Invoke the Skill & Fetch the Rulebook

Use the Skill tool to invoke cypress-to-playwright before any analysis. Then fetch the QA-maintained Confluence rulebook — this is the single source of truth for mappings, gotchas, and the pre-conversion audit checklist:

mcp__plugin_il_atlassian__getConfluencePage({
  cloudId: "weldnorthed.atlassian.net",
  pageId: "134491275317",
  contentFormat: "markdown"
})

Store the page content as rulebook for reuse in subagent prompts. Every subsequent phase references gotchas by their numbered section from that page (e.g., "gotcha §9"). Do not paraphrase the rulebook into agent prompts — pass the fetched content verbatim so agents work from the authoritative source.

1.3 Verify Cypress Repo Exists & Detect Layout

Use Bash (ls <cypress-repo-path>) to confirm the Cypress repo path exists. Detect:

• Test directory (cypress/e2e/, cypress/integration/, or custom)
• Support directory (cypress/support/, cypress/services/, cypress/pages/, etc.)
• cypress.config.ts / cypress.config.js
• package.json — capture current Cypress version, Node version, TypeScript version

1.4 Verify Playwright Target & Detect Existing State

Check the Playwright target:

• Empty or nonexistent — Phase 2 will scaffold
• Contains playwright.config.ts — read it to understand current state; Phase 2 will verify or augment
• Contains partial tests/ — treat as in-progress migration; Phase 2 detects what's already converted

1.5 Resolve Jira Cloud ID (if --jira provided)

If --jira <ticket> was provided AND --quiet-jira was NOT:

1. Use mcp__plugin_il_atlassian__getJiraIssue to fetch the ticket.
2. Use mcp__plugin_il_atlassian__getAccessibleAtlassianResources to resolve the Atlassian Cloud ID (UUID, not hostname). Store as resolved cloud ID — use this in every comment call.

1.6 Baseline Requirement Gate

Unless --skip-baseline was provided, require a fresh Cypress baseline before Phase F runtime validation. Use AskUserQuestion to ask:

The Cypress→Playwright migration requires a Cypress baseline captured the same day you run Playwright validation, to avoid credential/data drift masking as migration bugs (see gotcha §4). Have you already captured a fresh Cypress baseline today? If not, we'll pause before Phase 6 to let you run it.

Record the answer. If NO, set a flag to pause before runtime validation.

1.7 Present Context Summary

Context Summary
───────────────
Cypress repo:     <path>  (<spec count> specs, <test count> it() blocks, <domain count> domains)
Playwright target: <path>  (<fresh|partial|in-progress>)
Jira ticket:      <key or "none">
Scope:            <all domains | filtered list>
Phase:            <all | specific phase>
Baseline:         <captured today | needed before Phase 6 | skipped>

Ask the user to confirm before proceeding.

---

Phase 2: Pre-Conversion Audit (Delegated to Subagent)

Delegate the Cypress codebase audit to a subagent to keep the orchestrator's context clean. This agent scans the Cypress repo for every gotcha pattern and produces a quantified findings table.

2.1 Spawn Cypress Audit Agent

Use Agent with:

• subagent_type: "Explore"
• name: "cypress-auditor"
• description: "Audit Cypress repo for migration gotchas"

The prompt must include:

You are auditing a Cypress test repository before a Playwright migration. Your job is to produce a quantified findings table that drives migration planning.

## Repo path
<cypress repo path>

## Required Reading
Before starting, invoke the `cypress-to-playwright` skill via the `Skill` tool. The authoritative audit checklist lives in Confluence — the orchestrator has already fetched it and is providing it below as **rulebook**. Use the "Pre-Conversion Audit" / "Gotchas Checklist" sections of that rulebook for the exact grep commands and output template.

<rulebook>
<paste full Confluence page content here>
</rulebook>

## Your Task

1. Run every inventory command in the rulebook's audit section (suite inventory, per-gotcha counts, credential audit, shared-mutable-state audit).
2. For each gotcha category with a non-zero count, record:
   - Count (total matches and unique files)
   - Up to 5 example file paths
   - Planned Playwright approach (1 sentence, referencing the gotcha number from the rulebook)
3. Produce the credential findings table (credential → file count).
4. Produce the parallelism recommendation paragraph.
5. List every Cypress test currently using Applitools, cy.task, cy.origin, cy.getIframeBody, or `cy.session` — these categories typically become skip list entries.

## Required Output (Markdown)

Return a single markdown document with these sections. Do NOT write it to a file:
- **Suite Inventory** — test counts, file counts, domain list, currently-skipped count
- **Gotcha Findings Table** — one row per applicable gotcha from the rulebook
- **Credential Audit** — per-credential file count sorted descending
- **Shared Mutable State** — mutating helpers and the specs that call them
- **Parallelism Recommendation** — one paragraph with a concrete `workers` / account-provisioning recommendation
- **Skip List Candidates** — tests that should be temporarily skipped during conversion, grouped by blocker

Return the full markdown document as your text response. No additional commentary. No files created.

2.2 Receive & Present the Audit

Store the audit document. Present the summary (inventory counts + top 3 gotcha findings + parallelism recommendation) to the user. Ask for confirmation before proceeding.

2.3 Jira Commentary — Pre-Conversion Audit

If --jira was set and --quiet-jira was NOT, decide whether the audit surfaced anything worth a Jira comment. Things worth commenting on:

• Parallelism blockers that inform scope: "72 of 150 files share credentials — parallelism is deferred until ~72 accounts are provisioned"
• Unexpected pre-existing bugs found during the audit: "Found 5 malformed selectors in Cypress source that jQuery tolerated — fixing during conversion"
• Applitools/external-SDK scope: "36 visual tests will be ported but skipped until @applitools/eyes-playwright is integrated in a follow-up"

Use mcp__plugin_il_atlassian__addCommentToJiraIssue with the resolved cloud ID, contentFormat: "markdown", and the ticket key.

---

Phase 3: Plan (Enter Plan Mode)

Use EnterPlanMode. The plan must cover the specific axes a test-suite migration needs:

Plan Structure

1. Scaffold (if target is fresh)

   • playwright.config.ts — testDir, workers, fullyParallel, timeout, use.baseURL, reporter
   • tsconfig.json — path aliases (@pages/*, @services/*, @fixtures/*, etc.) — see the rulebook's scaffolding section
   • Folder structure — src/{aws,fixtures,mocks,pages,services,support,types,util}/ + tests/<domain>/
   • Env files — .env.dev, .env.staging, etc.

2. Infrastructure Port

   • BaseService, BasePage
   • Auth helpers (must use page.context().request for login — gotcha §14)
   • Tag constants and filtering
   • AWS SDK wrappers (direct imports, no cy.task registration — see mappings)
   • Mock/fixture loading helpers

3. Bulk Conversion Scope

   • Domain order — API-only first, student/largest last
   • Per-domain file counts and gotcha hot-spots (pulled from Phase 2 audit)
   • Expected conversions applied — enumerate the 5 highest-impact gotchas for this suite

4. Skip List

   • Every test that can't be ported this pass, grouped by blocker (Applitools, missing helper, missing fixture, etc.)
   • Format: each entry maps a blocker category to spec files and unblock work
   • Will become playwright-skipped-tests-report.md

5. TypeScript Gate Strategy

   • Target: npx tsc --noEmit produces 0 errors after bulk conversion
   • Plan for surfacing type mismatches — usually import path issues, missing method signatures on ported helpers

6. Timeout & Parallelism Config

   • Global timeout starting value (45-60s)
   • Per-suite test.describe.configure({ timeout }) for heavy-setup suites (identify candidates from Phase 2 — any suite with >20s of hard waits or heavy API setup)
   • workers and fullyParallel decisions per the Phase 2 recommendation

7. Runtime Validation Phases

   • API-only suite first
   • Single UI login
   • @smoke tag
   • Full regression, per-domain, student last
   • Comparison script: re-run Cypress equivalent for each Playwright failure

8. Success Criteria

   • npx tsc --noEmit = 0 errors
   • Migration audit: every Cypress it() has a Playwright test() or explicit test.skip(); DIFF per file = 0 or positive
   • API-only suite ≥85% pass on first runtime
   • All runtime failures mapped to either a migration bug (fix) or a Cypress baseline match (environment/data)

Plan Guardrails

• Do not mix migration with cleanup. Cypress suite flakiness, cy.wait elimination, and selector modernization are deferred — see the skill's "Cleanup is scope B" guardrail and the rulebook's §15.
• Do not mirror Cypress folder structure. src/ + tests/ split is non-negotiable (gotcha §8).
• Do not enable parallelism if Phase 2 recommends against it. workers: 1 is correct until credentials/data are isolated.

The user must explicitly approve the plan before proceeding. Use ExitPlanMode when ready for review.

Jira Commentary — Plan Decisions

If --jira was set and --quiet-jira was NOT, comment on the ticket after the user approves. Worth commenting on:

• Deferred cleanup — "Hard waits ported as-is; proper wait conditions deferred to follow-up per migration gotcha §15"
• Skip list scope — brief count by category, link to report once generated
• Parallelism deferral — concrete follow-up ask ("~72 educator accounts to provision before parallelism pays off")

---

Phase 4: Bulk Conversion (Team Orchestration)

4.1 Create the Team

Use TeamCreate to create a team named cypress-playwright-conversion-<target repo> (basename of the Playwright target path) — scoping to the target repo avoids collisions between concurrent sessions. Reuse this exact name for all team_name references below and the final TeamDelete. If the team already exists, do NOT silently reuse it — pause and ask the user.

4.2 Create the Conversion Task

Use TaskCreate to create: "Bulk-convert Cypress suite to Playwright per approved plan"

4.3 Spawn the Converter Agent

Reuse the code-generator agent — it already knows how to follow a plan, respects existing codebase patterns, and honors anti-hallucination guardrails. Spawn with:

Use Agent tool with:
  subagent_type: "code-generator"
  team_name: "cypress-playwright-conversion-<target repo>"
  name: "converter"

The agent's prompt MUST include all of the following (paste full content inline):

• Skill instruction: "Before writing any code, use the Skill tool to invoke the cypress-to-playwright skill. The authoritative rulebook (mappings table + gotchas catalog) is the QA-maintained Confluence page 134491275317 on weldnorthed.atlassian.net — the orchestrator has fetched it and is providing the full content below as rulebook. Every conversion must apply the relevant rules — reference gotchas by number in commit messages and comments when non-obvious. <paste full Confluence page content here>"
• Cypress audit findings — paste the full Phase 2 audit document inline
• Approved conversion plan — paste the Phase 3 plan verbatim
• Source and target paths — absolute paths, plus which files are in-scope per the --scope filter
• TypeScript gate instruction: "After bulk conversion, run npx tsc --noEmit from the Playwright target root. The output target is zero errors. Iterate until that gate passes. Do NOT proceed to skip-list documentation until tsc is clean."
• Skip list instruction: "For every Cypress test that cannot be ported this pass, emit a test.skip(...) in Playwright with the same title, and append an entry to playwright-skipped-tests-report.md grouped by blocker category per the skip-report template in the rulebook."
• Migration audit instruction: "After skip-list is complete, produce playwright-migration-audit.md — a per-file table of Cypress it() count vs Playwright test() count (including skips). DIFF column must be 0 or positive for every file."
• Cleanup-deferral instruction: "Port cy.wait(<ms>) as page.waitForTimeout(<ms>) as-is. Do NOT modernize waits, do NOT fix selector quality issues unless they are the pre-existing malformed selectors from gotcha §22. Migration is scope A; cleanup is scope B."
• Anti-hallucination instruction: "Do not invent Playwright APIs. If unsure whether a method exists on Page, Locator, BrowserContext, or APIRequestContext, verify against node_modules/@playwright/test/index.d.ts or leave a TODO with a specific question."
• Jira commenting instruction (include ONLY if --jira set and --quiet-jira NOT set):

You have access to mcp__plugin_il_atlassian__addCommentToJiraIssue to comment on <ticket key>. Use cloudId: "<resolved cloud ID>", contentFormat: "markdown", issueIdOrKey: "<ticket key>".

Comment when you encounter something worth documenting for humans reviewing this migration:
- **Surprising patterns**: "Found 12 specs with bare `//` XPath — all converted to CSS"
- **Non-mechanical decisions**: "Spec X uses cy.session with external identity provider — converted to storageState instead of inline login for Playwright"
- **Deferred TODOs**: "Left 3 TODOs for contenteditable editors that need `pressSequentially` helper — not in this scope"
- **Discoveries**: pre-existing Cypress bugs found during conversion

Do NOT post mechanical status or restate the plan. One comment per non-obvious discovery is the right cadence.

• Output delivery instruction: "When done, send your completion report to the team lead via SendMessage with to: 'team-lead', a short summary (5-10 words), and the full report as message. Include: files created/modified count, tsc --noEmit final exit status, migration audit summary (files with DIFF ≠ 0), skip list summary (counts per blocker category), and any TODO or deviation notes. Mark your task as completed via TaskUpdate."

4.4 Wait for Completion

Agent messages are delivered automatically. Do NOT poll. Wait for the converter's completion message.

4.5 Capture Conversion Delta

Run git status and git diff --stat in the Playwright target. Record:

• Planned files created — from Phase 3 plan
• Actually created — from git status
• Deviations — files created that weren't planned, or planned files missing (with the converter's justification)

This delta goes to the reviewer in Phase 6 as factual context.

---

Phase 5: Quality Audits (Parallel Dispatch)

Skip if --skip-audits was specified. Otherwise run three audits in parallel.

5.1 Collect Changes

Run git diff and git status from the Playwright target. Compile the changed-file list.

5.2 Dispatch Audits (Parallel)

Dispatch three audits in parallel (multiple Agent calls in one response):

Audit A: TypeScript Gate

• subagent_type: "Explore", name: "ts-gate"
• Prompt: "Run npx tsc --noEmit from <playwright target path>. Return the full output. Categorize every error: (1) missing import / wrong path, (2) missing method signature on ported helper, (3) any leakage, (4) actual type mismatch. Return a single JSON object: { exitCode, errorCount, byCategory: { ... }, topFiles: [...] }."

Audit B: Migration Audit (Test Count Parity)

• subagent_type: "Explore", name: "migration-audit"
• Prompt: "Compare Cypress it() count to Playwright test() count per file. Read <cypress repo>/cypress/e2e/ and <playwright target>/tests/ recursively. For each pair of corresponding files, count: Cypress it(, Playwright test( (including test.skip(). Produce a table with columns: file, cypress_count, playwright_count, diff. DIFF must be 0 or positive (positive = previously-hidden gated tests now made explicit via test.skip). Return JSON: { totalCypress, totalPlaywright, filesWithNegativeDiff: [...], summary }."

Audit C: Gotchas Verification

• subagent_type: "Explore", name: "gotchas-audit"
• Prompt: "Audit the Playwright target at <path> for residual migration gotchas. Use the cypress-to-playwright skill and the QA-maintained Confluence rulebook (page 134491275317 on weldnorthed.atlassian.net) — the orchestrator has fetched it and is providing the full content below as rulebook. Use the bulk-detection one-liners from the rulebook's gotchas section. Run each detection command against the Playwright target (not the Cypress source). For every match, classify as: (a) legitimate (e.g., response.json() against a JSON endpoint) or (b) potential gotcha (e.g., response.json() against an endpoint the audit says returns raw text). Return JSON: { perGotcha: { '§1': { matches, potentialIssues }, '§2': {...}, ... }, topConcerns: [...] }. <paste full Confluence page content here>"

5.3 Handle Audit Results

For each audit:

• Success — store the JSON result
• Failure — record as SKIPPED with the error

5.4 Compute Migration Quality Gate

The gate is simpler than the generic code-quality gate:

1. TypeScript gate — ts-gate.exitCode == 0 is mandatory. Non-zero is a hard block.
2. Migration audit — filesWithNegativeDiff.length == 0 is mandatory. Negative diff means tests were dropped.
3. Gotchas audit — produce a priority list. Flag CRITICAL if there are >0 potential issues in §1 (silent data corruption), §3 (beforeAll request), §4 (cookie strings), §9 (waitForResponse navigation), §14 (cy.request login).

5.5 Present Audit Results

## Migration Quality Audit

**TypeScript Gate:** <PASS | FAIL (<N> errors)>
**Migration Audit:** <PASS | FAIL (<N> files with lost tests)>
**Gotchas Verification:** <clean | <N> potential issues across <M> gotcha categories>

### Critical Concerns
<enumerate CRITICAL-tier gotchas with file:line references>

### Full Report
<TypeScript error summary, per-category counts>
<Migration audit table (files with diff ≠ 0)>
<Gotchas audit — per-category match counts with (legitimate / potential) split>

If TS gate or migration audit fails, use AskUserQuestion:

• Re-run converter with specific fixes — feed the audit findings back to a new converter invocation
• Fix manually and re-audit — user addresses and we re-run Phase 5
• Proceed to review anyway — only if the user explicitly overrides
• Abort

If audits pass, proceed to Phase 6.

---

Phase 6: Independent Review (Fresh Context)

6.1 Baseline Reminder

If Phase 1.6 flagged that no baseline was captured today, pause here. Ask the user:

Runtime validation requires a fresh Cypress baseline captured today. The reviewer will compare migration findings to this baseline to distinguish migration bugs from environment/data issues. Capture it now (from the Cypress repo) and confirm the pass/fail summary before we proceed.

Wait for confirmation and a baseline summary (pass count, fail count, date). Store for the reviewer.

6.2 Create Review Task

Use TaskCreate to create: "Independent migration review"

6.3 Spawn Reviewer

Use Agent tool with:
  subagent_type: "code-reviewer"
  team_name: "cypress-playwright-conversion-<target repo>"
  name: "reviewer"

Review Isolation: The reviewer's prompt must NOT include the converter's rationale or the approved plan. Pass only:

• Skill instruction: "Before reviewing, invoke the cypress-to-playwright skill. The ground-truth checklist is the QA-maintained Confluence rulebook (page 134491275317 on weldnorthed.atlassian.net) — the orchestrator has fetched it and is providing the full content below as rulebook. Evaluate every gotcha category from that page against the diff. <paste full Confluence page content here>"
• Cypress audit findings — Phase 2 output
• Git diff of the Playwright target — complete diff output
• Changed file list + file access strategy — standard Read tool instructions
• Conversion delta — factual Phase 3 plan vs Phase 4 delivery comparison. Preface: "This is factual; it does not include the converter's reasoning. Use it to detect gaps."
• Migration audit report — Phase 5 test-count parity output
• Gotchas audit report — Phase 5 gotchas verification output
• Cypress baseline summary — pass/fail counts and date captured
• Review isolation statement: "You are an independent reviewer of a Cypress→Playwright migration. You have NOT seen the converter's approach or reasoning. Evaluate the code purely against the gotchas catalog, the mapping correctness, and the audit findings. Form your own judgment on whether the migration is production-ready or requires rework. Focus areas: (a) correctness of mechanical conversions; (b) gotcha application (silent-data-corruption risks, strict-mode violations, waitForResponse-on-navigation, request-fixture misuse for login); (c) skip list completeness; (d) migration audit test-count parity; (e) runtime-readiness given the Cypress baseline."
• Review scope: "Do NOT critique cleanup items deferred per the migration plan (hard waits, selector modernization, Applitools integration). These are explicitly scope B. Flag only if a deferred item actually broke the migration."
• Jira commenting instruction (if applicable, same template as generate-code)
• Output delivery instruction: "Send your full review to the team lead via SendMessage with to: 'team-lead', a short summary, and the full review as message. Include verdict (APPROVE / REQUEST CHANGES / REJECT), findings by gotcha category with file:line references, confirmed vs disputed audit findings, and a runtime-readiness assessment. Mark your task as completed via TaskUpdate."

6.4 Wait for Review

Messages are delivered automatically.

---

Phase 7: Present Results & Handle Verdict

7.1 Parse Review

Extract verdict, findings, and runtime-readiness assessment.

7.2 Handle by Verdict

APPROVE

1. Present a combined migration summary: scaffolding status, TypeScript gate, migration audit, gotcha verification, review verdict, runtime-readiness.
2. Print the next-steps runbook:

Next Steps — Phased Runtime Validation

1. API-only first:
   npx playwright test --grep @api
   Expected: ≥85% pass, all failures match the Cypress baseline from <date>.

2. Single UI login:
   npx playwright test tests/auth/login.spec.ts
   Expected: pass. Validates cookie/storageState wiring (gotcha §4, §14).

3. Smoke tag:
   npx playwright test --grep @smoke

4. Full regression, per-domain, student last. For every failure:
   a. Re-run the equivalent Cypress spec SAME DAY to separate migration bugs from env/data.
   b. Cluster real failures into categories using the Confluence rulebook.
   c. Fix by category in bulk, not one test at a time.

5. Cleanup passes (separate PRs, not this one):
   - Hard waits → proper conditions (gotcha §15)
   - Parallelism: provision accounts, then raise `workers` (gotcha §7)
   - Applitools / visual — separate PR

3. Clean up the team using TeamDelete.
4. Optional: offer to generate a Jira summary comment consolidating the migration outcome.

REQUEST CHANGES

1. Present the review with findings clustered by gotcha category.
2. Triage:
   • Pivot indicators — folder structure wrong (gotcha §8), parallelism enabled against advice (§7), login flow uses wrong request fixture across many specs (§14). These suggest re-running Phase 3 with a revised plan.
   • Refinement candidates — specific files with specific gotchas to fix in place.
3. Offer options via AskUserQuestion:
   • Re-spawn converter with targeted fixes — pass the findings as input for a new Phase 4 invocation
   • Revise the plan — go back to Phase 3
   • Fix manually and re-audit — user fixes, we re-run Phase 5
   • Accept as-is — user overrides
4. Clean up team when satisfied.

REJECT

1. Present the fundamental problems (usually: folder structure wrong, parallelism safety violated, significant test coverage lost in migration audit, or pervasive gotcha misses).
2. Offer via AskUserQuestion:
   • Revise plan — Phase 3 with reviewer concerns
   • Reduce scope — migrate a smaller initial slice (e.g., API-only first)
   • Abandon — keep Cypress, re-attempt later
3. Clean up team.

7.3 Jira Commentary — Final

If --jira was set and --quiet-jira was NOT, post a final summary comment with: verdict, TypeScript gate status, migration audit test-count delta, top gotcha findings, and runtime-readiness assessment. Do NOT dump full reports — link the resolved cloud ID to where they live.