Selenium to Playwright migration, test by test

What changes in the code

A conversion is done by engineers reading tests, one at a time. The Selenium below is Selenium 4: several of the things people repeat about Selenium were true of Selenium 3 and stopped being true when 4 shipped.

One test — sign in, wait, assert — as it stands today:

import java.time.Duration;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

class LoginTest {
  @Test
  void signsIn() {
    WebDriver driver = new ChromeDriver();
    try {
      driver.get("https://example.com/login");
      driver.findElement(By.id("username")).sendKeys("ada");
      driver.findElement(By.id("password")).sendKeys("hunter2");
      driver.findElement(By.cssSelector("button[type='submit']")).click();

      WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
      WebElement banner = wait.until(
          ExpectedConditions.visibilityOfElementLocated(By.cssSelector(".welcome")));

      Assertions.assertEquals("Welcome, Ada", banner.getText());
    } finally {
      driver.quit();
    }
  }
}

And the same test after:

import { test, expect } from '@playwright/test';

test('signs in', async ({ page }) => {
  await page.goto('https://example.com/login');
  await page.getByLabel('Username').fill('ada');
  await page.getByLabel('Password').fill('hunter2');
  await page.getByRole('button', { name: 'Sign in' }).click();

  await expect(page.getByText('Welcome, Ada')).toBeVisible();
});

Every sample on this page is written against Playwright 1.62.

The driver lifecycle and the explicit wait disappear, and the test body is down to five lines. The converted file is also still recognisable: page objects survive as plain classes, and your XPath runs. page.locator('xpath=//button') is a supported locator, and Playwright reads any selector string starting with // as XPath without the prefix. Playwright's other-locators documentation still recommends user-visible locators over XPath tied to the implementation, and it states that XPath does not pierce shadow roots. A suite of plain XPath against server-rendered HTML ports on the first afternoon. A suite of XPath against a component library with shadow DOM has selectors that cannot port at all, and finding out which of the two you have moves the number further than the test count does.

The wait that becomes no wait

Somewhere in your repository is a wait helper that has been growing for three years. In Selenium it earns its place:

import java.time.Duration;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

class Checkout {
  static void placeOrder(WebDriver driver) {
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    wait.until(ExpectedConditions.elementToBeClickable(By.id("place-order"))).click();
  }
}

In Playwright there is nothing to translate. The helper is deleted:

import { test } from '@playwright/test';

test('places the order', async ({ page }) => {
  await page.goto('https://example.com/cart');
  await page.getByRole('button', { name: 'Place order' }).click();
});

Before that click runs, Playwright checks that the locator resolves to exactly one element and that the element is visible, stable, receives events and is enabled, and it waits for those checks to pass within the timeout. Assertions retry on the same principle: expect(locator).toBeVisible() keeps checking until it passes or the assertion timeout is reached, five seconds by default. Deleting that helper is part of why the converted suite is shorter.

Idioms with no clean equivalent

• driver.manage().timeouts().implicitlyWait(...) — nothing replaces it, because Playwright has no global implicit wait. There is a timeout per test, thirty seconds by default; a timeout per assertion, five seconds by default; and an optional timeout per action. Selenium 4's own documentation warns against mixing implicit and explicit waits, because the two combine into wait times nobody predicted. A suite that mixed the two has behaviour to unwind before any of it can be translated faithfully. Budget for that separately.
• StaleElementReferenceException and the retry loop around it — the exception has no counterpart. A Playwright locator is a description of how to find an element, and the documentation is explicit that every time a locator is used for an action, an up-to-date DOM element is located in the page. Nothing is held between calls, so nothing goes stale. Deleting the retry loop usually takes out the most-edited file in the repository.
• @FindBy and PageFactory — there is no annotation-driven page factory. A page object becomes a plain class that holds locators and exposes methods, which is a small change to the file and a large change to a Java team's habits: the field is no longer populated for you, and the constructor stops being ceremonial.
• Actions chains and JavascriptExecutor — some of this maps straight over. Hover, drag and keypress become locator.hover(), locator.dragTo() and locator.press(). The JavascriptExecutor calls are the ones to read individually: a scripted click was usually there to get past something the driver refused to do, so check whether Playwright still needs the escape hatch before porting one.

The same selector, a different outcome

A selector can port without a single edit and still fail:

import { test, expect } from '@playwright/test';

// Throws a strict mode violation when the invoice table has more than one Delete button.
test('deletes an invoice - ambiguous', async ({ page }) => {
  await page.goto('https://example.com/invoices');
  await page.locator('//button[text()="Delete"]').click();
});

// Names one row, so it can only hit one button.
test('deletes an invoice - unambiguous', async ({ page }) => {
  await page.goto('https://example.com/invoices');
  await page.getByRole('row', { name: 'INV-1042' })
    .getByRole('button', { name: 'Delete' })
    .click();

  await expect(page.getByText('INV-1042')).toHaveCount(0);
});

The Playwright locator documentation puts it this way: "Locators are strict. This means that all operations on locators that imply some target DOM element will throw an exception if more than one element matches." Selenium 4's documentation describes the other behaviour just as plainly: the singular find element method returns a reference to the first element found within a given context. Some share of your suite will fail on conversion for this reason alone, and each of those failures is a test that had been asserting against whichever element the DOM happened to put first. We have not measured what that share is, so we do not publish one.

Where the fix has to be quick, locator.first() is the retreat. The repair is a locator that can only match one thing, and the documentation recommends seven built-in ones for the job: getByRole, getByText, getByLabel, getByPlaceholder, getByAltText, getByTitle and getByTestId. Your converted suite ends up written in that vocabulary, and the translation record maps your old selectors onto it.

What replaces the Grid

Concurrency stops being a machine somebody maintains and becomes a config file:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  workers: process.env.CI ? 4 : undefined,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'https://staging.example.com',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

Workers are the parallelism on one machine. Across machines, npx playwright test --shard=1/4 in four CI jobs runs a quarter of the suite in each. The webkit project runs Playwright's WebKit build, which is not Safari on an iPhone. That distinction is one of the few places a Selenium suite loses coverage in the move.

What it costs

A migration is priced by the time it takes, which is why we price the engineers rather than the suite. Engineers are billed hourly, from $50 an hour, depending on where the engineer sits. The minimum engagement is one full-time engineer for one month.

For a migration, the number turns on the size of the suite, the language it is written in, how much of it is page objects rather than inline driver calls, and how much of the suite is worth keeping. That last one is the cheapest lever you have. A test that has been quarantined for a year is a test somebody already decided to live without, and converting it costs the same as converting one that works.