Risk‑based guidance for QA engineers who need to replace an established Selenium suite with Playwright while keeping behavioral coverage visible and auditable.


1. Start with an Inventory & Baseline

Before any code moves, capture what you are testing. A concrete inventory reduces the chance of “silent” coverage loss.

Export this inventory to a shared spreadsheet or a lightweight markdown table that the whole team can edit. Treat it as the definition of coverage for the migration project.


2. Build a Parity Ledger

A parity ledger is a living document that maps each Selenium scenario to its Playwright counterpart and records the equivalence status.

How to use the ledger

  1. Create the entry as soon as a Playwright test is drafted.
  2. Mark “Expected Differences” for any intentional change (e.g., using Playwright’s expect(page).toHaveURL(url) instead of Selenium’s assertEquals(url, expectedUrl)).
  3. Collect evidence – Playwright’s built‑in trace (trace.zip) or screenshots are attached to the ledger entry.
  4. Set rollback status – ✅ Ready when the new test has been run side‑by‑side with the old one and the results match the baseline; otherwise keep it ⏳ Pending.

The ledger is an audit trail of the evidence collected; it supports a coverage decision but cannot by itself prove that no behavior was missed.


3. Replace Explicit Waits – Use Playwright’s Actionability & Auto‑Retry

Selenium tests often contain patterns such as:

new WebDriverWait(driver, Duration.ofSeconds(10))
    .until(ExpectedConditions.elementToBeClickable(By.id("submit")));
driver.findElement(By.id("submit")).click();

Playwright’s philosophy is “wait for the right thing automatically”. The equivalent in TypeScript is:

await page.getByRole('button', { name: 'Submit' }).click(); // waits for the locator to satisfy actionability checks

Key points

Important: Auto‑waiting does not guarantee that the UI state matches the business rule. Keep explicit assertions that encode the expected outcome (e.g., “order confirmation number appears”).

References: Playwright documentation on auto-waiting and locators.


4. Preserve Page / Component Abstractions

If your Selenium suite already uses a Page Object Model (POM), you can migrate the structure while moving the implementation to Playwright.

// src/pages/LoginPage.ts
import { Locator, Page } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly username: Locator;
  readonly password: Locator;
  readonly submitBtn: Locator;

  constructor(page: Page) {
    this.page = page;
    this.username = page.getByLabel('Username');
    this.password = page.getByLabel('Password');
    this.submitBtn = page.getByRole('button', { name: 'Login' });
  }

  async login(user: string, pass: string) {
    await this.username.fill(user);
    await this.password.fill(pass);
    await this.submitBtn.click();
  }
}

Keep business assertions in the test files rather than inside page objects. This follows Selenium’s documented Page Object guidance and keeps verification intent visible; Playwright page objects can still encapsulate locators and user-facing operations.


5. Fixture & Browser‑Context Isolation

Playwright’s test runner (@playwright/test) provides built‑in fixtures for browser, context, and page isolation. A minimal playwright.config.ts that defines isolated tests and three browser-engine projects might look like:

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

export default defineConfig({
  testDir: './tests',
  timeout: 30_000,
  expect: { timeout: 5_000 },
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: [['list'], ['html']],
  use: {
    headless: true,
    viewport: { width: 1280, height: 720 },
    ignoreHTTPSErrors: true,
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

Key take‑aways


6. Cross‑Browser Projects & CI Integration

GitHub Actions can run the three Playwright projects in parallel, similar to a Selenium Grid. A concise workflow snippet:

name: Playwright Tests
on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        browser: [chromium, firefox, webkit]
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx playwright install --with-deps ${{ matrix.browser }}
      - run: npx playwright test --project=${{ matrix.browser }}
        env:
          CI: true

The workflow uses an official GitHub Actions matrix to run the configured Playwright projects separately; publish reports and traces as workflow artifacts when the team needs retained evidence.


7. Dual‑Running Old & New Suites

To prove that coverage is unchanged, run both suites on the same commit:

  1. Execute Selenium suite → generate JUnit XML, screenshots, and a failure report.
  2. Execute Playwright suite → generate the same artifacts (Playwright can output JUnit XML via --reporter=junit).
  3. Compare the mapped business intent and expected outcome automatically. Treat pass/fail differences as investigation signals, not proof of equivalence, because timing, data, or environment may differ between runs.

If a discrepancy appears, flag the corresponding parity‑ledger entry for investigation before proceeding.


8. Delta Classification & Flake Budget

When differences surface, classify them:

Define a team-owned flake budget from the current baseline and track it in the ledger. Playwright retries can help classify a test as flaky, but retries must not be used to hide instability; the first-run failure and retry outcome should both remain visible.


9. Phased Cut‑Over & Rollback Criteria

A risk‑averse migration proceeds in stages:

Rollback means re-enabling the preserved Selenium CI job through a reviewed configuration change while the Playwright implementation remains available for diagnosis and correction.


10. Migration QA Checklist


11. Where Automation Helps

Automation does not replace human judgment about what constitutes business correctness; it merely makes the migration evidence reproducible and auditable.


12. Conclusion

Migrating an established Selenium suite to Playwright is not a simple copy‑paste exercise. By inventorying the existing coverage, building a parity ledger, and running both suites side‑by‑side, teams can quantify risk and demonstrate that no behavioral gaps have been introduced. Playwright’s auto‑waiting, robust tracing, and built‑in fixtures simplify test maintenance, but they must be complemented with explicit assertions that capture the true business intent. A phased cut‑over, clear rollback criteria, and a disciplined flake budget keep the migration under control. When executed with this risk-based approach, the transition keeps migration risk visible and gives reviewers reproducible evidence for deciding when each critical journey is ready to cut over.


Review Questions

  1. What three pieces of information should be captured for each Selenium test before migration?
  2. How does Playwright’s auto‑waiting differ from Selenium’s explicit WebDriverWait, and why must assertions still be explicit?
  3. What is the purpose of a parity ledger, and which fields are essential for auditability?
  4. Describe one concrete way to use Playwright’s tracing feature in the migration process.
  5. List two criteria that would trigger a rollback during the phased cut‑over.

Sources