How to Modernize a Legacy Selenium Test Suite Without Starting Again

Nobody wants to migrate a passing test suite. The tests work. They're slow, they're flaky on a bad day, the codebase around them is a decade of copy-pasted WebDriverWait calls, but they work, and "works" is a hard thing to walk away from. The real problem isn't technical, it's organizational: a full rewrite competes for the same sprint capacity as feature work, it has no visible payoff until it's completely done, and if it stalls halfway you're now maintaining two suites in two frameworks with less confidence in either than you had when you started.

In a regulated environment (finance, healthcare, anything under EU AI Act or SOC 2 audit scope) there's a second, sharper version of the same problem: you can't just switch frameworks and hope the new suite covers what the old one did. If an auditor asks "show me continuous test coverage for this control across the migration window," a half-migrated suite with silent gaps is a finding, not a footnote.

Selenium suites accumulate technical debt in a specific, predictable way. Early tests are written with direct WebDriver calls. Later tests wrap those calls in page objects, but the page objects wrap the same slow, explicit-wait patterns underneath. By year three, the suite has hundreds of tests that all share the same brittle waiting and locator logic, so any migration approach that touches tests one at a time inherits that fragility everywhere it goes.

Meanwhile, "migrate everything at once" fails for a more human reason: it asks a team to hold two mental models (Selenium's WebDriver API and Playwright's auto-waiting, context-based API) at the same time, across hundreds of tests, with no working checkpoint until the very end. Most rewrite attempts stall not because Playwright is hard to learn, (Opinion), but because the project has no safe stopping point that still leaves you with a suite you trust.

• The parallel rewrite freeze. Pausing feature-test additions in Selenium while a small team rewrites everything in Playwright. This works in theory and rarely finishes in practice, because feature work doesn't pause for the rewrite, so the Selenium suite keeps growing while the Playwright rewrite tries to catch up.
• Alphabetical or file-order migration. Migrating test files in whatever order they appear in the repo. This produces a plausible-looking burndown chart but no risk reduction: you might spend the first month migrating low-value smoke checks while your highest-risk checkout or compliance-control tests stay on the old, slower suite the entire time.
• A big-bang cutover with no parallel-run window. Retiring the Selenium suite the day the Playwright suite reaches feature parity on paper. Without a period where both suites run against the same builds and their results are compared, "feature parity" is an assumption, not a verified fact, and in a regulated context that assumption is exactly what an audit will probe.
• Automated one-shot conversion tools. Several exist that mechanically translate Selenium calls to Playwright syntax. They handle the API surface (driver.findElement to page.locator) but not the underlying design problems: brittle CSS selectors, explicit sleeps instead of auto-waiting, and page objects built around Selenium's synchronous model. You end up with Playwright syntax and Selenium-era flakiness, (Industry consensus).

Two decisions do most of the work: migrate by risk tier, not by file order or convenience, and run both suites in parallel during a defined transition window rather than cutting over on faith.

Risk-tier migration order. Before writing a single Playwright test, classify the existing Selenium suite into tiers based on what a missed regression would cost, not how easy the test is to convert:

• Tier 1: tests covering regulated controls, payment flows, auth, and anything an incident report or audit has previously flagged. Migrate first, even though these are often the hardest tests to convert.
• Tier 2: tests covering core functional flows that matter to users but carry lower compliance or financial exposure.
• Tier 3: tests covering edge cases, low-traffic paths, or functionality already flagged as candidates for deletion regardless of framework.

This inverts the instinct to start with the easy wins. It's slower to show early progress, (Opinion), but it means that if the migration project loses momentum or gets deprioritized (a real risk, per the section above), the highest-risk coverage has already moved, not the lowest-risk coverage.

Parallel-run validation before cutover. For each tier, once its Playwright equivalents exist, run both the Selenium and Playwright versions against the same build for a fixed window (commonly 2 to 4 sprints, (Opinion), longer for regulated controls) before retiring the Selenium version. Track three things during that window:

• Do both suites agree on pass/fail for every run, and if not, which one is right?
• Does the Playwright suite catch every regression the Selenium suite catches, with no coverage regression?
• Is there a documented, timestamped record of both suites' results for the window, so "coverage was continuous during migration" is a verifiable artifact, not a claim?

Only after a tier clears that window does its Selenium version get deleted, not just skipped in CI.

A Selenium-to-Playwright locator and action comparison

The mechanical translation matters less than the design shift it enables, but seeing them side by side is where most teams start:

// Selenium (Java), explicit wait then click
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement checkoutButton = wait.until(
 ExpectedConditions.elementToBeClickable(By.xpath("//button[@data-action='checkout']"))
);
checkoutButton.click();

// Playwright (TypeScript), auto-waiting built into the locator/action
await page.locator("//button[@data-action='checkout']").click();

The Playwright version isn't just shorter. page.locator(...).click() auto-waits for the element to be attached, visible, stable, and receiving events before it acts, which is what most of those hand-written WebDriverWait blocks in a legacy Selenium suite exist to approximate manually (Verified, Playwright documentation). This is also the point in a migration where it's worth revisiting locator choice itself, not just syntax: a legacy suite's XPath and CSS selectors carried over verbatim will still be as brittle as they were in Selenium. The companion article on locator strategy (linked below) covers how to choose resilient locators for the rewritten tests rather than porting fragile ones forward.

Running both suites in the same CI pipeline during the transition window

name: migration-parallel-run
on:
 pull_request:
 push:
 branches: [main]
jobs:
 selenium-tier1:
 if: contains(github.event.pull_request.labels.*.name, 'tier1-migrating') || github.event_name == 'push'
 runs-on: ubuntu-latest
 steps:
      - uses: actions/checkout@v4
      - run: mvn test -Dgroups=tier1
 playwright-tier1:
 runs-on: ubuntu-latest
 steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright test --grep @tier1
 compare-results:
 needs: [selenium-tier1, playwright-tier1]
 runs-on: ubuntu-latest
 steps:
      - run: echo "Archive both result sets with a shared build ID for audit comparison"

The compare-results step is intentionally minimal here: the point is that both result sets get archived against the same build identifier, so a later audit or a later engineer can reconstruct exactly what each suite reported for any given release during the transition window, not just today's CI summary.

Audit trail continuity during migration

For regulated-industry teams, the artifact that matters isn't "we migrated," it's "coverage was continuous and provable throughout." Three concrete practices support that:

• Tag each test with its control or requirement ID in both frameworks, not just a tier label, so a compliance mapping (test to control) survives the framework change instead of needing to be rebuilt from scratch afterward.
• Archive parallel-run results with retention matching your audit window, not your CI's default log retention, which is often 90 days or less and won't cover a migration that spans a full audit cycle.
• Keep a written migration log per tier: date range of the parallel run, discrepancies found and how they were resolved, and the date Selenium coverage for that tier was formally retired. This is the document that answers an auditor's question directly instead of requiring them to reconstruct history from CI logs.

An AI coding agent is genuinely useful for the mechanical parts of this migration: converting Selenium locator and action syntax to Playwright's API, drafting the first-pass Playwright equivalent of a page object, and flagging Selenium calls (explicit sleeps, Thread.sleep, brittle absolute XPath) that shouldn't be carried forward unchanged. It is not well suited to deciding tier classification, since that requires business and compliance risk judgment the agent has no visibility into, and it should not be trusted to sign off that a converted test is behaviorally equivalent to its Selenium original without a human reviewing the parallel-run comparison data described above. Treat AI-assisted conversion as a first draft that still goes through the same parallel-run validation as a hand-written migration, not a shortcut around it.

If you're migrating specifically because you want your test suite to be something an AI coding agent can extend going forward, not just something a human maintains, it's worth looking at how a Playwright suite built for that from the start is structured. CrevoAI, published under OpenEvident, is a local-first Playwright test automation toolkit built for AI coding agents (Cursor, Claude Code, GitHub Copilot), with MCP tools for codegen, browser control, and recordings, running entirely as a local stack with no cloud job runner. For a team migrating off Selenium partly to make the suite more AI-agent-friendly, that architecture (everything on 127.0.0.1, no remote orchestration) is directly relevant to how you might structure the rewritten suite, not just what framework it runs on. [VERIFY API BEFORE PUBLICATION]: confirm current install and adoption steps against the CrevoAI repository before referencing a specific setup flow.

A phased, risk-tiered migration with a parallel-run validation window is the right approach, but it's genuinely more work up front than a big-bang rewrite, and it has to happen while the team keeps shipping features. That combination (migrate a legacy suite by risk tier, prove continuity for regulated controls, and don't stop delivery to do it) is exactly the kind of implementation-ready roadmap work OpenCrevo's Consult & Transform service is built around: embedding as a digital transformation partner to deliver a grounded, open-source-tooling-based migration plan rather than a slide deck. If your organization needs this planned and executed alongside a normal release calendar, not during a dedicated freeze, OpenCrevo can help design and run the migration. Not sure where your gaps are? Start with the free QA maturity assessment for a scored baseline before scoping the engagement.

• Classify the existing Selenium suite into risk tiers based on regulatory, financial, and incident-history exposure, not file order or conversion difficulty.
• Migrate Tier 1 (highest risk) first, even though it's usually the hardest and slowest tier to convert.
• Run Selenium and Playwright versions of each tier in parallel against the same builds for a fixed window before retiring the Selenium version.
• Tag tests with their control or requirement ID in both frameworks so compliance mapping survives the migration.
• Archive parallel-run results with retention matching your audit cycle, not your CI tool's default log retention.
• Keep a written per-tier migration log: parallel-run dates, discrepancies found, and formal Selenium retirement date.
• Re-evaluate locator strategy during the rewrite instead of porting brittle Selenium selectors into Playwright syntax unchanged.
• Treat AI-assisted conversion as a first draft still subject to full parallel-run validation, not a substitute for it.

• How long does a Selenium to Playwright migration take for a mid-size suite? It depends heavily on suite size and how many tiers carry regulated controls, but a phased approach (tier by tier, with parallel-run windows) commonly runs several months for a few hundred tests, (Opinion), not weeks. Rushing the parallel-run window to hit a shorter timeline is where most of the real risk gets reintroduced.
• Do we have to migrate everything, or can some tests just be deleted? Migration is also a legitimate moment to prune. If a Tier 3 test hasn't independently caught a real regression in the review period, it's a candidate for deletion rather than conversion, the same logic used in regression-suite pruning generally.
• Does this replace the need for a locator strategy decision? No. Migrating framework without revisiting locator choice just moves the same brittleness into new syntax. See "Stop Using Fragile CSS Selectors" for the locator-resilience side of this work.
• What's the minimum parallel-run window for a regulated control? There's no universal number; it should match your audit cycle and control criticality rather than a fixed convention, (Requires verification) against your specific compliance framework and auditor expectations.
• Can AI agents do most of the conversion work? They can accelerate the syntax-level conversion and first-draft page objects, but the tier classification and the sign-off that a converted test is behaviorally equivalent to its original need to stay human decisions, validated against parallel-run data.

A legacy Selenium suite doesn't need a rewrite from zero, it needs a migration order driven by risk instead of convenience, and a validation window that proves the new suite catches what the old one caught before you delete anything. For regulated teams, that validation window doubles as the audit artifact that answers "was coverage continuous during migration" without anyone having to reconstruct the answer after the fact. Skipping either the risk-tier ordering or the parallel-run proof is how migrations stall, or how they finish technically but leave an audit gap nobody notices until it's asked about.

For the next step in tightening the rewritten suite itself, see "Stop Using Fragile CSS Selectors: A Practical Locator Strategy," and for teams pairing this migration with a broader shift toward AI-assisted quality engineering, "From Manual Regression to AI-Assisted Quality Engineering: A Practical Migration Plan" covers the org-level rollout beyond the framework change itself.

Sources: Playwright documentation on auto-waiting and locators, Selenium WebDriver documentation on explicit waits, OpenEvident's CrevoAI repository, OpenCrevo services documentation (src/data/services.ts in this repository). Note per content-gap-analysis.md: existing Selenium to Playwright migration content, including enterprise-specific guides, largely omits regulated-industry audit trail and parallel-run validation concerns; this article's incremental risk-tier and parallel-run framework is written to fill that specific gap rather than restate general migration mechanics already well covered elsewhere.