How to Migrate from Selenium to Playwright

Should You Migrate from Selenium to Playwright?

Migrate when you are hitting a limit, not when you are bored of the syntax. A working Selenium suite that your team maintains comfortably is not a problem that needs solving, and the migration will introduce fresh instability while the new suite settles.

The honest triggers are:

• Wait-driven flakiness - your suite is a thicket of explicit waits and the occasional sleep, and failures correlate with CI load rather than code changes.
• Stale element churn - your app re-renders and you spend time re-finding elements you already found.
• Grid maintenance - nodes, driver drift and browser version pinning cost more attention than the tests do.
• Cross-origin and multi-tab flows - you are working around the browser rather than driving it.
• Debugging time - a CI failure gives you a stack trace and a screenshot, and reproducing it locally takes longer than fixing it.

Reasons to Stay on Selenium

A browser requirement or a mobile dependency can cancel a migration outright, and both are easy to discover late.

The first is browser requirements. Playwright drives its own bundled browser builds, including a WebKit build that is not Safari. If you have a compliance or support requirement to test on a specific real browser version, or on Safari proper, Selenium plus a real-browser grid still answers that and Playwright's bundled builds do not.

The second is mobile. Playwright has no Appium equivalent. If a meaningful part of your estate drives native apps or real devices, that part is not migrating, and your plan needs to say so rather than discovering it in week three.

It is also worth being accurate about what Selenium is in 2026 rather than comparing against the Selenium of five years ago. Selenium Manager resolves drivers automatically, so manual driver downloads are no longer a differentiator, and WebDriver BiDi gives Selenium a bidirectional protocol of its own. If you are building a migration case, build it on waits, locator resilience and debugging, which are real, rather than on driver management, which is not. For a broader side-by-side, see the Playwright vs Selenium vs Cypress comparison.

Triage Your Suite Before You Convert Anything

Every migration guide tells you to audit your suite and none of them say how. The audit is a handful of greps, and it tells you the size of the job in about ten minutes.

# How much of your suite is wait logic?
grep -rc "WebDriverWait\|ExpectedConditions" src/test/ | grep -v ":0"

# Sleeps are the specs that will need real thought
grep -rn "Thread.sleep" src/test/

# Locator strategy mix - XPath volume predicts rewrite effort
grep -rho "By\.\w*" src/test/ | sort | uniq -c | sort -rn

# Custom infrastructure with no automatic equivalent
grep -rln "ThreadLocal<WebDriver>\|DriverFactory\|@FindBy" src/test/

# The blocker: anything Appium is not migrating
grep -rln "io.appium\|AndroidDriver\|IOSDriver" src/test/

Read the output as a plan. A high Thread.sleep count means specs that hide real race conditions, and those need attention rather than translation. Heavy @FindBy and DriverFactory usage means the harness is the bulk of the work, not the tests. Any Appium hit is scope you remove from the migration entirely.

Conceptual Shifts Behind the Mappings

Three conceptual shifts explain almost every surprise in a converted suite. Understanding them first makes the mapping tables read as obvious rather than arbitrary.

Eager Handles Become Lazy Queries

Selenium's findElement queries the DOM at the moment you call it and hands back a WebElement bound to that one node. If the page re-renders, that handle is stale and the next use throws.

A Playwright locator performs no DOM query when you create it. It stores the query, and every time you use it, Playwright locates an up-to-date element. You can build a locator before the page has even loaded. The practical consequence is that StaleElementReferenceException has no equivalent, because there is no stored node to go stale. It is also why you cannot test existence by constructing a locator; use a count or an assertion instead.

Strict Mode Surfaces Ambiguity You Already Had

This is the error that greets most people on their first converted spec. Any locator action that resolves to more than one element throws rather than acting on the first match. Selenium's findElement silently returned the first, which meant an ambiguous selector could pass for years while testing the wrong element.

Treat each violation as a bug report about your selector, not an obstacle. Narrow with a scope or a filter rather than reaching for first(), which just reinstates the old behaviour and the old blind spot. Counting operations are exempt, so count(), all() and a count assertion all work happily on many elements. The Playwright locators guide covers the filtering patterns in depth.

Language Choice Decides How Much Rewriting You Do

Selenium has official bindings for Java, Python, C#, Ruby and JavaScript. Playwright has Java, Python, .NET and Node. A Java Selenium suite can become a Java Playwright suite, and the Java, Python and .NET APIs are synchronous in style, so the control flow you already have survives.

Node is the exception: it is async throughout and every call needs await. Advice that every migrated method becomes async is true only if you are moving to Node. Ruby has no official Playwright binding at all, which makes a Ruby Selenium suite a language migration as well as a framework one. Decide this before you convert a single spec, because it is the one choice that touches every file.

Locators and Interactions

The third column is the one that matters. A row marked Needs care compiles and runs but does not mean the same thing as the Selenium line it replaced.

Waits and Assertions

This section is where a mechanically converted suite becomes flakier than the Selenium original. The wait-deletion rule and the retry rule prevent it.

The Wait Deletion Rule

Common advice is to delete your explicit waits. Followed literally, that converts explicit waits into silent races. The rule is narrower: delete the wait when the thing you were waiting for is one of the five actionability checks Playwright already performs, and keep it as an assertion when you were waiting for application state.

Before acting, Playwright checks that the element is attached to the DOM, visible, stable (not animating), able to receive events (not obscured), and enabled. A wait for any of those is redundant. A wait for a spinner to disappear, a row count to settle or a toast to appear is application state and becomes a web-first assertion.

Query Methods Do Not Auto-Retry

This is the subtler of the two rules and the one that caught us in testing. expect(locator) auto-retries until it passes or times out. textContent(), getAttribute() and inputValue() resolve once and return immediately. So the natural port of Selenium's getText followed by assertEquals produces a test that reads the DOM before the application has updated it.

We hit exactly this while verifying the code for this guide. Running a migrated flow against the Selenium Playground on the TestMu AI cloud grid, the first version read the output element straight after the click and asserted an empty string:

// Reads once, before the handler has written the value
const shown = await page.locator('#message').textContent();
// -> ASSERTED MESSAGE: ""

The web-first assertion passes against the identical page, because it polls until the DOM matches:

await page.getByPlaceholder('Please enter your Message').fill('Migrated from Selenium');
await page.locator('#showInput').click();
await expect(page.locator('#message')).toHaveText('Migrated from Selenium');
// -> PASS  #message = "Migrated from Selenium"

Nothing about the page changed between those two runs. The only difference is whether the assertion retries. If you take one rule from this guide, take this one: assert on the locator, not on a value you already extracted.

The Harness Is Where the Time Goes

Converters handle test bodies. They do not handle the scaffolding around them, and on a mature suite that scaffolding is most of the work.

Page Objects Get Simpler

A Selenium page object takes a driver, declares fields with @FindBy and calls PageFactory to populate them. The Playwright equivalent takes a page and assigns locators directly, because a locator is already a lazy query and needs no initialisation step.

export class LoginPage {
  constructor(page) {
    this.page = page;
    this.email = page.getByLabel('Email');
    this.password = page.getByLabel('Password');
    this.submit = page.getByRole('button', { name: 'Sign in' });
  }

  async login(email, password) {
    await this.email.fill(email);
    await this.password.fill(password);
    await this.submit.click();
  }
}

The locators are assigned in the constructor but resolve nothing until used, so there is no staleness risk in holding them. If you are formalising this layer during the migration, the page object model guide covers the structure in more detail.

Authentication Is the Biggest Wall-Clock Win

If every Selenium test logs in through the UI in setup, that cost is paid once per test. Playwright lets you log in once in a setup project, save the browser state, and have every other test start authenticated. On a large suite this removes more runtime than any other single change in the migration.

What Does Not Convert?

Running Both Suites During the Transition

Migrate incrementally and keep Selenium authoritative until each replacement has been stable for several days. Two practical rules keep that period honest.

First, never let a spec exist in both suites as a passing test at the same time without comparing them. A Playwright test that passes while its Selenium twin fails deserves investigation before you trust it; more than once it means the new test is asserting less than the old one.

Second, decide what a red build means while both run. The usual answer is that Selenium gates the merge until its replacement has earned the gate, and the Playwright job runs non-blocking until then.

You do not have to retire your Grid on day one either. Playwright can connect to a Selenium 4 Grid through the SELENIUM_REMOTE_URL environment variable for Chromium-based browsers, which Playwright describes as experimental. It buys you a transition period on infrastructure you already pay for, but Firefox and WebKit will not run that way.

Longer term, the infrastructure question outlives the framework question. TestMu AI's test automation cloud runs Selenium, Playwright, Cypress and Puppeteer across 3,000+ real browser and OS combinations with no grid to stand up or patch, which means both suites can run on one place while you migrate rather than you maintaining two sets of infrastructure. To point an existing config at it, follow the setup guide for Playwright testing with TestMu AI.

How Long a Selenium to Playwright Migration Takes

Published per-test estimates circulate widely and almost none of them state a methodology, so treat any number you read, including this one, as a shape rather than a forecast. What actually drives effort is not the test count but how much shared machinery sits underneath.

The first ten specs take disproportionately long, because that is when the config, fixtures, auth setup and page objects get built. After that the per-spec cost drops sharply, and the long tail is whatever depended on custom infrastructure. What reliably pushes a migration past its estimate is a high Thread.sleep count, heavy @FindBy and driver-factory usage, or the discovery that part of the suite is Appium and was never in scope.

Run the triage greps from earlier in this guide before you commit to a date. They tell you which of those three you are dealing with in about ten minutes, which is more useful than any per-test average.