Selenium to Playwright Migration: Step-by-Step Guide (2026)

# Initialize Playwright (creates playwright.config.ts + example tests)
npm init playwright@latest

# This creates:
#   playwright.config.ts    — configuration file
#   tests/                  — test directory
#   tests/example.spec.ts   — example test
#   package.json updates    — @playwright/test dependency

# Download browser binaries
npx playwright install --with-deps

project/
  ├── selenium-tests/          # Existing Selenium tests (untouched)
  │   ├── pages/               # Selenium Page Objects
  │   ├── tests/               # Selenium test files
  │   └── config/              # Selenium configuration
  │
  ├── tests/                   # New Playwright tests
  │   ├── pages/               # Playwright Page Objects
  │   ├── login.spec.ts        # Migrated/new tests
  │   └── fixtures/            # Shared test data
  │
  ├── playwright.config.ts     # Playwright config
  ├── test-data/               # Shared test data (both frameworks)
  └── package.json

// These break when CSS classes or structure change
driver.findElement(By.cssSelector("form.login-form input#email-field"));
driver.findElement(By.cssSelector("form.login-form input#pass-field"));
driver.findElement(By.cssSelector("form.login-form button.btn-primary"));
driver.findElement(By.xpath("//div[@class='error-msg']/span"));

// These survive CSS refactors and UI redesigns
page.getByLabel('Email');
page.getByLabel('Password');
page.getByRole('button', { name: 'Sign In' });
page.getByText('Invalid credentials');

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

// Click
wait.until(ExpectedConditions.elementToBeClickable(By.id("submit")));
driver.findElement(By.id("submit")).click();

// Type text
wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("email")));
driver.findElement(By.id("email")).clear();
driver.findElement(By.id("email")).sendKeys("user@example.com");

// Select dropdown
new Select(driver.findElement(By.id("country"))).selectByVisibleText("Canada");

// Navigate
driver.get("https://app.example.com/dashboard");

// Get text
String text = driver.findElement(By.id("heading")).getText();

// Checkbox
WebElement checkbox = driver.findElement(By.id("agree"));
if (!checkbox.isSelected()) { checkbox.click(); }

// Hover
new Actions(driver).moveToElement(driver.findElement(By.id("menu"))).perform();

// Click — auto-waits for element to be clickable
await page.getByRole('button', { name: 'Submit' }).click();

// Type text — fill() clears and types (replaces clear + sendKeys)
await page.getByLabel('Email').fill('user@example.com');

// Select dropdown
await page.getByLabel('Country').selectOption('Canada');

// Navigate
await page.goto('https://app.example.com/dashboard');

// Get text
const text = await page.locator('#heading').textContent();

// Checkbox — check() is idempotent (no if-not-checked guard needed)
await page.getByLabel('I agree').check();

// Hover
await page.getByText('Menu').hover();

// Text content
Assert.assertEquals("Welcome", driver.findElement(By.id("title")).getText());

// URL check
Assert.assertTrue(driver.getCurrentUrl().contains("dashboard"));

// Element visibility
Assert.assertTrue(driver.findElement(By.id("alert")).isDisplayed());

// Element count
List<WebElement> items = driver.findElements(By.cssSelector(".item"));
Assert.assertEquals(5, items.size());

// Attribute check
String value = driver.findElement(By.id("input")).getAttribute("value");
Assert.assertEquals("prefilled", value);

// Text content — auto-retries until match or timeout
await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();

// URL check
await expect(page).toHaveURL(/dashboard/);

// Element visibility
await expect(page.locator('#alert')).toBeVisible();

// Element count
await expect(page.locator('.item')).toHaveCount(5);

// Attribute check
await expect(page.locator('#input')).toHaveValue('prefilled');

public class LoginPage {
    private WebDriver driver;
    private WebDriverWait wait;

    // Locators
    private By emailField = By.id("email");
    private By passwordField = By.id("password");
    private By submitButton = By.cssSelector("button[type='submit']");
    private By errorMessage = By.cssSelector(".error-message");
    private By rememberMe = By.id("remember");

    public LoginPage(WebDriver driver) {
        this.driver = driver;
        this.wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    }

    public void navigate() {
        driver.get("https://app.example.com/login");
        wait.until(ExpectedConditions.visibilityOfElementLocated(emailField));
    }

    public void enterEmail(String email) {
        wait.until(ExpectedConditions.visibilityOfElementLocated(emailField));
        driver.findElement(emailField).clear();
        driver.findElement(emailField).sendKeys(email);
    }

    public void enterPassword(String password) {
        driver.findElement(passwordField).clear();
        driver.findElement(passwordField).sendKeys(password);
    }

    public void clickSubmit() {
        wait.until(ExpectedConditions.elementToBeClickable(submitButton));
        driver.findElement(submitButton).click();
    }

    public void checkRememberMe() {
        WebElement cb = driver.findElement(rememberMe);
        if (!cb.isSelected()) { cb.click(); }
    }

    public String getErrorMessage() {
        wait.until(ExpectedConditions.visibilityOfElementLocated(errorMessage));
        return driver.findElement(errorMessage).getText();
    }

    public void login(String email, String password) {
        enterEmail(email);
        enterPassword(password);
        clickSubmit();
    }
}

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

export class LoginPage {
    // Locators — defined once, auto-wait on every use
    readonly emailField: Locator;
    readonly passwordField: Locator;
    readonly submitButton: Locator;
    readonly errorMessage: Locator;
    readonly rememberMe: Locator;

    constructor(private page: Page) {
        this.emailField = page.getByLabel('Email');
        this.passwordField = page.getByLabel('Password');
        this.submitButton = page.getByRole('button', { name: 'Sign In' });
        this.errorMessage = page.locator('.error-message');
        this.rememberMe = page.getByLabel('Remember me');
    }

    async navigate() {
        await this.page.goto('https://app.example.com/login');
    }

    async enterEmail(email: string) {
        await this.emailField.fill(email);
    }

    async enterPassword(password: string) {
        await this.passwordField.fill(password);
    }

    async clickSubmit() {
        await this.submitButton.click();
    }

    async checkRememberMe() {
        await this.rememberMe.check();  // Idempotent — no if-guard
    }

    async getErrorMessage() {
        return await this.errorMessage.textContent();
    }

    async login(email: string, password: string) {
        await this.enterEmail(email);
        await this.enterPassword(password);
        await this.clickSubmit();
    }
}

import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/login-page';

test('user can log in with valid credentials', async ({ page }) => {
    const loginPage = new LoginPage(page);

    await loginPage.navigate();
    await loginPage.login('user@example.com', 'password123');

    await expect(page).toHaveURL(/dashboard/);
    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

test('shows error for invalid credentials', async ({ page }) => {
    const loginPage = new LoginPage(page);

    await loginPage.navigate();
    await loginPage.login('wrong@example.com', 'wrongpass');

    const error = await loginPage.getErrorMessage();
    expect(error).toContain('Invalid credentials');
});

// Java — browser setup scattered across code
WebDriverManager.chromedriver().setup();
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless");
options.addArguments("--window-size=1920,1080");
options.addArguments("--disable-gpu");
WebDriver driver = new ChromeDriver(options);
driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));

// For remote execution:
WebDriver driver = new RemoteWebDriver(
    new URL("http://selenium-hub:4444/wd/hub"),
    options
);

// testng.xml for parallel execution:
// <suite name="Tests" parallel="methods" thread-count="4">

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

export default defineConfig({
    testDir: './tests',
    timeout: 30_000,
    retries: 2,
    workers: 4,                       // Parallel execution — no Grid needed
    reporter: [
        ['html'],
        ['junit', { outputFile: 'results.xml' }],
    ],

    use: {
        baseURL: 'https://app.example.com',
        headless: true,
        screenshot: 'only-on-failure',     // Auto-screenshot on fail
        video: 'retain-on-failure',        // Auto-video on fail
        trace: 'retain-on-failure',        // Trace Viewer on fail
    },

    // Replace RemoteWebDriver + different browser configs
    projects: [
        {
            name: 'chromium',
            use: { ...devices['Desktop Chrome'] },
        },
        {
            name: 'firefox',
            use: { ...devices['Desktop Firefox'] },
        },
        {
            name: 'webkit',
            use: { ...devices['Desktop Safari'] },
        },
        {
            name: 'mobile-chrome',
            use: { ...devices['Pixel 7'] },
        },
        {
            name: 'mobile-safari',
            use: { ...devices['iPhone 14'] },
        },
    ],
});

# .github/workflows/selenium-tests.yml
name: Selenium Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      selenium-hub:
        image: selenium/hub:4.20
        ports: ["4444:4444"]
      chrome-node:
        image: selenium/node-chrome:4.20
        env:
          SE_EVENT_BUS_HOST: selenium-hub
          SE_EVENT_BUS_PUBLISH_PORT: 4442
          SE_EVENT_BUS_SUBSCRIBE_PORT: 4443
      firefox-node:
        image: selenium/node-firefox:4.20
        env:
          SE_EVENT_BUS_HOST: selenium-hub
          SE_EVENT_BUS_PUBLISH_PORT: 4442
          SE_EVENT_BUS_SUBSCRIBE_PORT: 4443

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with: { java-version: '17' }
      - run: mvn test -Dselenium.grid.url=http://localhost:4444

# .github/workflows/playwright-tests.yml
name: Playwright Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: '!cancelled()'
        with:
          name: playwright-report
          path: playwright-report/

driver.switchTo().frame("payment-frame");
driver.findElement(By.id("card-number")).sendKeys("4111111111111111");
driver.switchTo().defaultContent();  // Don't forget this!

// No switching — just chain frameLocator
await page.frameLocator('#payment-frame')
    .getByLabel('Card number')
    .fill('4111111111111111');
// No need to switch back — no context change happened

driver.findElement(By.cssSelector("input[type='file']"))
    .sendKeys("/absolute/path/to/file.pdf");

await page.locator("input[type='file']")
    .setInputFiles('./test-data/file.pdf');

// Multiple files:
await page.locator("input[type='file']")
    .setInputFiles(['file1.pdf', 'file2.pdf']);

String originalWindow = driver.getWindowHandle();
driver.findElement(By.id("open-popup")).click();

// Wait for new window
wait.until(ExpectedConditions.numberOfWindowsToBe(2));

// Switch to new window
for (String handle : driver.getWindowHandles()) {
    if (!handle.equals(originalWindow)) {
        driver.switchTo().window(handle);
        break;
    }
}

// Do work in popup...
driver.close();
driver.switchTo().window(originalWindow);

// Wait for popup and interact — no window handle juggling
const popupPromise = page.waitForEvent('popup');
await page.locator('#open-popup').click();
const popup = await popupPromise;

// popup is a full Page object — use it directly
await popup.waitForLoadState();
await expect(popup.getByRole('heading')).toBeVisible();
await popup.close();
// Original page is still accessible — no switching back

driver.findElement(By.id("delete")).click();
Alert alert = driver.switchTo().alert();
String alertText = alert.getText();
alert.accept();  // or alert.dismiss()

// Set up listener BEFORE triggering the dialog
page.on('dialog', async dialog => {
    expect(dialog.message()).toContain('Are you sure?');
    await dialog.accept();
});

await page.locator('#delete').click();

// Selenium cannot pierce shadow DOM natively
WebElement shadowHost = driver.findElement(By.cssSelector("my-component"));
SearchContext shadowRoot = shadowHost.getShadowRoot();
WebElement button = shadowRoot.findElement(By.cssSelector("button"));

// Playwright pierces shadow DOM by default
await page.locator('my-component button').click();

// getByRole, getByText etc. also pierce shadow DOM automatically
await page.getByRole('button', { name: 'Submit' }).click();

Convert this Selenium Java test to Playwright TypeScript.
Use semantic locators (getByRole, getByLabel, getByText)
where possible. Remove all explicit waits — Playwright
auto-waits. Use expect() assertions. Follow the Page
Object Model pattern with a separate page class.

// Then paste your Selenium test below the prompt