AI-Assisted Playwright Migration: Using Claude Code + Playwright Agents to Port Selenium Tests

Every prompt you need is below, ready to paste  plus a before/after code example and the Selenium-to-Playwright translation table.

If you lead the org rather than write the tests: This migration is a budget and risk decision wearing a tooling costume. Three things to take from this guide. 

• AI collapses the generation cost of migration, not the judgment cost; staff the review, not the typing.
• Demand the four-state tracker (converted → passing → validated → parallel) in status reports ("500 tests converted" is not progress; "120 validated" is). 
• The parallel-run window temporarily doubles CI spend; approve it up front as the insurance premium it is. The commercial version of this decision; cost, engagement models, proof lives on our managed testing page. Hand the rest of this article to your QA lead, then ask them the retirement-rule question in your next 1:1.

1. Choose CLI, MCP, or Agents by Where the Agent Operates

Don't start with "CLI vs MCP." Start with a simpler question: where is the agent working, and what can a human review before the old Selenium test gets retired?

If Claude Code is working inside your repo: reading files, editing tests, running commands - Playwright CLI is the default. The evidence stays where your reviewers already look: source files, test runs, CI behavior. Playwright's own documentation points coding agents this way when repo access is the boundary.

If you're working through an MCP-native client, or browser automation has to go through a managed server, Playwright MCP has a narrower job: controlled browser exploration through accessibility snapshots and tool calls. Useful, but it's the exploration tool, not the migration engine. (New to MCP? Start with our Playwright MCP vs CLI guide.)

Playwright Agents sit above both. Planner, generator, and healer are workflow roles, they separate "what should this test prove?" from "write the code" from "fix the failure." That separation is the whole game, as you'll see.

One honest note on maturity: this tooling is young. Public issue reports tell the story, Claude Code users have described Playwright MCP results as "very variable," with the agent sometimes driving the browser well and sometimes falling back to curl instead. Another reported MCP issue involved a browser-profile lock where navigation retries opened blank tabs until failing. Neither is disqualifying. Both are reasons to pilot before you trust the boundary, which is what the rest of this guide is for.

And if you're wondering about Playwright codegen - the built-in recorder  it's a different tool for a different job. Codegen records your clicks into a script. Agents reason about an existing suite's intent. For migration, you need the second one; nobody wants to hand-replay 2,000 Selenium tests into a recorder.

For most Selenium-to-Playwright migration in Claude Code: CLI by default, MCP when the client boundary requires it, Agents for the workflow. Boundary set. Now the part most teams skip.

2. Prepare Claude Code Before It Touches the Selenium Suite

The fastest way to ruin a migration is a vague prompt:

That asks for converted files. It doesn't ask for the one thing that matters: preserving the old suite's regression signal. An agent rewarded for output volume will happily produce 2,000 Playwright files that pass beautifully and protect nothing.

So before the first conversion, set project rules. Put them in your repo's CLAUDE.md (Claude Code reads it automatically at session start), or in the first prompt of a pilot:

Prompt - For this migration, preserve the intent of every Selenium test before rewriting it. Do not remove, weaken, or replace assertions only to make a Playwright test pass. Prefer user-visible assertions and accessible locators. If intent is unclear, stop and mark the test for human QA review. Do not delete Selenium tests unless explicitly instructed. Keep converted tests separate from the existing Selenium suite until approved. 

Then the working rules that keep the pilot from becoming an uncontrolled rewrite:

• Converted tests live in a migration branch or dedicated folder
• Selenium stays intact during the pilot - the old regression signal stays available
• Synthetic or sanitized data for anything sensitive, so browser artifacts can't leak real records
• Decide before the first run whether traces, screenshots, videos, and logs get stored — those artifacts are evidence, and in regulated environments, exposure
• Any assertion change requires human review. No exceptions.

Will Playwright reduce Selenium pain? 

Yes, auto-waiting alone kills a whole category of flake. But better tooling doesn't fix weak isolation, shared state, or shallow assertions. Those travel with you unless someone stops them at review.

One rule above all: the new test is not allowed to be easier to pass than the old one. Write it down. Enforce it in diffs.

3. Map the Selenium Suite by Business Risk

A 2,000-test suite is not 2,000 equal tasks. Some tests protect login and role-based access. Some protect billing, audit events, and data export. Some protect edge cases nobody hits. Some are so flaky nobody trusts them anyway. And a few encode years of business knowledge that exists nowhere else, those are the ones you can't afford to mistranslate.

Ask Claude Code to map before it rewrites:

Prompt - Review the Selenium test suite and create a migration map. For each test or test group, identify: 1. business workflow covered 2. current assertion intent 3. data dependencies 4. flakiness risk 5. migration difficulty 6. recommended Playwright priority: high, medium, low. Do not rewrite tests yet. Produce only the suite map and risks.

The map gives your QA lead three decisions: which workflows carry real product or compliance risk, which assertions actually protect release behavior, and which tests should be paused because nobody can say what they prove.

This is where you avoid the full-suite rewrite. The migration unit is a workflow your team can validate, not the suite. Start where the current suite already hurts: a flaky area, a high-risk user journey, a module with a clear owner.

The map also answers a CTO-level question: is this a tooling project or a QA architecture project? If the map comes back full of unclear assertions, shared test data, and brittle setup, Claude Code will still help, but generation speed was never your bottleneck. Judgment is. Someone has to decide what release risk each new test must prove, and that someone isn't the agent.

4. Plan One Workflow Before Generating Any Code

You've picked the first workflow. Resist the urge to generate.

The planner's job is to make the target assertions reviewable before code exists — because once a generated test is in the repo and passing, teams stop asking whether it proves the right thing. Green is very persuasive.

Prompt - Using the migration map, create a Playwright migration plan for the highest-risk workflow. Preserve the original Selenium test intent. Define the target Playwright assertions before generating code. List missing test data, fixtures, roles, auth states, or environment assumptions. Do not write the Playwright test until the plan is approved.

A useful plan names: the Selenium test being converted, the business workflow it protects, the old assertion's purpose in plain language, the proposed Playwright assertion for review, required roles and auth state, data setup, known flake risks, and notes for the QA owner.

Sounds slow? It's faster than debugging a hundred shallow generated tests later.

 Here's why this step exists. If the old Selenium test doesn't have a clear expected outcome, Claude Code has to infer what the new test should prove, and that's where agent-generated tests go wrong. The agent clicks through the same flow but checks a weaker condition, accepts the wrong state, or treats a product mismatch as a test-repair problem. Academic work on agentic testing calls this the oracle problem: the agent needs a reliable way to decide what "correct" means. Your planner step is the oracle,  it makes expected behavior explicit before the generator gets its turn.

5. Generate One Test Group, Then Heal Only Mechanics

Plan approved? Generate — one workflow, one test group, one assertion set:

Prompt - Convert only this Selenium test group to Playwright. Use the approved plan. Keep the original assertion intent. Prefer accessible locators such as getByRole, getByLabel, and getByText. Do not remove assertions. If an assertion cannot be mapped, add a TODO and explain why.

This is where Playwright earns its reputation: role-based locators, auto-waiting, fixtures, clean isolation. Here's what the conversion actually looks like same test, same assertion intent:

Before (Selenium, Java):

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

driver.findElement(By.id("username")).sendKeys("admin@test.com");

driver.findElement(By.id("password")).sendKeys(TEST_PASSWORD);

driver.findElement(By.xpath("//button[@type='submit']")).click();

wait.until(ExpectedConditions.visibilityOfElementLocated(

   By.cssSelector(".dashboard-header")));

Assert.assertEquals(driver.findElement(By.cssSelector(".role-badge")).getText(), "Administrator");

After (Playwright, TypeScript):

Notice what changed and what didn't. The explicit wait is gone:  Playwright's assertions auto-wait. The brittle XPath and CSS selectors became role- and label-based locators that survive redesigns. But the assertion intent is identical: the admin logs in and sees administrator access. That's the invariant the whole workflow protects.

Generation is honestly not the risky part. Repair is. The healer is valuable when a selector changed, a wait is wrong, or setup needs a fix that doesn't touch the assertion. It's dangerous when it quietly weakens the assertion to make the test pass, because now your suite earns less release confidence than Selenium did, and the dashboard looks better.

Give the healer a narrow job:

Prompt - Run the generated Playwright test and diagnose failures. You may fix selector, wait, setup, and Playwright syntax issues. Do not remove or weaken assertions. If the assertion appears wrong, stop and explain the mismatch between the Selenium intent and Playwright behavior.

The review rule: the healer may fix mechanics; it may not change what the test proves. If a diff removes an assertion, changes a business condition, or swaps a specific check for a generic "is it visible?",  that diff needs a human.

And this is the honest pitch for QA architecture, ours or anyone's: the agent can generate. The hard part is knowing which changes preserve a test's value and which make the suite easier to pass. That skill doesn't come with the subscription.

Selenium to Playwright: The Mechanical Translations

6. Validate That the Test Fails for the Right Reason

A passing Playwright test is a candidate, not a replacement. The question that promotes it: if the protected behavior breaks, does this test fail?

Prompt- Validate this migrated Playwright test. Identify the specific product regression it should catch. Suggest one safe mutation, mocked failure, or controlled test-data change that should make the test fail. Confirm whether the current assertion would detect that failure. If not, propose a stronger assertion.

For a regulated product, take healthcare SaaS, the hardest case -  the controlled checks mirror real workflow risk: remove a role permission and confirm the access test fails. Return the wrong workflow state and confirm the state assertion catches it. Hide an audit event; the audit test should scream. Feed a sanitized record with missing required fields; validation should fail. Break a billing status; the downstream workflow should block. If it works under those constraints, it works for your CRUD app.

Why so much ceremony? DORA's 2025 research found AI adoption continuing to correlate negatively with delivery stability. That's not "AI is bad." It's "faster output without stronger guardrails destabilizes delivery." Generation is output. Validation is the guardrail.

Track every test through four states, and don't collapse them:

• Converted —> a Playwright version exists. No reliability claim earned yet.
• Passing —> it runs green. The assertion still needs validation.
• Validated —> it has proven it fails for the intended regression.
• Ready for parallel —> QA can compare it against Selenium in CI.

Each state triggers a different review decision. Teams that collapse them are back to counting converted files.

7. Run Both Suites in Parallel Before Retiring Anything

The day the Playwright test passes is not the day Selenium dies. It's the day comparison starts.

For high-risk workflows, run both suites long enough to compare regression signal for most teams that's two to four release cycles, not two days. 

Track: 

• Do both suites fail on the same real defects? 
• Does Playwright catch things Selenium missed (it should -  that's the upgrade)? 
• Does Selenium catch things Playwright missed (that's a migration bug)? 
• Plus flake per suite, runtime, false passes, false failures, CI stability, and review time per migrated test.

The retirement rule, written down: a Selenium test retires only when its Playwright replacement shows comparable or better regression signal, acceptable flake, and a validated assertion. That changes the migration story from "we converted the suite" to "we preserved the suite's risk coverage." Only one of those sentences survives an audit.

And keep retired Selenium tests in version control, tagged, not deleted. If a Playwright replacement misses a regression in its first month of solo duty, you want the old test restorable in minutes, not rewritten from memory.

Budget note your CFO will appreciate in advance: parallel running means paying for both suites' CI time for the duration of the window. For a large suite over two to four release cycles, that's a real line item. It's also temporary, it's the price of not gambling your regression coverage, and it ends the day retirements start. Say it up front and it's a plan; discover it in the invoice and it's an incident.

Pilot sizing: 10-20 high-value tests or one bounded workflow. Not the easiest tests,  a workflow important enough to matter and small enough to govern.

Good pilot candidates: login plus role-specific landing (access control), user creation and permissioning, billing status change with downstream checks, a sensitive workflow on synthetic data, audit event generation, a critical onboarding path with stable data.

Bad pilot candidates: the entire suite (nobody can review that much replacement evidence), smoke tests that only prove a page opened, the flakiest area if nobody can explain its expected behavior, and anything needing production-like sensitive data before governance exists.

What Doesn't Migrate (Plan for These Three)

• The language, usually. Most Selenium suites are Java or Python; Playwright's first-class experience is TypeScript. Playwright does offer Python and Java bindings, but agents generate best in TS, and most teams treat migration as the moment to switch. That's a skills decision, not just a tooling one. Budget for it.
• The BDD layer. If your Selenium suite sits under Cucumber or SpecFlow, the feature files and step definitions don't translate 1:1,  you're deciding whether to keep the BDD abstraction or drop it. Decide before the pilot, because it changes what "converted" means.
• The Grid infrastructure. Your Selenium Grid, and whatever maintenance it consumed retires with the suite. Parallelism moves into Playwright config and CI workers. That's a cost reduction, but someone owns the CI migration, and it isn't the agent.

8. Run a Pilot Your QA Lead Can Actually Govern

The pilot's job isn't proving the tool can generate a Playwright file. It's proving your team can repeat the review model without losing coverage.

The checklist:

• One bounded business-critical workflow.
• Synthetic data ready.
• Selenium baseline behavior known. 
• CLAUDE.md instructions in place.
• CLI/MCP boundary documented.
• Planner output QA-reviewed. 
• Generated tests keep assertion purposes. 
• Healer restricted · 
• Mutation-style validation defined.
• Parallel window agreed.
• Retirement criteria written.

Then measure whether it scales: 

1. Mapping time, generation time, 
2. Human review hours, 
3. Assertions that needed strengthening, 
4. Mechanical vs. requirement failures, 
5. Regression-signal comparison,
6. And the big one: can the team repeat this without a senior engineer babysitting every step?

Three failure modes, three different fixes:

If the pilot works, scale by workflow or module and keep the same validation gates for release review.

If the pilot fails because the agent cannot generate useful tests, fix the prompts and environment.

If it fails because assertions are unclear, fix the suite map before approving more generated tests or retiring Selenium coverage.

If it fails because no one has time to validate output, you do not have a tooling problem. You have a QA architecture capacity problem that will block safe migration.

Conclusion

Claude Code, Playwright CLI, MCP, and Playwright Agents genuinely make Selenium migration faster - the generation step shrinks from weeks to days. What they don't do is decide what your tests must prove. That was always the real work, and it still is.

If you want the speed without gambling your regression coverage on it, ThinkSys plans, validates, and scales these migrations with a Zero Critical Bugs Guarantee behind the release confidence, and the same framework-first discipline from our Playwright automation practice. Still choosing a framework?

 See our Playwright vs Selenium vs Cypress comparison. Worried about agent security boundaries? Read the enterprise MCP security guide.

And if migration is part of a bigger question, whether to keep QA in-house at all, our managed testing model and outsourced vs in-house cost breakdown cover the economics, and the Centerbase case study shows this discipline in production: regression cycle halved, roughly $120K a year saved.

Have a Selenium suite and a Claude Code subscription? Book a 30-minute migration assessment - we'll map your first pilot workflow.

Book a call