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 does | Selenium 4.51.0 | Playwright 1.64.1 |
|---|---|---|
| Button renders 700 ms after load | find_element throws NoSuchElementException 0.01 seconds after load | click() waits for the button and clicks it 0.9 seconds after load |
| Overlay covers the button for 6 seconds | ChromeDriver retries for 1.05 seconds, then throws ElementClickInterceptedException | click() waits out the overlay and clicks at 6.2 seconds |
| Framework re-renders the button | The held element throws StaleElementReferenceException | The 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:
- 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.
- Flaky and skipped tests: Anything quarantined or marked skip is a deletion candidate, not a migration candidate. Migrating a flake just moves the flake.
- Custom wait and retry helpers: Every
WebDriverWait, every polling loop with a hand-tuned interval, everysleep. In Java suites this is also everyFluentWait. Playwright makes this code obsolete, so flag it for removal up front. - 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.
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.
| Selenium | Playwright | Notes |
|---|---|---|
driver.get(url) | await page.goto(url) | Direct equivalent |
find_element( | 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(…) | Nothing. Auto-waiting | Covered by actionability checks |
element.click() | await locator.click() | Waits for actionability first |
element. | await locator.fill(“text”) | Replaces the value, no keystrokes |
assert element.text == “x” | await expect(locator) | Web-first assertion auto-retries |
| Selenium Grid | Workers 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.
- Install Playwright alongside Selenium: Run
npm init playwright@latestin the existing repo, or the Python or .NET equivalent. When apackage.jsonis 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. - 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.
- Refactor the recorded locators: Replace any CSS path codegen fell back to with
getByRole,getByLabel, orgetByTextwherever the element is user-facing, as Playwright’s locator guide recommends. Paste an existing stable selector intopage.locator()only where no role-based locator fits. - Delete the waits, do not port them: Remove every
WebDriverWait, polling loop, andsleepfrom the ported flow. If a step seems to need one anyway, express it as a web-first assertion such asawait expect(...).toBeVisible()rather than a timeout. - 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. - 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.
- Cut over CI parallelism and retire Grid: Once most flows are ported, move CI to Playwright workers and
--shard(Node) orpytest-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.
- A ported
sleep: Atime.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. - 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.
- 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.
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.
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.