Legacy-to-modern migrations with AI

A Selenium-to-Playwright migration is not a single translation task. It is five distinct tasks that happen to be sequential: an inventory audit (what is in the suite and what condition is it in?), a syntactic conversion (Selenium API to Playwright API, file by file), a selector optimisation pass (XPath and CSS chains to role-based locators where the mapping is unambiguous), a page-object boundary definition (which interactions belong together?), and a stabilisation loop (first-run failures triaged and resolved). Each benefits from a different agent configuration focused on that specific stage.

The pipeline is not a product you can buy. It is assembled from Claude Code (claude.com/product/claude-code), Cursor (cursor.com), or another coding agent capable of multi-step agentic operation, driven by a prompt set that scopes each stage to its specific task. Teams that have attempted whole-migration-in-one-session approaches consistently report lower first-run pass rates than teams that decompose the migration into these five stages.

The audit agent inventories the suite before any migration begins. It identifies tests that are already failing or permanently skipped, tests with fragile XPath selectors that will not survive direct API translation, tests that share state in ways not explicit in the code, and external dependencies (databases, mail services, third-party APIs) that will need explicit handling in Playwright. The output is a structured report, not migrated code. Teams that skip the audit stage spend significant time in the stabilisation stage diagnosing problems they could have anticipated.

The conversion agent handles mechanical translation file by file: Selenium WebDriver API calls become Playwright API calls, TestNG or JUnit assertions become Playwright `expect()` assertions, explicit driver management disappears. For well-structured Selenium tests, conversion accuracy is high. For tests that relied on driver-specific timing behaviour or Selenium's implicit waits, the conversion produces syntactically valid code with incorrect async handling that only surfaces at runtime.

The selector optimisation agent passes over converted test files and replaces XPath and CSS-path selectors with role-based locators where the mapping is unambiguous. Where it is ambiguous — where the XPath targeted a DOM structure that Playwright would need a `data-testid` to target cleanly — the agent flags the selector for human review rather than guessing. Refer to playwright.dev/docs/pom for Playwright's page-object model guidance on selector strategy.

The page-object-model generator defines which interactions belong in which page object. This is the most failure-prone stage because domain boundaries in a legacy Selenium suite are often implicit — encoded in the original engineer's mental model, not in the file structure. The agent uses test names and interaction sequences to infer boundaries. Human review of the proposed structure before the agent generates code is the single highest-return review step in the entire pipeline.

The self-heal agent takes the first CI run — which will not be at 100% passing — and triages failures into genuine migration errors (wrong API mapping), selector failures (XPath without a clean role-based equivalent), and test-data setup failures (implicit Selenium state that needs explicit initialisation in Playwright). It proposes fixes for the first two categories; the third requires human domain knowledge about what state the application expects.

The comparison below is based on a 1,000-test Selenium suite migrating to Playwright in TypeScript. Figures are indicative; they scale with suite complexity and the proportion of tests using advanced Selenium features (actions API, shadow DOM, multi-window handling).

The key trade-off between AI-assisted and fully autonomous is not time or cost — it is risk profile. Fully autonomous migration produces PRs quickly. Those PRs are syntactically valid and pass automated type checks. A meaningful proportion contain semantic problems — wrong assertions, implicit state assumptions, timing issues — that only become visible when a real defect passes through without being caught. The review discipline that prevents this is not optional overhead; it is the load-bearing step that makes the approach viable.

First-run pass rate is rarely above 70% even on well-structured legacy suites. This is not a pipeline design failure — it is a property of the problem. Selenium tests that passed reliably often did so because of timing tolerances in the WebDriver protocol that do not translate to Playwright's event-driven model. The agent cannot know which timing assumptions were load-bearing until the tests run.

Hidden dependencies are the second category. Legacy Selenium suites often relied on driver-specific behaviour: implicit waits applied globally, browser state persisted between tests because the WebDriver session was shared, cookie handling that differed between the Selenium Java client and Playwright's TypeScript API. None of these appear in the test code. They appear in the failure log after migration.

Test data setup that was implicit in the Selenium suite is the third failure category. Many Selenium tests assumed a specific database state established by a preceding test in the suite run order. Playwright's parallel-execution default breaks this assumption silently — tests run in isolation, and the expected state is absent.

The honest gap: there is no single migration product that handles Selenium-to-Playwright end-to-end in 2026. Teams stitch together Claude Code, Cursor, custom prompt sets, and manual review. The five-agent architecture described here is a validated pattern, not a purchasable product. Engineering blogs published in Q1–Q2 2026 from teams that have completed migrations describe this stitched-together approach consistently.

A fully annotated diagram showing data flow between migration stages, failure modes at each handoff, and decision points where human review is required is planned for Phase 3 of this guide. The placeholder below marks the intended location.