Blog / How to Migrate From Selenium to Playwright: A Step-by-Step Guide
How-To

How to Migrate From Selenium to Playwright: A Step-by-Step Guide

The clicks and fills port fast. The wait helpers are where Selenium migrations stall. How to move a suite to Playwright flow by flow and keep coverage.

Ask Playwright to click a button that has not rendered yet and it waits for the button. Ask Selenium and, unless someone set an implicit wait, find_element throws NoSuchElementException on the spot. Many Selenium suites pay for that gap with a WebDriverWait helper and, somewhere, a time.sleep(3) that someone added to kill one flake.

The wait code is where a migration’s time goes, since the clicks and fills port almost line for line. Here is how to move your suite to Playwright flow by flow and delete those waits instead of translating them.

What you’ll learn

  • What to inventory in your Selenium suite before you write any Playwright
  • How locators, waits, and assertions map from Selenium to Playwright
  • A side-by-side, flow-by-flow migration that never drops coverage
  • What the port fixes, what it leaves untouched, and what to do about the difference

Why Teams Move From Selenium to Playwright

Teams migrate to stop hand-managing waits and parallel infrastructure. One in two developers in State of JS 2025 had used Playwright, up from under a third two years earlier.

We worked through the Playwright versus Selenium decision on its own, and this guide assumes you have already made it. What Playwright removes is two of Selenium’s most expensive chores.

The first chore is waiting. Selenium hands timing to you through explicit and implicit waits, and a suite of any age has grown a layer of them. Playwright runs actionability checks before every action and, for a click, waits on its own for the element to be visible, stable, and able to receive events.

Three cases that Selenium suites keep helpers for show the gap. We built a test page for each and ran both tools against them on 23 October 2026, Selenium 4.51.0 and Playwright 1.64.1, both driving headless Chrome 155.

What the page doesSelenium 4.51.0Playwright 1.64.1
Button renders 700 ms after loadfind_element throws NoSuchElementException 0.01 seconds after loadclick() waits for the button and clicks it 0.9 seconds after load
Overlay covers the button for 6 secondsChromeDriver retries for 1.05 seconds, then throws ElementClickInterceptedExceptionclick() waits out the overlay and clicks at 6.2 seconds
Framework re-renders the buttonThe held element throws StaleElementReferenceExceptionThe locator finds the new button and clicks it

None of the Playwright results needed a wait or a retry in the test. Each Selenium result is a helper your suite already carries.

The second chore is parallelism. Playwright Test, the Node.js runner, spreads spec files across worker processes out of the box, and a --shard flag splits one run across several CI jobs. Selenium leaves parallelism to your test runner (pytest-xdist, for one) and, once runs cross machines, to a Grid you host or rent. Add the trace viewer and codegen, and the day-to-day friction drops far enough to justify the port.

Four Lists to Build Before You Start

Before writing any Playwright, inventory the Selenium suite so you migrate by value instead of alphabetically. The audit separates the flows worth keeping from the dead weight and flags the waiting code you are about to delete. A migration also gives you cover to drop tests that have not caught a real bug in a year.

Pull together four lists:

  1. Critical flows by business value: Rank suites by what they protect, starting with auth, checkout, and anything tied to revenue, and migrate those first so the highest-risk coverage lands earliest.
  2. Flaky and skipped tests: Anything quarantined or marked skip is a deletion candidate, not a migration candidate. Migrating a flake just moves the flake.
  3. Custom wait and retry helpers: Every WebDriverWait, every polling loop with a hand-tuned interval, every sleep. In Java suites this is also every FluentWait. Playwright makes this code obsolete, so flag it for removal up front.
  4. Locator strategies in use: Count how much of the suite leans on fragile XPath or deep CSS versus stable IDs and data-testid. The fragile share tells you how much locator refactoring the port really involves.
Size the Port in Journeys

A hundred tests covering six user journeys is a six-journey migration. Plan the timeline on that number.

Eight Swaps That Cover Most of the Port

Most of the migration is a small set of concept swaps. The table maps the Selenium constructs you will hit most often, with Selenium in Python and Playwright in its Node.js API. Playwright’s Python package uses the same calls in snake_case, such as get_by_role.

SeleniumPlaywrightNotes
driver.get(url)await page.goto(url)Direct equivalent
find_element(By.CSS_SELECTOR, …)page.locator(…)Lazy locator, re-queried each use
find_element(By.ID, “x”)page.locator(‘#x’)Direct swap, then move to getByRole where the element is user-facing
WebDriverWait(…).until(…)Nothing. Auto-waitingCovered by actionability checks
element.click()await locator.click()Waits for actionability first
element.send_keys(“text”)await locator.fill(“text”)Replaces the value, no keystrokes
assert element.text == “x”await expect(locator).toHaveText(“x”)Web-first assertion auto-retries
Selenium GridWorkers and —shard (Node), pytest-xdist (Python)Parallelism with no server to run

The fourth row is the one that matters. In Selenium you wrote waits everywhere. In Playwright most of them need no counterpart, because web-first assertions like expect(locator).toHaveText() re-check on their own until the condition holds or the timeout expires.

Row two is the quiet one. Selenium hands you an element reference that goes stale the moment the DOM re-renders under it, and its own docs prescribe re-locating the element rather than waiting longer. A Playwright locator works almost like a person who reads the screen again before each click. It resolves the element fresh before every action, which is how the re-render case above clicked cleanly.

The trap is porting find_element to page.$(). That returns an ElementHandle, and a handle goes stale exactly like a Selenium reference.

const handle = await page.$('button.pay');               // pinned to one DOM node
const pay = page.getByRole('button', { name: 'Pay' });   // resolved again on every action

// ...the framework re-renders the button...
await pay.click();     // clicks the new button
await handle.click();  // throws: Element is not attached to the DOM

Port find_element to page.locator() or a getBy call, and the stale reference has nowhere to come from.

Row six changes behavior twice. fill("hello") replaces whatever the field held, where Selenium’s send_keys typed after it. A field that read “old text” ends as “hello” in Playwright and as “old texthello” in Selenium. fill also fires no keydown events, while pressSequentially("hello") fires five. A field whose JavaScript listens for keystrokes, such as some input masks, needs pressSequentially.

Rewriting Every Test Anyway?

Bring one critical flow to a demo. See it run with no selector to write.

How to Migrate in Seven Steps

Migrate flow by flow with both frameworks running in parallel. Selenium stays green and gating CI until each flow has a stable Playwright replacement, and only then does the old test go. The old suite protects you the whole way, and you can stop at any point with a working suite.

A coding agent makes a migration like this much faster when it has the old system’s outputs to check against, and work that once took months goes quicker. The bottleneck moves to validation, proving the ported suite still checks what the old one did. The steps below keep Selenium running for that reason.

  1. Install Playwright alongside Selenium: Run npm init playwright@latest in the existing repo, or the Python or .NET equivalent. When a package.json is already there, the installer adds Playwright to it instead of starting a new project. Do not remove Selenium. Both run in CI through the transition.
  2. Recreate one critical flow with codegen: Run Playwright codegen and walk through your highest-value flow in the browser. It records a script and prioritizes role, text, and test-id locators, which beats translating the old test line by line.
  3. Refactor the recorded locators: Replace any CSS path codegen fell back to with getByRole, getByLabel, or getByText wherever the element is user-facing, as Playwright’s locator guide recommends. Paste an existing stable selector into page.locator() only where no role-based locator fits.
  4. Delete the waits, do not port them: Remove every WebDriverWait, polling loop, and sleep from the ported flow. If a step seems to need one anyway, express it as a web-first assertion such as await expect(...).toBeVisible() rather than a timeout.
  5. Convert assertions to web-first form: Swap raw equality checks for toHaveText(), toBeVisible(), and the rest. They re-check until the condition holds, where a raw check samples one moment and fails.
  6. Run both suites and compare: Let each Playwright test run beside its Selenium twin for a few builds. When the Playwright version holds, delete the Selenium test in the same pull request.
  7. Cut over CI parallelism and retire Grid: Once most flows are ported, move CI to Playwright workers and --shard (Node) or pytest-xdist (Python). Decommission Selenium Grid unless you still need real Safari, which Playwright’s WebKit build is not, or browser versions Playwright does not bundle.

Three Things That Break During the Migration

The actions translate without surprises, fill aside. What snaps is the timing model the old suite assumed and the abstractions the team built to survive it.

  1. A ported sleep: A time.sleep(3) that masked a race in Selenium is dead weight in Playwright, because auto-waiting already covers that race, the first of the root causes of flaky tests we traced. Leave it in and every run pays three seconds for nothing. Deleting it feels wrong right up to the moment you watch the test pass faster without it.
  2. The page-object base class: Many Selenium suites wrap the driver in a custom layer of retry helpers and wait wrappers. Port that layer wholesale and you carry Selenium’s habits into Playwright, hiding the auto-waiting you migrated for. Rebuild the abstraction thin, or skip it until the ported flows tell you what it should hold.
  3. Text-bound locators: Role-based locators survive a renamed class, which is the reason to refactor toward them. They still bind to the words on the page. getByRole('button', { name: 'Sign in' }) matches nothing the day the button reads “Log in”. The migration changes how your tests wait and leaves what they are bound to. A QA engineer at a web-platform company told us Selenium had sort of become obsolete for their team, so some of their newest products got Playwright scripts. The locators kept changing there too, and the scripts were close to no use.

Is a Full Rewrite the Time to Drop Locators?

A full port is the cheapest moment you will ever have to change the model underneath it, because you are already paying to rewrite every test. Playwright is the strongest code-first option among the eight alternatives to Selenium we ranked, and it keeps the locator model intact.

Moving to Playwright cuts timing flakiness and retires the parallel infrastructure you were maintaining, and both are worth doing. What the port does not remove is the repair work, because a Playwright test points at a locator a redesign can invalidate.

Playwright 1.56 added an opt-in healer agent, which has your coding agent rerun the failing tests and patch them, for example by rewriting a broken locator. That moves the repair to an agent, and the selector stays in your test code for the next redesign. You can put numbers on that upkeep for your own suite before deciding where the rewrite money goes.

Pie is an agentic testing platform built on the other side of that choice. You author supported tests without writing or maintaining a selector.

  • Autonomous discovery: Pie’s agents explore the reachable, supported flows in your app and generate tests for them, without anyone re-authoring coverage flow by flow.
  • Self-healing, vision-first execution: Pie carries out each step vision-first and identifies elements by context, position, and function. A button whose ID or text changes can be found again with no locator to edit.
  • Web and native mobile: Pie tests web apps and native iOS and Android apps in one platform. Playwright labels its Android support experimental and has no iOS app API. A Playwright port leaves native mobile where it was.

Already running Playwright at the PR level? Keep it, and run Pie beside it to check the product from the user’s side. Pie reads the screen, so assert a stable result rather than a message that flashes past. If a full rewrite is already approved, though, evaluate the option where your team stops writing selectors.

Delete Before You Translate

A Selenium suite keeps its timing model in code, mostly in the wait helpers and the base class around them. Ported, that code goes on paying for races Playwright already handles. Delete it flow by flow while Selenium keeps gating CI. Once a replacement holds, Playwright’s own waiting does the work your helpers did.

Typing the port is faster now. The slow part is showing the new suite catches what the old one caught. The binding comes along unchanged too, because a Playwright test points at an element by its name or a selector just as a Selenium one did.

Pie offers a way out of that binding. Its agents explore the reachable, supported flows in your app and test them from the user’s side, and you author supported tests without maintaining selectors. Price that difference while the port is only a proposal.

One Demo Before the Rewrite

Show us the flow that breaks most. Keep selector upkeep off the plan.

Frequently Asked Questions

It depends less on test count than on how much custom waiting and page-object code the suite carries. Straightforward flows port quickly with Playwright running beside Selenium.

Suites full of explicit-wait helpers take longer, because the real work is deleting that scaffolding. Plan the timeline by user journey.

Yes, and side by side is the safe way to migrate. Keep the Selenium suite green and gating CI while you port flows into Playwright one at a time.

Once a flow is stable in Playwright, delete its Selenium counterpart. Coverage stays on until each replacement has held.

Most of them, as a simplification more than a translation. Playwright recommends user-facing locators like getByRole, getByLabel, and getByText over CSS or XPath. Paste existing CSS selectors into page.locator() to move fast, then refactor the high-churn ones to role-based locators, which keep matching after a class is renamed.
Waiting. Selenium makes you manage timing with explicit and implicit waits. Suites collect WebDriverWait helpers and sleep calls to cope. Playwright auto-waits for each element to be actionable before it acts. The biggest change in a migration is deleting that wait code, because porting it carries Selenium's flakes along.

Partially. Codegen records a flow as you click through it, and a coding agent can speed up the typing. Playwright publishes migration guides for Protractor and Puppeteer, but none for Selenium.

The slow part is proving the ported suite still checks what the old one did.

It fixes most timing flakiness and leaves locator flakiness. Failures from acting before the UI is ready mostly disappear, because auto-waiting covers the races Selenium's explicit waits miss. A changed label or a reworked flow breaks Playwright locators too, since both frameworks bind each test to one.

Yes, when the rewrite is already approved. That is the cheapest time to drop locators altogether, because you are already paying to rewrite every test.

Pie's agents explore reachable, supported flows and generate the tests, and you author supported tests without maintaining selectors.

Adithya Aggarwal
Adithya Aggarwal
CTO & Co-founder at Pie

Eight years building search and delivery systems at Amazon. The kind of scale where flaky tests block billion-dollar releases. Now CTO at Pie, building AI agents that adapt when your UI changes. LinkedIn →