Skip to content

testdino-hq/playwright-skill / migration

playwright-migration

Verified

Step-by-step migration guides for moving to Playwright from Cypress or Selenium/WebDriver — command mappings, architecture changes, and incremental adoption strategies.

FileKindSize
SKILL.mdskill md645 B
from-cypress.mdmarkdown42.2 KB
from-selenium.mdmarkdown38.6 KB

from-selenium.md

View on GitHub
# Migrating from Selenium to Playwright

> **When to use**: When converting a Selenium/WebDriver test suite to Playwright. Covers Java/Python/C# Selenium idioms mapped to TypeScript and JavaScript Playwright equivalents.
> **Prerequisites**: [core/locators.md](../core/locators.md), [core/assertions-and-waiting.md](../core/assertions-and-waiting.md)

## Key Mindset Shifts

Before translating any code, internalize these six changes. They are not syntax swaps -- they are fundamental differences in how Playwright works.

### 1. No More Explicit Waits

Selenium requires `WebDriverWait` and `ExpectedConditions` on nearly every interaction. Playwright auto-waits on every action (`click`, `fill`, `check`, `selectOption`) and every web-first assertion (`expect(locator).toBeVisible()`). Delete all your waits. They are not needed.

```
Selenium:  WebDriverWait + ExpectedConditions.visibilityOfElementLocated(...)
Playwright: nothing — auto-waiting is built into every action and assertion
```

### 2. No WebDriver Protocol Overhead

Selenium sends every command over the WebDriver (W3C) HTTP protocol -- each click, each find, each assertion is a round-trip HTTP request. Playwright communicates over CDP (Chromium) or its own protocol to its patched Firefox and WebKit builds. This is a persistent bidirectional connection, not request-response. Tests are faster by default.

### 3. No Driver Management

Selenium requires matching browser drivers (`chromedriver`, `geckodriver`) to browser versions. Version mismatches are a constant source of CI failures (Selenium Manager, bundled since Selenium 4.6, automates downloads but still resolves drivers at runtime). Playwright bundles browser binaries. One command installs everything:

```bash
npx playwright install
```

No `WebDriverManager`. No `chromedriver` path. No version matrix.

### 4. No Implicit vs Explicit Wait Confusion

Selenium has implicit waits (global, apply to all `findElement` calls), explicit waits (`WebDriverWait`), and `Thread.sleep()` / `time.sleep()`. Teams mix these, creating unpredictable timing behavior. Playwright has one mechanism: auto-waiting. Every action waits for the element to be actionable. Every web-first assertion retries until timeout. There is nothing to configure.

### 5. Locators Are Lazy and Auto-Retry

In Selenium, `findElement()` immediately queries the DOM and returns a `WebElement` reference. If the DOM changes, that reference is stale and throws `StaleElementReferenceException`. In Playwright, `page.locator()` returns a lazy locator that re-queries the DOM on every action. There is no stale element. There is no `StaleElementReferenceException`. Ever.

### 6. Built-In Test Runner

Selenium is a browser automation library, not a test framework. You need JUnit, TestNG, pytest, or Mocha on top. Playwright Test is a full test runner with parallel execution, retries, fixtures, HTML reports, trace viewer, and UI mode. No assembly required.

## API Mapping Table

Every Selenium API and its direct Playwright equivalent. The "Notes" column calls out behavior differences.

### Navigation

| Selenium WebDriver | Playwright | Notes |
|---|---|---|
| `driver.get(url)` | `await page.goto(url)` | Playwright waits for `load` event by default; configurable via `waitUntil` |
| `driver.navigate().to(url)` | `await page.goto(url)` | Same as above |
| `driver.navigate().back()` | `await page.goBack()` | Waits for navigation to complete |
| `driver.navigate().forward()` | `await page.goForward()` | Waits for navigation to complete |
| `driver.navigate().refresh()` | `await page.reload()` | Waits for `load` event |
| `driver.getCurrentUrl()` | `page.url()` | Synchronous in Playwright -- no await needed |
| `driver.getTitle()` | `await page.title()` | Or use `await expect(page).toHaveTitle('...')` for assertion |

### Element Location

| Selenium WebDriver | Playwright | Notes |
|---|---|---|
| `driver.findElement(By.id("x"))` | `page.locator('#x')` or `page.getByTestId('x')` | Prefer `getByRole()` or `getByTestId()` over ID selectors |
| `driver.findElement(By.css("x"))` | `page.locator('x')` | CSS selectors work, but prefer semantic locators |
| `driver.findElement(By.xpath("x"))` | `page.locator('xpath=x')` | Works but avoid XPath; use `getByRole()`, `getByLabel()`, `getByText()` |
| `driver.findElement(By.name("x"))` | `page.locator('[name="x"]')` | Or `page.getByLabel()` if the field has a label |
| `driver.findElement(By.linkText("x"))` | `page.getByRole('link', { name: 'x' })` | Role-based is more resilient |
| `driver.findElement(By.partialLinkText("x"))` | `page.getByRole('link', { name: /x/ })` | Regex for partial match |
| `driver.findElement(By.className("x"))` | `page.locator('.x')` | Class selectors are fragile; prefer semantic locators |
| `driver.findElement(By.tagName("x"))` | `page.locator('x')` | Rarely useful alone; combine with role or text |
| `driver.findElements(By.css("x"))` | `await page.locator('x').all()` | Returns array of locators; or use `toHaveCount()` to assert count |

### Element Interaction

| Selenium WebDriver | Playwright | Notes |
|---|---|---|
| `element.click()` | `await locator.click()` | Auto-waits for element to be visible, stable, enabled, and unobscured |
| `element.sendKeys("text")` | `await locator.fill("text")` | **Behavior change**: `fill()` clears existing text first, then sets the value. Use `pressSequentially()` to type character by character. |
| `element.sendKeys(Keys.ENTER)` | `await locator.press('Enter')` | Or `await page.keyboard.press('Enter')` |
| `element.clear()` | `await locator.clear()` | Or `await locator.fill('')` |
| `element.submit()` | `await locator.press('Enter')` | No direct equivalent; click the submit button or press Enter |
| `new Select(element).selectByVisibleText("x")` | `await locator.selectOption({ label: 'x' })` | Also supports `{ value: 'x' }` and `{ index: 0 }` |
| `element.isDisplayed()` | `await expect(locator).toBeVisible()` | Use assertion form -- it auto-retries. `locator.isVisible()` does not retry. |
| `element.isEnabled()` | `await expect(locator).toBeEnabled()` | Use assertion form for reliability |
| `element.isSelected()` | `await expect(locator).toBeChecked()` | For checkboxes and radio buttons |
| `element.getText()` | `await locator.textContent()` | Or prefer `await expect(locator).toHaveText('...')` which auto-retries |
| `element.getAttribute("x")` | `await locator.getAttribute('x')` | Or `await expect(locator).toHaveAttribute('x', 'value')` |
| `element.getCssValue("x")` | `await expect(locator).toHaveCSS('x', 'value')` | Use assertion form; computed values only |

### Waits and Conditions

| Selenium WebDriver | Playwright | Notes |
|---|---|---|
| `WebDriverWait(driver, 10).until(...)` | Not needed | Playwright auto-waits on all actions and assertions |
| `ExpectedConditions.visibilityOfElementLocated(...)` | `await expect(locator).toBeVisible()` | Built into every action; use assertion only when you need to verify visibility explicitly |
| `ExpectedConditions.elementToBeClickable(...)` | Not needed | `click()` auto-waits for clickability |
| `ExpectedConditions.presenceOfElementLocated(...)` | `await expect(locator).toBeAttached()` | Rarely needed; most actions wait for attachment automatically |
| `ExpectedConditions.invisibilityOfElementLocated(...)` | `await expect(locator).not.toBeVisible()` | Auto-retries until element disappears |
| `ExpectedConditions.textToBePresentInElement(...)` | `await expect(locator).toHaveText('...')` | Auto-retries until text matches |
| `ExpectedConditions.titleIs("x")` | `await expect(page).toHaveTitle('x')` | Auto-retries |
| `ExpectedConditions.urlContains("x")` | `await expect(page).toHaveURL(/x/)` | Or `await page.waitForURL('**/x')` |
| `ExpectedConditions.alertIsPresent()` | `page.on('dialog', ...)` or `page.waitForEvent('dialog')` | Register handler before the action that triggers the dialog |
| `Thread.sleep(5000)` / `time.sleep(5)` | Never | Delete it. Use auto-waiting assertions instead. |
| `driver.manage().timeouts().implicitlyWait(10)` | Not needed | No implicit waits in Playwright -- auto-waiting handles everything |

### Frames and Windows

| Selenium WebDriver | Playwright | Notes |
|---|---|---|
| `driver.switchTo().frame("name")` | `page.frameLocator('iframe[name="name"]')` | No context switching; chain locators directly into the frame |
| `driver.switchTo().frame(element)` | `page.frameLocator('iframe#id')` | Target the iframe by any CSS selector |
| `driver.switchTo().defaultContent()` | Not needed | No frame switching in Playwright; each `frameLocator` is scoped |
| `driver.switchTo().parentFrame()` | Not needed | No frame switching to undo |
| `driver.switchTo().window(handle)` | `context.pages()` | Access all pages in the context by index |
| `driver.getWindowHandle()` | Not needed | Use `page` references directly |
| `driver.getWindowHandles()` | `context.pages()` | Returns array of all open pages |
| New window/tab opened by click | `page.waitForEvent('popup')` | Register before the click; returns the new `Page` object |

### Browser and Context

| Selenium WebDriver | Playwright | Notes |
|---|---|---|
| `driver.manage().window().setSize(w, h)` | `await page.setViewportSize({ width: w, height: h })` | Sets the viewport, not the OS window |
| `driver.manage().window().maximize()` | Configure in `playwright.config` `use.viewport` | Or pass `--headed` with large viewport |
| `driver.manage().addCookie(cookie)` | `await context.addCookies([cookie])` | Takes an array; operates on the browser context |
| `driver.manage().getCookieNamed("x")` | `await context.cookies()` then filter | Returns all cookies; filter in JS |
| `driver.manage().deleteAllCookies()` | `await context.clearCookies()` | Clears all cookies in the context |
| `driver.executeScript("return ...")` | `await page.evaluate(() => { ... })` | Full access to browser JS context; supports return values |
| `driver.executeAsyncScript(...)` | `await page.evaluate(async () => { ... })` | `evaluate` supports async functions natively |
| `driver.getScreenshotAs(OutputType.FILE)` | `await page.screenshot({ path: 'shot.png' })` | Also supports `fullPage: true`, element screenshots via `locator.screenshot()` |
| `driver.quit()` | Handled automatically | Playwright Test manages browser lifecycle. No manual cleanup. |

### Actions Class

| Selenium WebDriver | Playwright | Notes |
|---|---|---|
| `new Actions(driver).moveToElement(el).perform()` | `await locator.hover()` | Single method, auto-waits |
| `new Actions(driver).doubleClick(el).perform()` | `await locator.dblclick()` | Single method, auto-waits |
| `new Actions(driver).contextClick(el).perform()` | `await locator.click({ button: 'right' })` | Right-click option |
| `new Actions(driver).dragAndDrop(src, tgt).perform()` | `await source.dragTo(target)` | Both are locators |
| `new Actions(driver).keyDown(Keys.SHIFT).click(el).keyUp(Keys.SHIFT).perform()` | `await locator.click({ modifiers: ['Shift'] })` | Modifier keys as option |
| `new Actions(driver).sendKeys(Keys.chord(Keys.CONTROL, "a")).perform()` | `await page.keyboard.press('Control+a')` | Keyboard API for global shortcuts |
| `new Actions(driver).moveByOffset(x, y).perform()` | `await page.mouse.move(x, y)` | Raw mouse API for canvas/map interactions |

## Before/After Examples

### Example 1: Login Test

The most common Selenium test. Notice the complete absence of explicit waits in the Playwright version.

**Selenium (Java)**
```java
import org.openqa.selenium.*;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.WebDriverWait;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.junit.jupiter.api.*;

public class LoginTest {
    WebDriver driver;

    @BeforeEach
    void setUp() {
        System.setProperty("webdriver.chrome.driver", "/path/to/chromedriver");
        driver = new ChromeDriver();
        driver.manage().window().maximize();
        driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));
    }

    @AfterEach
    void tearDown() {
        if (driver != null) driver.quit();
    }

    @Test
    void userCanLogIn() {
        driver.get("https://myapp.com/login");

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

        WebElement emailField = wait.until(
            ExpectedConditions.visibilityOfElementLocated(By.id("email"))
        );
        emailField.clear();
        emailField.sendKeys("user@example.com");

        WebElement passwordField = driver.findElement(By.id("password"));
        passwordField.clear();
        passwordField.sendKeys("s3cure!Pass");

        WebElement loginButton = wait.until(
            ExpectedConditions.elementToBeClickable(By.cssSelector("button[type='submit']"))
        );
        loginButton.click();

        wait.until(ExpectedConditions.urlContains("/dashboard"));

        WebElement heading = wait.until(
            ExpectedConditions.visibilityOfElementLocated(By.tagName("h1"))
        );
        Assertions.assertEquals("Dashboard", heading.getText());
    }
}
```

**Playwright (TypeScript)**
```typescript
import { test, expect } from '@playwright/test';

test('user can log in', async ({ page }) => {
  await page.goto('/login');

  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('s3cure!Pass');
  await page.getByRole('button', { name: 'Sign In' }).click();

  await page.waitForURL('/dashboard');
  await expect(page.getByRole('heading', { level: 1 })).toHaveText('Dashboard');
});
```

**Playwright (JavaScript)**
```javascript
const { test, expect } = require('@playwright/test');

test('user can log in', async ({ page }) => {
  await page.goto('/login');

  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('s3cure!Pass');
  await page.getByRole('button', { name: 'Sign In' }).click();

  await page.waitForURL('/dashboard');
  await expect(page.getByRole('heading', { level: 1 })).toHaveText('Dashboard');
});
```

**What changed**: 45 lines of Java with explicit waits, driver management, and element references became 9 lines of Playwright. No setup, no teardown, no waits, no driver path. The `fill()` call replaces `clear()` + `sendKeys()`. Semantic locators (`getByLabel`, `getByRole`) replace brittle `By.id` and `By.cssSelector`.

---

### Example 2: Search and Verify Results

Demonstrates replacing `findElements()`, explicit waits for result count, and text assertions.

**Selenium (Java)**
```java
@Test
void searchReturnsResults() {
    driver.get("https://myapp.com/products");

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

    WebElement searchBox = wait.until(
        ExpectedConditions.visibilityOfElementLocated(By.cssSelector("input[placeholder='Search products']"))
    );
    searchBox.clear();
    searchBox.sendKeys("wireless headphones");
    searchBox.sendKeys(Keys.ENTER);

    wait.until(ExpectedConditions.numberOfElementsToBeMoreThan(
        By.cssSelector(".product-card"), 0
    ));

    List<WebElement> results = driver.findElements(By.cssSelector(".product-card"));
    Assertions.assertTrue(results.size() >= 3);

    String firstTitle = results.get(0).findElement(By.cssSelector(".product-title")).getText();
    Assertions.assertTrue(firstTitle.toLowerCase().contains("wireless"));
}
```

**Playwright (TypeScript)**
```typescript
import { test, expect } from '@playwright/test';

test('search returns results', async ({ page }) => {
  await page.goto('/products');

  await page.getByPlaceholder('Search products').fill('wireless headphones');
  await page.getByPlaceholder('Search products').press('Enter');

  const results = page.getByTestId('product-card');
  await expect(results).toHaveCount(3, { timeout: 10_000 });

  await expect(results.first().getByTestId('product-title')).toContainText(/wireless/i);
});
```

**Playwright (JavaScript)**
```javascript
const { test, expect } = require('@playwright/test');

test('search returns results', async ({ page }) => {
  await page.goto('/products');

  await page.getByPlaceholder('Search products').fill('wireless headphones');
  await page.getByPlaceholder('Search products').press('Enter');

  const results = page.getByTestId('product-card');
  await expect(results).toHaveCount(3, { timeout: 10_000 });

  await expect(results.first().getByTestId('product-title')).toContainText(/wireless/i);
});
```

**What changed**: No `WebDriverWait` for element visibility. No `clear()` before `sendKeys()`. No `findElements()` returning a stale list. The Playwright `toHaveCount()` auto-retries until the results appear. The regex assertion on `toContainText` replaces manual `getText()` + `toLowerCase()` + `contains()`.

---

### Example 3: Working with Iframes

Selenium's frame switching is stateful and error-prone. Playwright's `frameLocator` is scoped and stateless.

**Selenium (Java)**
```java
@Test
void fillPaymentFormInIframe() {
    driver.get("https://myapp.com/checkout");

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

    // Switch into the payment iframe
    wait.until(ExpectedConditions.frameToBeAvailableAndSwitchToIt(
        By.cssSelector("iframe#payment-frame")
    ));

    // Now inside the iframe context
    WebElement cardNumber = wait.until(
        ExpectedConditions.visibilityOfElementLocated(By.id("card-number"))
    );
    cardNumber.sendKeys("4242424242424242");

    driver.findElement(By.id("expiry")).sendKeys("12/28");
    driver.findElement(By.id("cvc")).sendKeys("123");

    // Switch back to main content before interacting with the page
    driver.switchTo().defaultContent();

    driver.findElement(By.id("place-order")).click();

    wait.until(ExpectedConditions.visibilityOfElementLocated(
        By.cssSelector(".confirmation-message")
    ));
}
```

**Playwright (TypeScript)**
```typescript
import { test, expect } from '@playwright/test';

test('fill payment form in iframe', async ({ page }) => {
  await page.goto('/checkout');

  // No switching — just scope into the frame
  const paymentFrame = page.frameLocator('#payment-frame');
  await paymentFrame.getByLabel('Card number').fill('4242424242424242');
  await paymentFrame.getByLabel('Expiry').fill('12/28');
  await paymentFrame.getByLabel('CVC').fill('123');

  // No switching back — main page locators still work
  await page.getByRole('button', { name: 'Place order' }).click();

  await expect(page.getByText('Order confirmed')).toBeVisible();
});
```

**Playwright (JavaScript)**
```javascript
const { test, expect } = require('@playwright/test');

test('fill payment form in iframe', async ({ page }) => {
  await page.goto('/checkout');

  const paymentFrame = page.frameLocator('#payment-frame');
  await paymentFrame.getByLabel('Card number').fill('4242424242424242');
  await paymentFrame.getByLabel('Expiry').fill('12/28');
  await paymentFrame.getByLabel('CVC').fill('123');

  await page.getByRole('button', { name: 'Place order' }).click();

  await expect(page.getByText('Order confirmed')).toBeVisible();
});
```

**What changed**: No `switchTo().frame()`. No `switchTo().defaultContent()`. No risk of forgetting to switch back. Playwright's `frameLocator` scopes into the iframe without changing the driver's global state. You can interact with the main page and the iframe in any order.

---

### Example 4: Handling Popups and New Windows

Selenium window handle management is notoriously fragile. Playwright makes it declarative.

**Selenium (Java)**
```java
@Test
void handlePopupWindow() {
    driver.get("https://myapp.com/settings");

    String originalWindow = driver.getWindowHandle();

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

    driver.findElement(By.linkText("Connect OAuth Provider")).click();

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

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

    // Interact with the popup
    wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("authorize-btn")));
    driver.findElement(By.id("authorize-btn")).click();

    // Wait for popup to close and switch back
    wait.until(ExpectedConditions.numberOfWindowsToBe(1));
    driver.switchTo().window(originalWindow);

    wait.until(ExpectedConditions.visibilityOfElementLocated(
        By.cssSelector(".connection-status.success")
    ));
}
```

**Playwright (TypeScript)**
```typescript
import { test, expect } from '@playwright/test';

test('handle popup window', async ({ page }) => {
  await page.goto('/settings');

  // Register listener BEFORE the click that opens the popup
  const popupPromise = page.waitForEvent('popup');
  await page.getByRole('link', { name: 'Connect OAuth Provider' }).click();
  const popup = await popupPromise;

  // Interact with the popup — it's just another Page object
  await popup.getByRole('button', { name: 'Authorize' }).click();

  // Popup closes automatically; verify result on original page
  await expect(page.getByText('Connected successfully')).toBeVisible();
});
```

**Playwright (JavaScript)**
```javascript
const { test, expect } = require('@playwright/test');

test('handle popup window', async ({ page }) => {
  await page.goto('/settings');

  const popupPromise = page.waitForEvent('popup');
  await page.getByRole('link', { name: 'Connect OAuth Provider' }).click();
  const popup = await popupPromise;

  await popup.getByRole('button', { name: 'Authorize' }).click();

  await expect(page.getByText('Connected successfully')).toBeVisible();
});
```

**What changed**: No window handle iteration. No `switchTo()`. No tracking original vs new window. The popup is a `Page` object you interact with directly. When it closes, you just continue using the original `page`. The `waitForEvent('popup')` pattern is declarative and race-condition-free.

---

### Example 5: Drag and Drop with Actions

Selenium's `Actions` class requires chaining and `perform()`. Playwright has direct methods.

**Selenium (Java)**
```java
@Test
void dragAndDropTask() {
    driver.get("https://myapp.com/kanban");

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

    WebElement sourceCard = wait.until(
        ExpectedConditions.visibilityOfElementLocated(
            By.xpath("//div[@class='card' and contains(text(),'Fix login bug')]")
        )
    );
    WebElement targetColumn = driver.findElement(
        By.xpath("//div[@class='column' and .//h2[text()='Done']]")
    );

    Actions actions = new Actions(driver);
    actions.dragAndDrop(sourceCard, targetColumn).perform();

    // Verify the card moved
    WebElement doneColumn = driver.findElement(
        By.xpath("//div[@class='column' and .//h2[text()='Done']]")
    );
    WebElement movedCard = doneColumn.findElement(
        By.xpath(".//div[@class='card' and contains(text(),'Fix login bug')]")
    );
    Assertions.assertTrue(movedCard.isDisplayed());
}
```

**Playwright (TypeScript)**
```typescript
import { test, expect } from '@playwright/test';

test('drag and drop task to done column', async ({ page }) => {
  await page.goto('/kanban');

  const card = page.getByText('Fix login bug');
  const doneColumn = page.getByRole('heading', { name: 'Done' }).locator('..');

  await card.dragTo(doneColumn);

  // Verify card is now inside the Done column
  await expect(doneColumn.getByText('Fix login bug')).toBeVisible();
});
```

**Playwright (JavaScript)**
```javascript
const { test, expect } = require('@playwright/test');

test('drag and drop task to done column', async ({ page }) => {
  await page.goto('/kanban');

  const card = page.getByText('Fix login bug');
  const doneColumn = page.getByRole('heading', { name: 'Done' }).locator('..');

  await card.dragTo(doneColumn);

  await expect(doneColumn.getByText('Fix login bug')).toBeVisible();
});
```

**What changed**: No `Actions` class. No `perform()`. No XPath for finding elements. `dragTo()` is a single method call on a locator. The verification uses scoped locators instead of XPath ancestor traversal.

## Migration Steps

A practical, ordered checklist for converting a Selenium suite to Playwright.

### Step 1: Set Up Playwright Alongside Selenium

Do not rip out Selenium on day one. Run both in parallel.

```bash
# Install Playwright in your existing project
npm init playwright@latest

# This creates:
# - playwright.config.ts (or .js)
# - tests/ directory
# - package.json dependencies
```

Configure `baseURL` in `playwright.config` to match your Selenium target:

**TypeScript**
```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests-playwright', // separate from Selenium tests
  use: {
    baseURL: 'https://staging.myapp.com',
    trace: 'on-first-retry',
  },
  retries: process.env.CI ? 2 : 0,
});
```

**JavaScript**
```javascript
// playwright.config.js
const { defineConfig } = require('@playwright/test');

module.exports = defineConfig({
  testDir: './tests-playwright',
  use: {
    baseURL: 'https://staging.myapp.com',
    trace: 'on-first-retry',
  },
  retries: process.env.CI ? 2 : 0,
});
```

### Step 2: Convert Page Objects First

If you have Selenium page objects, convert them to Playwright page objects. The pattern is similar but simpler.

**Selenium Page Object (Java)**
```java
public class LoginPage {
    private WebDriver driver;
    private WebDriverWait wait;

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

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

    public void login(String email, String password) {
        wait.until(ExpectedConditions.visibilityOfElementLocated(emailField));
        driver.findElement(emailField).clear();
        driver.findElement(emailField).sendKeys(email);
        driver.findElement(passwordField).clear();
        driver.findElement(passwordField).sendKeys(password);
        driver.findElement(loginButton).click();
    }

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

**Playwright Page Object (TypeScript)**
```typescript
// page-objects/login-page.ts
import { type Page, type Locator, expect } from '@playwright/test';

export class LoginPage {
  private readonly emailField: Locator;
  private readonly passwordField: Locator;
  private readonly loginButton: Locator;
  private readonly errorMessage: Locator;

  constructor(private readonly page: Page) {
    this.emailField = page.getByLabel('Email');
    this.passwordField = page.getByLabel('Password');
    this.loginButton = page.getByRole('button', { name: 'Sign In' });
    this.errorMessage = page.getByRole('alert');
  }

  async login(email: string, password: string) {
    await this.emailField.fill(email);
    await this.passwordField.fill(password);
    await this.loginButton.click();
  }

  async expectError(message: string) {
    await expect(this.errorMessage).toHaveText(message);
  }
}
```

**Playwright Page Object (JavaScript)**
```javascript
// page-objects/login-page.js
const { expect } = require('@playwright/test');

class LoginPage {
  constructor(page) {
    this.page = page;
    this.emailField = page.getByLabel('Email');
    this.passwordField = page.getByLabel('Password');
    this.loginButton = page.getByRole('button', { name: 'Sign In' });
    this.errorMessage = page.getByRole('alert');
  }

  async login(email, password) {
    await this.emailField.fill(email);
    await this.passwordField.fill(password);
    await this.loginButton.click();
  }

  async expectError(message) {
    await expect(this.errorMessage).toHaveText(message);
  }
}

module.exports = { LoginPage };
```

Key differences in page objects:
- Locators are defined in the constructor, not as `By` objects -- they are lazy and never go stale
- No `WebDriverWait` anywhere
- No `clear()` before `fill()`
- Assertions can live inside the page object (`expectError`) because they auto-retry

### Step 3: Convert Tests by Priority

Start with your most valuable and most flaky tests. Convert them in order:

1. **Smoke tests** -- highest value, run on every deploy
2. **Flaky tests** -- Playwright's auto-waiting eliminates most flakiness
3. **Slow tests** -- Playwright's parallelism and faster protocol make these faster
4. **Everything else** -- bulk conversion of the remaining suite

For each test, apply the API mapping table above. The mechanical translation is:
1. Remove all `WebDriverWait` and `ExpectedConditions`
2. Replace `findElement(By.xxx)` with semantic locators (`getByRole`, `getByLabel`, `getByText`)
3. Replace `sendKeys` with `fill` (or `pressSequentially` for character-by-character input)
4. Replace `Assert` / `assertEquals` with `expect(locator).toHaveText()` / `toBeVisible()` / etc.
5. Remove `setUp` and `tearDown` -- Playwright Test handles browser lifecycle
6. Remove `Thread.sleep()` / `time.sleep()` entirely

### Step 4: Replace Test Infrastructure

| Selenium Infrastructure | Playwright Equivalent |
|---|---|
| Selenium Grid / Hub | `npx playwright test --shard=1/4` (built-in sharding) |
| BrowserStack / SauceLabs | Often unnecessary; Playwright runs 3 browsers locally. Use for Safari on CI if needed. |
| WebDriverManager | `npx playwright install` (one command, all browsers) |
| TestNG XML suites | `playwright.config` `projects` array |
| JUnit @Tag / pytest marks | `test.describe()` grouping + `--grep` filtering |
| Allure / ExtentReports | Built-in HTML reporter (`npx playwright show-report`) + trace viewer |
| Screenshot on failure | Built-in: `use: { screenshot: 'only-on-failure' }` |
| Video recording | Built-in: `use: { video: 'on-first-retry' }` |

### Step 5: Remove Selenium

Once all tests pass in Playwright and have run green in CI for at least two weeks:

1. Delete Selenium test files
2. Remove Selenium dependencies (`selenium-webdriver`, `chromedriver`, `geckodriver`)
3. Remove Selenium Grid infrastructure
4. Update CI pipelines to run only Playwright
5. Remove `setUp` / `tearDown` boilerplate classes

## Common Gotchas

### Gotcha 1: `findElement` Throws, `locator()` Does Not

In Selenium, `driver.findElement(By.id("missing"))` throws `NoSuchElementException` immediately. In Playwright, `page.locator('#missing')` returns a locator object without querying the DOM. It only throws when you perform an action on it and the element does not appear within the timeout.

```typescript
// This does NOT throw — locators are lazy
const missing = page.locator('#does-not-exist');

// This throws after timeout — because the action waits and the element never appears
await missing.click(); // TimeoutError after actionTimeout
```

**Impact**: If your Selenium tests use try-catch around `findElement` to check element existence, replace with assertions:

```typescript
// Selenium pattern (do not replicate)
// try { driver.findElement(By.id("error")); fail(); } catch (NoSuchElementException e) { /* expected */ }

// Playwright equivalent
await expect(page.locator('#error')).not.toBeVisible();
```

### Gotcha 2: `sendKeys` Appends, `fill` Replaces

Selenium's `sendKeys("text")` appends to the existing value. If the field already contains "hello" and you `sendKeys("world")`, you get "helloworld". Playwright's `fill("text")` clears the field first, then sets the value. You get "text".

```typescript
// Selenium behavior: appends
// element.sendKeys("world"); // field: "helloworld"

// Playwright behavior: replaces
await locator.fill('world'); // field: "world"

// To replicate Selenium's append behavior:
await locator.pressSequentially('world'); // types each character, appending to existing value
```

### Gotcha 3: No StaleElementReferenceException

In Selenium, storing a `WebElement` reference and using it after the DOM changes throws `StaleElementReferenceException`. This is the single most common source of Selenium test flakiness.

```java
// Selenium — this can throw StaleElementReferenceException
WebElement button = driver.findElement(By.id("submit"));
// ... some action causes the DOM to re-render ...
button.click(); // BOOM — StaleElementReferenceException
```

In Playwright, locators re-query the DOM on every action. Store locators freely.

```typescript
// Playwright — this always works
const button = page.getByRole('button', { name: 'Submit' });
// ... some action causes the DOM to re-render ...
await button.click(); // Works — re-queries the DOM automatically
```

### Gotcha 4: No Global Driver State

Selenium has a single `driver` instance with global state: the current frame, the current window, implicit wait timeout. Calling `switchTo().frame()` changes state for all subsequent calls. Forgetting to `switchTo().defaultContent()` causes every following `findElement` to fail.

Playwright has no global state. `page.frameLocator()` returns a scoped object. `context.pages()` gives you all pages. Nothing changes the "current" context.

```typescript
// Selenium mental model: "Where am I now?"
// driver.switchTo().frame("payment"); // I'm in the payment frame
// driver.findElement(...);            // This looks in the payment frame
// driver.switchTo().defaultContent(); // Now I'm back in the main page
// ... forget this line and everything breaks

// Playwright mental model: "I always say exactly where I'm looking"
const paymentFrame = page.frameLocator('#payment');
await paymentFrame.getByLabel('Card').fill('4242...'); // scoped to frame
await page.getByRole('button', { name: 'Pay' }).click(); // main page — no switching
```

### Gotcha 5: Assertions Must Be Awaited

In Selenium (Java), assertions are synchronous: `assertEquals("Dashboard", heading.getText())`. In Playwright, web-first assertions are async and must be awaited:

```typescript
// WRONG — assertion runs detached, test may pass before it resolves
expect(page.getByRole('heading')).toHaveText('Dashboard'); // missing await!

// CORRECT
await expect(page.getByRole('heading')).toHaveText('Dashboard');
```

Missing `await` is the number one Playwright beginner mistake. Your linter should flag this. Enable `@typescript-eslint/no-floating-promises` or the Playwright ESLint plugin.

### Gotcha 6: Parallel by Default

Selenium tests typically run sequentially (one browser, one thread). Playwright Test runs test files in parallel by default. This means:

- Tests must be isolated -- no shared state between test files
- Each test gets its own browser context (fresh cookies, storage, session)
- Database fixtures must not collide between parallel tests

If your Selenium suite depends on execution order, you must fix that before migrating. See [core/test-organization.md](../core/test-organization.md) for isolation strategies.

## What's Better in Playwright

These are not just syntax differences. These are capabilities that Selenium does not have.

### Auto-Waiting Everywhere

Every action, every assertion, every navigation auto-waits. You write zero wait code. This alone eliminates 60-80% of Selenium test flakiness.

### Trace Viewer

When a test fails in CI, Playwright captures a trace: screenshots at every step, DOM snapshots, network requests, console logs. Open it with `npx playwright show-report` and step through the exact failure. Selenium has nothing comparable.

```typescript
// playwright.config.ts — enable traces on first retry
export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});
```

### Built-In Parallel Execution

Playwright Test runs test files in parallel with zero configuration. No Selenium Grid. No TestNG parallel suite XML. No pytest-xdist.

```bash
# Run all tests in parallel (default)
npx playwright test

# Shard across CI machines
npx playwright test --shard=1/4  # machine 1
npx playwright test --shard=2/4  # machine 2
```

### Multiple Browsers, One API

The same test runs on Chromium, Firefox, and WebKit without code changes. Configure in `playwright.config`:

```typescript
export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});
```

Selenium requires separate driver binaries and often browser-specific workarounds.

### Network Interception

Playwright can intercept, modify, and mock network requests natively. Selenium cannot.

```typescript
// Mock an API response — impossible in Selenium
await page.route('**/api/users', (route) => {
  route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify([{ name: 'Mock User' }]),
  });
});
```

### Browser Context Isolation

Each test gets a fresh browser context (like an incognito window). Cookies, localStorage, and sessions are isolated between tests without restarting the browser. Selenium requires `driver.quit()` and `new ChromeDriver()` for true isolation.

### Test Fixtures

Playwright's fixture system provides dependency injection for test setup and teardown. Fixtures guarantee cleanup even if a test crashes. Selenium relies on `@BeforeEach` / `@AfterEach` which skip teardown on hard failures.

```typescript
// Custom fixture for authenticated user — reusable across all tests
import { test as base } from '@playwright/test';

export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill('admin@example.com');
    await page.getByLabel('Password').fill('password');
    await page.getByRole('button', { name: 'Sign In' }).click();
    await page.waitForURL('/dashboard');
    await use(page);
    // Cleanup runs automatically, even on crash
  },
});
```

### Codegen

Generate tests by recording browser interactions:

```bash
npx playwright codegen https://myapp.com
```

This opens a browser and records your clicks, fills, and navigations as Playwright test code. No equivalent exists in Selenium.

### UI Mode

Debug tests visually with time-travel:

```bash
npx playwright test --ui
```

Step forward and backward through each action, see the DOM state, network requests, and console logs at every point. Selenium's closest equivalent is manual `Thread.sleep()` and screenshot debugging.

## Related

- [core/locators.md](../core/locators.md) -- locator strategy priority and patterns
- [core/assertions-and-waiting.md](../core/assertions-and-waiting.md) -- auto-waiting and web-first assertions in depth
- [core/configuration.md](../core/configuration.md) -- setting up `playwright.config`
- [pom/page-object-model.md](../pom/page-object-model.md) -- page object patterns for Playwright
- [core/fixtures-and-hooks.md](../core/fixtures-and-hooks.md) -- fixtures system for test setup and isolation
- [core/test-organization.md](../core/test-organization.md) -- organizing tests for parallel execution
- [migration/from-cypress.md](from-cypress.md) -- migrating from Cypress instead
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall