zebbern/claude-code-guide / skills/playwright/migration
playwright-migration
VerifiedStep-by-step migration guides for moving to Playwright from Cypress or Selenium/WebDriver — command mappings, architecture changes, and incremental adoption strategies.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 751 B |
| from-cypress.md | markdown | 47.4 KB |
| from-selenium.md | markdown | 45.0 KB |
from-cypress.md
View on GitHub# Migrating from Cypress to Playwright
> **When to use**: When converting a Cypress test suite to Playwright. Follow this guide command-by-command, pattern-by-pattern.
## Key Mindset Shifts
Before converting any code, internalize these five differences. They affect every line you write.
### 1. Chains vs async/await
Cypress commands are enqueued and run in a serial chain that _looks_ synchronous but is not. Playwright uses standard `async`/`await` -- real asynchronous JavaScript with no magic scheduling.
```javascript
// Cypress — chain-based, implicitly queued
cy.get(".todo-list li").should("have.length", 3)
cy.get(".todo-list li").first().should("have.text", "Buy milk")
// Playwright — async/await, explicit control flow
const items = page.getByTestId("todo-item")
await expect(items).toHaveCount(3)
await expect(items.first()).toHaveText("Buy milk")
```
**Why it matters**: You can use `if`/`else`, `for` loops, `try`/`catch`, and any JavaScript construct naturally. No `cy.then()` workarounds.
### 2. Automatic retry vs auto-wait
Cypress retries the _entire command chain_ until assertions pass (or time out). Playwright locators are lazy -- they do nothing until you perform an _action_ or _assertion_, at which point Playwright auto-waits for the element to be actionable (visible, enabled, stable).
```javascript
// Cypress — retries cy.get + .should together
cy.get('[data-testid="submit"]').should("be.visible").click()
// Playwright — locator is created instantly; .click() auto-waits for visibility + stability
await page.getByTestId("submit").click()
```
### 3. In-browser vs Node.js
Cypress test code runs _inside_ the browser (same origin). Playwright runs in Node.js and controls browsers over the Chrome DevTools Protocol or equivalent. This means:
- Playwright can open multiple tabs, windows, and even multiple browsers in a single test.
- Playwright has native access to the file system, databases, and APIs from test code -- no `cy.task()` needed.
- You cannot access `window` or `document` directly; use `page.evaluate()` when you need browser-side code.
### 4. One tab vs multi-tab, multi-browser
Cypress is limited to a single browser tab and a single browser. Playwright can control multiple pages, multiple browser contexts (each with isolated cookies/storage), and even multiple browser types (Chromium, Firefox, WebKit) in the same test run.
### 5. Custom commands vs fixtures
Cypress extends via `Cypress.Commands.add()` -- a global mutable registry. Playwright uses `test.extend()` fixtures with dependency injection, guaranteed teardown, and type safety. Fixtures are dramatically more powerful.
## Command Mapping Table
| Cypress | Playwright | Notes |
| ------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `cy.visit('/path')` | `await page.goto('/path')` | Use `baseURL` in config to avoid full URLs |
| `cy.get('selector')` | `page.locator('selector')` | Prefer `page.getByRole()` over CSS selectors |
| `cy.get('[data-testid="x"]')` | `page.getByTestId('x')` | Configure `testIdAttribute` in playwright.config |
| `cy.contains('text')` | `page.getByText('text')` | For buttons/links, prefer `page.getByRole('button', { name: 'text' })` |
| `cy.find('child')` | `locator.locator('child')` | Chain locators to scope within a parent |
| `cy.get('sel').click()` | `await locator.click()` | Auto-waits for element to be actionable |
| `cy.get('sel').type('text')` | `await locator.fill('text')` | `fill()` sets value instantly. Use `locator.pressSequentially('text')` for character-by-character typing |
| `cy.get('sel').clear()` | `await locator.clear()` | Or `await locator.fill('')` |
| `cy.get('select').select('val')` | `await locator.selectOption('val')` | Accepts value, label, or `{ index }` |
| `cy.get('input').check()` | `await locator.check()` | No-op if already checked |
| `cy.get('input').uncheck()` | `await locator.uncheck()` | No-op if already unchecked |
| `cy.get('sel').should('be.visible')` | `await expect(locator).toBeVisible()` | Web-first assertion; auto-retries |
| `cy.get('sel').should('have.text', 'x')` | `await expect(locator).toHaveText('x')` | Also accepts regex: `.toHaveText(/pattern/)` |
| `cy.get('sel').should('contain', 'x')` | `await expect(locator).toContainText('x')` | Substring match |
| `cy.get('sel').should('have.length', 3)` | `await expect(locator).toHaveCount(3)` | Counts matching elements |
| `cy.get('sel').should('have.value', 'x')` | `await expect(locator).toHaveValue('x')` | Input/textarea value |
| `cy.get('sel').should('have.attr', 'href', '/x')` | `await expect(locator).toHaveAttribute('href', '/x')` | Any HTML attribute |
| `cy.get('sel').should('have.class', 'active')` | `await expect(locator).toHaveClass(/active/)` | Regex for partial class match |
| `cy.get('sel').should('be.disabled')` | `await expect(locator).toBeDisabled()` | |
| `cy.get('sel').should('not.exist')` | `await expect(locator).toBeHidden()` | Or `.toHaveCount(0)` for truly absent elements |
| `cy.intercept('GET', '/api/**', { body })` | `await page.route('/api/**', route => route.fulfill({ body }))` | Set up _before_ the action that triggers the request |
| `cy.intercept('POST', '/api/save').as('save')` | `const resp = page.waitForResponse('**/api/save')` | Start _before_ the action, `await` after |
| `cy.wait('@save')` | `await resp` | Returns `Response` object with `.json()`, `.status()` |
| `cy.fixture('users.json')` | Fixtures via `test.extend()` or direct `import`/`require` | See Example 5 below |
| `cy.request('GET', '/api/users')` | `const resp = await request.get('/api/users')` | Use the `request` fixture or `APIRequestContext` |
| `cy.request('POST', '/api/users', body)` | `const resp = await request.post('/api/users', { data: body })` | |
| `cy.wrap(value)` | No equivalent needed | Just use the value directly with `await` |
| `cy.then((result) => { ... })` | `const result = await ...` | Standard async/await replaces `.then()` chains |
| `Cypress.env('API_KEY')` | `process.env.API_KEY` | Or use `use: {}` in playwright.config for test-specific values |
| `Cypress.Commands.add('login', fn)` | Custom fixture via `test.extend()` | See Example 5 below |
| `cy.clock()` / `cy.tick(1000)` | `await page.clock.install()` / `await page.clock.fastForward(1000)` | `page.clock` API for full time control |
| `cy.screenshot('name')` | `await page.screenshot({ path: 'name.png' })` | Auto-captured on failure when `screenshot: 'on'` in config |
| `cy.viewport(1280, 720)` | `await page.setViewportSize({ width: 1280, height: 720 })` | Prefer setting in config or per-project |
| `beforeEach(() => { cy.visit('/') })` | `test.beforeEach(async ({ page }) => { await page.goto('/') })` | Destructure `page` from fixtures |
| `cy.scrollTo('bottom')` | `await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))` | Actions auto-scroll to elements; manual scroll is rarely needed |
| `cy.focused()` | `page.locator(':focus')` | Or assert: `await expect(locator).toBeFocused()` |
| `cy.go('back')` | `await page.goBack()` | Also `page.goForward()` |
| `cy.reload()` | `await page.reload()` | |
| `cy.title()` | `await expect(page).toHaveTitle('text')` | Web-first assertion on page title |
| `cy.url()` | `await expect(page).toHaveURL('/path')` | Accepts string or regex |
| `cy.getCookie('name')` | `const cookies = await context.cookies()` | Filter by name from the array |
| `cy.setCookie('name', 'val')` | `await context.addCookies([{ name, value, url }])` | |
| `cy.clearCookies()` | `await context.clearCookies()` | |
## Before/After Examples
### Example 1: Basic Navigation and Assertion
**Cypress**
```javascript
describe("Homepage", () => {
beforeEach(() => {
cy.visit("/")
})
it("displays the welcome heading", () => {
cy.get("h1").should("have.text", "Welcome to Acme")
cy.get('[data-testid="hero-subtitle"]').should("be.visible")
cy.url().should("include", "/")
})
it("navigates to the about page", () => {
cy.contains("About").click()
cy.url().should("include", "/about")
cy.get("h1").should("have.text", "About Us")
})
})
```
**Playwright (TypeScript)**
```typescript
import { test, expect } from "@playwright/test"
test.describe("Homepage", () => {
test.beforeEach(async ({ page }) => {
await page.goto("/")
})
test("displays the welcome heading", async ({ page }) => {
await expect(page.getByRole("heading", { level: 1 })).toHaveText("Welcome to Acme")
await expect(page.getByTestId("hero-subtitle")).toBeVisible()
await expect(page).toHaveURL("/")
})
test("navigates to the about page", async ({ page }) => {
await page.getByRole("link", { name: "About" }).click()
await expect(page).toHaveURL(/\/about/)
await expect(page.getByRole("heading", { level: 1 })).toHaveText("About Us")
})
})
```
**Playwright (JavaScript)**
```javascript
const { test, expect } = require("@playwright/test")
test.describe("Homepage", () => {
test.beforeEach(async ({ page }) => {
await page.goto("/")
})
test("displays the welcome heading", async ({ page }) => {
await expect(page.getByRole("heading", { level: 1 })).toHaveText("Welcome to Acme")
await expect(page.getByTestId("hero-subtitle")).toBeVisible()
await expect(page).toHaveURL("/")
})
test("navigates to the about page", async ({ page }) => {
await page.getByRole("link", { name: "About" }).click()
await expect(page).toHaveURL(/\/about/)
await expect(page.getByRole("heading", { level: 1 })).toHaveText("About Us")
})
})
```
**Key changes**: `cy.get('h1')` becomes `page.getByRole('heading', { level: 1 })` for resilience. `cy.contains('About').click()` becomes `page.getByRole('link', { name: 'About' }).click()` to assert the element is actually a link. `cy.url().should('include', ...)` becomes `await expect(page).toHaveURL(...)` which auto-retries.
---
### Example 2: Form Interaction
**Cypress**
```javascript
describe("Registration Form", () => {
it("submits a valid form", () => {
cy.visit("/register")
cy.get("#first-name").type("Jane")
cy.get("#last-name").type("Doe")
cy.get("#email").type("jane@example.com")
cy.get("#password").type("s3cure!Pass")
cy.get("#country").select("United States")
cy.get("#terms").check()
cy.get("form").submit()
cy.get(".success-message").should("be.visible")
cy.get(".success-message").should("contain", "Welcome, Jane")
})
it("shows validation errors for empty fields", () => {
cy.visit("/register")
cy.get('[type="submit"]').click()
cy.get(".error").should("have.length", 4)
cy.get("#first-name").should("have.attr", "aria-invalid", "true")
})
})
```
**Playwright (TypeScript)**
```typescript
import { test, expect } from "@playwright/test"
test.describe("Registration Form", () => {
test("submits a valid form", async ({ page }) => {
await page.goto("/register")
await page.getByLabel("First name").fill("Jane")
await page.getByLabel("Last name").fill("Doe")
await page.getByLabel("Email").fill("jane@example.com")
await page.getByLabel("Password").fill("s3cure!Pass")
await page.getByLabel("Country").selectOption("United States")
await page.getByLabel("I agree to the terms").check()
await page.getByRole("button", { name: "Register" }).click()
const successMessage = page.getByText("Welcome, Jane")
await expect(successMessage).toBeVisible()
})
test("shows validation errors for empty fields", async ({ page }) => {
await page.goto("/register")
await page.getByRole("button", { name: "Register" }).click()
await expect(page.getByRole("alert")).toHaveCount(4)
await expect(page.getByLabel("First name")).toHaveAttribute("aria-invalid", "true")
})
})
```
**Playwright (JavaScript)**
```javascript
const { test, expect } = require("@playwright/test")
test.describe("Registration Form", () => {
test("submits a valid form", async ({ page }) => {
await page.goto("/register")
await page.getByLabel("First name").fill("Jane")
await page.getByLabel("Last name").fill("Doe")
await page.getByLabel("Email").fill("jane@example.com")
await page.getByLabel("Password").fill("s3cure!Pass")
await page.getByLabel("Country").selectOption("United States")
await page.getByLabel("I agree to the terms").check()
await page.getByRole("button", { name: "Register" }).click()
const successMessage = page.getByText("Welcome, Jane")
await expect(successMessage).toBeVisible()
})
test("shows validation errors for empty fields", async ({ page }) => {
await page.goto("/register")
await page.getByRole("button", { name: "Register" }).click()
await expect(page.getByRole("alert")).toHaveCount(4)
await expect(page.getByLabel("First name")).toHaveAttribute("aria-invalid", "true")
})
})
```
**Key changes**: `cy.get('#id').type()` becomes `page.getByLabel('Label').fill()`. No IDs needed -- labels are resilient and accessible. `fill()` replaces `type()` and sets the value instantly. `cy.get('form').submit()` becomes an explicit button click, matching real user behavior.
---
### Example 3: Network Mocking
**Cypress**
```javascript
describe("Product List", () => {
it("displays products from the API", () => {
cy.intercept("GET", "/api/products", {
statusCode: 200,
body: [
{ id: 1, name: "Widget", price: 9.99 },
{ id: 2, name: "Gadget", price: 24.99 },
],
}).as("getProducts")
cy.visit("/products")
cy.wait("@getProducts")
cy.get('[data-testid="product-card"]').should("have.length", 2)
cy.get('[data-testid="product-card"]').first().should("contain", "Widget")
})
it("shows error state when API fails", () => {
cy.intercept("GET", "/api/products", {
statusCode: 500,
body: { error: "Internal server error" },
}).as("getProducts")
cy.visit("/products")
cy.wait("@getProducts")
cy.get('[data-testid="error-message"]').should("contain", "Something went wrong")
})
it("submits a new product", () => {
cy.intercept("POST", "/api/products", {
statusCode: 201,
body: { id: 3, name: "Doohickey", price: 14.99 },
}).as("createProduct")
cy.visit("/products/new")
cy.get("#product-name").type("Doohickey")
cy.get("#product-price").type("14.99")
cy.get('button[type="submit"]').click()
cy.wait("@createProduct").its("request.body").should("deep.equal", {
name: "Doohickey",
price: 14.99,
})
})
})
```
**Playwright (TypeScript)**
```typescript
import { test, expect } from "@playwright/test"
test.describe("Product List", () => {
test("displays products from the API", async ({ page }) => {
await page.route("**/api/products", (route) =>
route.fulfill({
status: 200,
contentType: "application/json",
body: JSON.stringify([
{ id: 1, name: "Widget", price: 9.99 },
{ id: 2, name: "Gadget", price: 24.99 },
]),
})
)
await page.goto("/products")
await expect(page.getByTestId("product-card")).toHaveCount(2)
await expect(page.getByTestId("product-card").first()).toContainText("Widget")
})
test("shows error state when API fails", async ({ page }) => {
await page.route("**/api/products", (route) =>
route.fulfill({
status: 500,
contentType: "application/json",
body: JSON.stringify({ error: "Internal server error" }),
})
)
await page.goto("/products")
await expect(page.getByTestId("error-message")).toContainText("Something went wrong")
})
test("submits a new product", async ({ page }) => {
// Set up route mock AND capture the request
let requestBody: unknown
await page.route("**/api/products", (route) => {
requestBody = route.request().postDataJSON()
return route.fulfill({
status: 201,
contentType: "application/json",
body: JSON.stringify({ id: 3, name: "Doohickey", price: 14.99 }),
})
})
await page.goto("/products/new")
await page.getByLabel("Product name").fill("Doohickey")
await page.getByLabel("Price").fill("14.99")
await page.getByRole("button", { name: "Create product" }).click()
// Assert on the captured request body
expect(requestBody).toEqual({ name: "Doohickey", price: 14.99 })
})
})
```
**Playwright (JavaScript)**
```javascript
const { test, expect } = require("@playwright/test")
test.describe("Product List", () => {
test("displays products from the API", async ({ page }) => {
await page.route("**/api/products", (route) =>
route.fulfill({
status: 200,
contentType: "application/json",
body: JSON.stringify([
{ id: 1, name: "Widget", price: 9.99 },
{ id: 2, name: "Gadget", price: 24.99 },
]),
})
)
await page.goto("/products")
await expect(page.getByTestId("product-card")).toHaveCount(2)
await expect(page.getByTestId("product-card").first()).toContainText("Widget")
})
test("shows error state when API fails", async ({ page }) => {
await page.route("**/api/products", (route) =>
route.fulfill({
status: 500,
contentType: "application/json",
body: JSON.stringify({ error: "Internal server error" }),
})
)
await page.goto("/products")
await expect(page.getByTestId("error-message")).toContainText("Something went wrong")
})
test("submits a new product", async ({ page }) => {
let requestBody
await page.route("**/api/products", (route) => {
requestBody = route.request().postDataJSON()
return route.fulfill({
status: 201,
contentType: "application/json",
body: JSON.stringify({ id: 3, name: "Doohickey", price: 14.99 }),
})
})
await page.goto("/products/new")
await page.getByLabel("Product name").fill("Doohickey")
await page.getByLabel("Price").fill("14.99")
await page.getByRole("button", { name: "Create product" }).click()
expect(requestBody).toEqual({ name: "Doohickey", price: 14.99 })
})
})
```
**Key changes**: `cy.intercept()` becomes `page.route()`. Set up routes _before_ the action that triggers the request. No `cy.wait('@alias')` needed -- Playwright auto-waits for the UI to update. To assert on request bodies, capture them in the route handler. For waiting on a specific response, use `page.waitForResponse()`.
---
### Example 4: Authentication
**Cypress**
```javascript
// cypress/support/commands.js
Cypress.Commands.add("login", (email, password) => {
cy.session([email, password], () => {
cy.visit("/login")
cy.get("#email").type(email)
cy.get("#password").type(password)
cy.get('button[type="submit"]').click()
cy.url().should("include", "/dashboard")
})
})
// cypress/e2e/dashboard.cy.js
describe("Dashboard", () => {
beforeEach(() => {
cy.login("admin@example.com", "password123")
cy.visit("/dashboard")
})
it("shows admin content", () => {
cy.get('[data-testid="admin-panel"]').should("be.visible")
})
})
```
**Playwright (TypeScript)** -- using `storageState` for session reuse (recommended)
```typescript
// auth.setup.ts — runs once, saves auth state to a file
import { test as setup, expect } from "@playwright/test"
import path from "path"
const authFile = path.join(__dirname, "../.auth/user.json")
setup("authenticate", async ({ page }) => {
await page.goto("/login")
await page.getByLabel("Email").fill("admin@example.com")
await page.getByLabel("Password").fill("password123")
await page.getByRole("button", { name: "Sign in" }).click()
await page.waitForURL("/dashboard")
// Save signed-in state to file
await page.context().storageState({ path: authFile })
})
```
```typescript
// playwright.config.ts
import { defineConfig } from "@playwright/test"
export default defineConfig({
projects: [
// Setup project — runs auth first
{ name: "setup", testMatch: /.*\.setup\.ts/ },
// All tests reuse the saved auth state
{
name: "chromium",
dependencies: ["setup"],
use: {
storageState: ".auth/user.json",
},
},
],
})
```
```typescript
// dashboard.spec.ts — already authenticated, no login code needed
import { test, expect } from "@playwright/test"
test.describe("Dashboard", () => {
test("shows admin content", async ({ page }) => {
await page.goto("/dashboard")
await expect(page.getByTestId("admin-panel")).toBeVisible()
})
})
```
**Playwright (JavaScript)** -- using `storageState` for session reuse (recommended)
```javascript
// auth.setup.js
const { test: setup, expect } = require("@playwright/test")
const path = require("path")
const authFile = path.join(__dirname, "../.auth/user.json")
setup("authenticate", async ({ page }) => {
await page.goto("/login")
await page.getByLabel("Email").fill("admin@example.com")
await page.getByLabel("Password").fill("password123")
await page.getByRole("button", { name: "Sign in" }).click()
await page.waitForURL("/dashboard")
await page.context().storageState({ path: authFile })
})
```
```javascript
// playwright.config.js
const { defineConfig } = require("@playwright/test")
module.exports = defineConfig({
projects: [
{ name: "setup", testMatch: /.*\.setup\.js/ },
{
name: "chromium",
dependencies: ["setup"],
use: {
storageState: ".auth/user.json",
},
},
],
})
```
```javascript
// dashboard.spec.js
const { test, expect } = require("@playwright/test")
test.describe("Dashboard", () => {
test("shows admin content", async ({ page }) => {
await page.goto("/dashboard")
await expect(page.getByTestId("admin-panel")).toBeVisible()
})
})
```
**Key changes**: Cypress `cy.session()` becomes Playwright's `storageState`. Auth runs once as a setup project, saves cookies/localStorage to a JSON file, and all test projects reuse it. Tests never touch login flows -- they start authenticated. Add `.auth/` to `.gitignore`.
---
### Example 5: Custom Commands to Fixtures
**Cypress** -- custom commands are globally registered
```javascript
// cypress/support/commands.js
Cypress.Commands.add("createTodo", (text) => {
cy.get('[data-testid="new-todo"]').type(`${text}{enter}`)
})
Cypress.Commands.add("getTodos", () => {
return cy.get('[data-testid="todo-item"]')
})
Cypress.Commands.add("apiCreateUser", (userData) => {
return cy.request("POST", "/api/users", userData)
})
// cypress/e2e/todos.cy.js
describe("Todos", () => {
beforeEach(() => {
cy.visit("/todos")
})
it("adds and verifies todos", () => {
cy.createTodo("Buy milk")
cy.createTodo("Walk dog")
cy.getTodos().should("have.length", 2)
})
})
```
**Playwright (TypeScript)** -- fixtures replace custom commands
```typescript
// fixtures.ts
import { test as base, expect } from "@playwright/test"
// Define the types for your custom fixtures
type TodoFixtures = {
todosPage: TodosPage
apiHelper: ApiHelper
}
class TodosPage {
constructor(private page: import("@playwright/test").Page) {}
async createTodo(text: string) {
await this.page.getByTestId("new-todo").fill(text)
await this.page.getByTestId("new-todo").press("Enter")
}
get todos() {
return this.page.getByTestId("todo-item")
}
}
class ApiHelper {
constructor(private request: import("@playwright/test").APIRequestContext) {}
async createUser(userData: { name: string; email: string }) {
const response = await this.request.post("/api/users", { data: userData })
return response.json()
}
}
export const test = base.extend<TodoFixtures>({
todosPage: async ({ page }, use) => {
await page.goto("/todos")
await use(new TodosPage(page))
},
apiHelper: async ({ request }, use) => {
await use(new ApiHelper(request))
},
})
export { expect }
```
```typescript
// todos.spec.ts
import { test, expect } from "./fixtures"
test("adds and verifies todos", async ({ todosPage }) => {
await todosPage.createTodo("Buy milk")
await todosPage.createTodo("Walk dog")
await expect(todosPage.todos).toHaveCount(2)
})
test("creates a user via API then verifies in UI", async ({ todosPage, apiHelper, page }) => {
const user = await apiHelper.createUser({ name: "Jane", email: "jane@test.com" })
await page.goto(`/users/${user.id}`)
await expect(page.getByRole("heading")).toHaveText("Jane")
})
```
**Playwright (JavaScript)** -- fixtures replace custom commands
```javascript
// fixtures.js
const { test: base, expect } = require("@playwright/test")
class TodosPage {
constructor(page) {
this.page = page
}
async createTodo(text) {
await this.page.getByTestId("new-todo").fill(text)
await this.page.getByTestId("new-todo").press("Enter")
}
get todos() {
return this.page.getByTestId("todo-item")
}
}
class ApiHelper {
constructor(request) {
this.request = request
}
async createUser(userData) {
const response = await this.request.post("/api/users", { data: userData })
return response.json()
}
}
const test = base.extend({
todosPage: async ({ page }, use) => {
await page.goto("/todos")
await use(new TodosPage(page))
},
apiHelper: async ({ request }, use) => {
await use(new ApiHelper(request))
},
})
module.exports = { test, expect }
```
```javascript
// todos.spec.js
const { test, expect } = require("./fixtures")
test("adds and verifies todos", async ({ todosPage }) => {
await todosPage.createTodo("Buy milk")
await todosPage.createTodo("Walk dog")
await expect(todosPage.todos).toHaveCount(2)
})
```
**Key changes**: Every Cypress custom command maps to either a method on a page object (for UI interactions) or a helper class (for API calls), exposed via `test.extend()` fixtures. Fixtures provide dependency injection, type safety, and guaranteed teardown. Tests declare what they need by name in the function signature.
## Migration Steps
A battle-tested process for migrating an existing Cypress test suite to Playwright.
### Step 1: Install Playwright alongside Cypress
Do not remove Cypress yet. Run both frameworks in parallel during migration.
```bash
npm init playwright@latest
# Accept defaults: TypeScript (or JavaScript), tests folder, GitHub Actions CI, install browsers
```
This creates `playwright.config.ts`, a `tests/` folder, and installs browsers.
### Step 2: Configure playwright.config to match your Cypress setup
Map your `cypress.config.js` settings to `playwright.config.ts`:
**TypeScript**
```typescript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests", // Your new Playwright test directory
timeout: 30_000, // Cypress default is 4s per command; Playwright uses 30s per test
expect: { timeout: 5_000 }, // Assertion auto-retry timeout (like Cypress defaultCommandTimeout)
fullyParallel: true, // Cypress runs serially by default; Playwright parallelizes
retries: process.env.CI ? 2 : 0,
reporter: process.env.CI ? "html" : "list",
use: {
baseURL: "http://localhost:3000", // Matches Cypress baseUrl
trace: "on-first-retry",
screenshot: "only-on-failure",
},
projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
// Add more browsers — something Cypress cannot do:
{ name: "firefox", use: { ...devices["Desktop Firefox"] } },
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
],
// Equivalent to Cypress's devServer config
webServer: {
command: "npm run dev",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
},
})
```
**JavaScript**
```javascript
// playwright.config.js
const { defineConfig, devices } = require("@playwright/test")
module.exports = defineConfig({
testDir: "./tests",
timeout: 30_000,
expect: { timeout: 5_000 },
fullyParallel: true,
retries: process.env.CI ? 2 : 0,
reporter: process.env.CI ? "html" : "list",
use: {
baseURL: "http://localhost:3000",
trace: "on-first-retry",
screenshot: "only-on-failure",
},
projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
{ name: "firefox", use: { ...devices["Desktop Firefox"] } },
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
],
webServer: {
command: "npm run dev",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
},
})
```
### Step 3: Convert custom commands to fixtures
Before migrating individual tests, convert your `cypress/support/commands.js` into Playwright fixtures. This gives every migrated test immediate access to the same helpers.
1. Identify each custom command in `cypress/support/commands.js` and `cypress/support/e2e.js`.
2. Group UI commands into page object classes.
3. Group API commands into API helper classes.
4. Expose them via `test.extend()` in a shared `fixtures.ts` (or `fixtures.js`).
5. See Example 5 above for the complete pattern.
### Step 4: Set up authentication
Convert `cy.session()` or login-in-`beforeEach` patterns to Playwright's `storageState`:
1. Create an `auth.setup.ts` file (see Example 4 above).
2. Add a `setup` project to `playwright.config.ts`.
3. Add `.auth/` to `.gitignore`.
4. Remove all login code from individual test files.
### Step 5: Migrate tests file by file
Start with the simplest spec files. For each file:
1. Create the corresponding Playwright test file in `tests/`.
2. Convert using the Command Mapping Table above.
3. Replace CSS selectors with semantic locators (`getByRole`, `getByLabel`, `getByText`).
4. Run the Playwright test in headed mode: `npx playwright test tests/my-test.spec.ts --headed`.
5. Once passing, mark the Cypress spec as migrated (move to an `archived/` folder or delete).
Prioritize by value: migrate your critical path tests first (auth, checkout, core CRUD).
### Step 6: Convert cy.intercept patterns to page.route
For each intercepted route:
1. Move `page.route()` calls _before_ the action that triggers the request (Playwright routes must be set up in advance).
2. Replace `cy.wait('@alias')` with either `page.waitForResponse()` (when you need the response) or just let auto-waiting assertions handle it (when you only care about UI updates).
3. For request body assertions, capture the body inside the `page.route()` handler.
### Step 7: Convert Cypress plugins to Node.js code
Cypress plugins (in `cypress/plugins/` or `setupNodeEvents` in config) run in a separate Node.js process and communicate with test code via `cy.task()`. In Playwright, your test code already runs in Node.js, so:
- Database seeding: call directly from fixtures or `globalSetup`.
- File operations: use `fs` directly in test code or fixtures.
- Environment setup: use `globalSetup` / `globalTeardown` in config.
- Custom task logic: move into fixture setup/teardown.
### Step 8: Update CI pipeline
Replace the Cypress CI step with Playwright:
```yaml
# GitHub Actions example
- name: Install Playwright Browsers
run: npx playwright install --with-deps
- name: Run Playwright tests
run: npx playwright test
- name: Upload Playwright Report
uses: actions/upload-artifact@v4
if: ${{ !cancelled() }}
with:
name: playwright-report
path: playwright-report/
retention-days: 30
```
### Step 9: Remove Cypress
Once all tests are migrated and passing in CI:
```bash
npm uninstall cypress
rm -rf cypress/
rm cypress.config.js # or .ts
# Remove any Cypress-related CI config
# Remove Cypress-related entries from .eslintrc if present
```
## Common Gotchas
Things that look similar between Cypress and Playwright but behave differently.
### 1. Locators are lazy, not retrying
Cypress `cy.get()` immediately starts querying the DOM and retries until the chain passes. Playwright `page.locator()` creates a locator object instantly -- it does _nothing_ until you call an action (`.click()`, `.fill()`) or assertion (`expect(locator).toBeVisible()`).
```typescript
// This does NOT query the DOM — it just creates a locator reference
const button = page.getByRole("button", { name: "Submit" })
// This is where the actual DOM query + waiting happens
await button.click()
```
This means storing locators in variables is free and encouraged. Reuse them across multiple actions and assertions.
### 2. Assertions are separate from locators
Cypress chains assertions onto commands: `cy.get('x').should('be.visible').and('have.text', 'y')`. Playwright uses separate `expect()` calls for each assertion:
```typescript
// Cypress — chained assertions
cy.get(".card").should("be.visible").and("have.text", "Hello").and("have.class", "active")
// Playwright — separate expect() calls, each auto-retries independently
const card = page.locator(".card")
await expect(card).toBeVisible()
await expect(card).toHaveText("Hello")
await expect(card).toHaveClass(/active/)
```
### 3. fill() vs type() — the speed difference
`cy.type('text')` sends keystrokes one at a time, triggering `keydown`, `keypress`, `input`, and `keyup` events for each character. Playwright's `locator.fill('text')` clears the field and sets the value in one shot, only triggering `input` and `change` events.
Use `fill()` by default. Use `pressSequentially()` only when character-by-character input matters (autocomplete, search-as-you-type, input masks):
```typescript
// Default — fast, sets value directly
await page.getByLabel("Name").fill("Jane Doe")
// Character-by-character — only when keystroke events matter
await page.getByLabel("Search").pressSequentially("play", { delay: 100 })
```
### 4. Auto-scroll behavior
Cypress auto-scrolls to bring elements into view before _any_ interaction. Playwright auto-scrolls into view only when performing _actions_ (click, fill, check). Assertions like `toBeVisible()` do **not** scroll -- they check if the element is visible in its current position.
If you need to scroll before asserting visibility:
```typescript
// Scroll into view first, then assert
await page.getByText("Footer content").scrollIntoViewIfNeeded()
await expect(page.getByText("Footer content")).toBeVisible()
```
### 5. No implicit cy.wrap() equivalent
Cypress `cy.wrap()` brings a non-Cypress value into the command chain. Playwright does not need this because you are already in async/await land:
```typescript
// Cypress
const value = 42
cy.wrap(value).should("equal", 42)
// Playwright — just use the value
const value = 42
expect(value).toBe(42)
```
### 6. Route setup timing
Cypress `cy.intercept()` can be called at any point and will match the _next_ matching request. Playwright `page.route()` must be set up _before_ the action that triggers the request. A common mistake is setting up the route _after_ `page.goto()` -- by then the request may have already fired.
```typescript
// WRONG — route set up too late
await page.goto("/products")
await page.route("**/api/products", (route) => route.fulfill({ body: "[]" }))
// CORRECT — route set up before navigation
await page.route("**/api/products", (route) => route.fulfill({ body: "[]" }))
await page.goto("/products")
```
### 7. Cypress subject vs Playwright return values
Cypress commands yield a "subject" to the next command in the chain. Playwright actions return `void` (or a `Promise<void>`). If you need a value _from_ the browser, use `evaluate`, `textContent`, `inputValue`, etc.:
```typescript
// Cypress — subject chaining
cy.get("#counter")
.invoke("text")
.then((text) => {
const count = parseInt(text, 10)
expect(count).to.be.greaterThan(0)
})
// Playwright — direct return values
const text = await page.locator("#counter").textContent()
const count = parseInt(text!, 10)
expect(count).toBeGreaterThan(0)
// Better: use a web-first assertion when possible
await expect(page.locator("#counter")).not.toHaveText("0")
```
### 8. Cypress plugins vs Playwright global setup
Cypress uses `setupNodeEvents` (or the legacy `plugins/index.js`) for Node.js-side operations, accessed via `cy.task()`. Since Playwright tests already run in Node.js, you do not need a separate plugin layer:
```typescript
// Cypress — plugin pattern
// cypress.config.js
setupNodeEvents(on) {
on('task', {
seedDatabase(data) { return db.seed(data); },
});
}
// Test: cy.task('seedDatabase', testData);
// Playwright — direct call in fixture
export const test = base.extend({
seededDatabase: async ({}, use) => {
await db.seed(testData);
await use();
await db.cleanup();
},
});
```
### 9. cy.within() vs locator scoping
Cypress `cy.within()` scopes all subsequent commands to a container element. Playwright scopes by chaining locators:
```typescript
// Cypress
cy.get('[data-testid="signup-form"]').within(() => {
cy.get('input[name="email"]').type("user@test.com")
cy.get("button").click()
})
// Playwright — chain locators for scoping
const form = page.getByTestId("signup-form")
await form.getByLabel("Email").fill("user@test.com")
await form.getByRole("button", { name: "Sign up" }).click()
```
### 10. Test isolation differences
Cypress clears cookies, localStorage, and sessionStorage between tests by default but shares the same browser instance. Playwright creates a _fresh browser context_ for each test -- complete isolation of cookies, storage, cache, and service workers. This means:
- You never need to manually clear state between tests.
- You cannot "leak" state from one test to another (which can mask or cause flakiness in Cypress).
- Worker-scoped fixtures are the way to share expensive resources across tests.
## What's Better in Playwright
Features that have no Cypress equivalent and make Playwright the stronger choice for production test suites.
### Multi-browser testing out of the box
Test on Chromium, Firefox, and WebKit (Safari) in a single config. No plugins, no paid dashboard.
```typescript
// playwright.config.ts — three browsers, zero extra setup
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 5'] } },
{ name: 'mobile-safari', use: { ...devices['iPhone 13'] } },
],
```
### Multi-tab and multi-window testing
Test popups, OAuth flows, new tabs, and multi-window interactions:
```typescript
// Handle a popup window (e.g., OAuth)
const popupPromise = page.waitForEvent("popup")
await page.getByRole("button", { name: "Sign in with Google" }).click()
const popup = await popupPromise
await popup.getByLabel("Email").fill("user@gmail.com")
```
### Multi-user testing in a single test
Test collaboration features with multiple independent browser contexts:
```typescript
test("two users can collaborate", async ({ browser }) => {
const aliceContext = await browser.newContext({ storageState: "auth/alice.json" })
const bobContext = await browser.newContext({ storageState: "auth/bob.json" })
const alicePage = await aliceContext.newPage()
const bobPage = await bobContext.newPage()
await alicePage.goto("/doc/shared")
await bobPage.goto("/doc/shared")
await alicePage.getByRole("textbox").fill("Hello from Alice")
await expect(bobPage.getByText("Hello from Alice")).toBeVisible()
await aliceContext.close()
await bobContext.close()
})
```
### Native API testing
Test APIs without a browser, using the same runner and assertion library:
```typescript
test("API returns user list", async ({ request }) => {
const response = await request.get("/api/users")
expect(response.ok()).toBeTruthy()
const users = await response.json()
expect(users).toHaveLength(3)
expect(users[0]).toHaveProperty("email")
})
```
### Parallel execution with sharding
Run tests across multiple machines with zero configuration:
```bash
# Split across 4 CI machines
npx playwright test --shard=1/4 # Machine 1
npx playwright test --shard=2/4 # Machine 2
npx playwright test --shard=3/4 # Machine 3
npx playwright test --shard=4/4 # Machine 4
```
### Trace viewer
Playwright traces capture a complete record of test execution: DOM snapshots, network requests, console logs, and action screenshots. Open with:
```bash
npx playwright show-trace trace.zip
```
This replaces Cypress's time-travel debugger with a more detailed, offline-capable tool.
### Component testing with framework support
Test React, Vue, Svelte, and Solid components in real browsers (not jsdom):
```typescript
import { test, expect } from '@playwright/experimental-ct-react';
import { Button } from './Button';
test('button renders with label', async ({ mount }) => {
const component = await mount(<Button label="Click me" />);
await expect(component).toContainText('Click me');
await component.click();
});
```
### Built-in code generation
Generate test code by interacting with your app:
```bash
npx playwright codegen http://localhost:3000
```
Records your clicks, fills, and assertions, and outputs Playwright test code. Use it as a starting point, then refine locators to use `getByRole`.
### Clock control
Full control over `Date`, `setTimeout`, `setInterval`, and `requestAnimationFrame`:
```typescript
test("shows expired badge after timeout", async ({ page }) => {
await page.clock.install({ time: new Date("2024-01-01T00:00:00Z") })
await page.goto("/offers")
await page.clock.fastForward("24:00:00")
await expect(page.getByText("Offer expired")).toBeVisible()
})
```
### Network request interception with HAR files
Record and replay network traffic from HAR files for deterministic tests:
```typescript
// Record all network traffic
await page.routeFromHAR("tests/fixtures/products.har", {
url: "**/api/**",
update: true, // Set to true once to record, then false to replay
})
```
## Related
- [core/locators.md](../core/locators.md) -- locator strategy for Playwright (replaces Cypress `cy.get()` patterns)
- [core/fixtures-and-hooks.md](../core/fixtures-and-hooks.md) -- deep dive on fixtures (replaces Cypress custom commands)
- [core/assertions-and-waiting.md](../core/assertions-and-waiting.md) -- web-first assertions (replaces Cypress `should` chains)
- [core/configuration.md](../core/configuration.md) -- playwright.config setup
- [core/authentication.md](../core/authentication.md) -- auth patterns (replaces Cypress `cy.session()`)
- [core/network-mocking.md](../core/network-mocking.md) -- route mocking (replaces Cypress `cy.intercept()`)
- [ci/ci-github-actions.md](../ci/ci-github-actions.md) -- CI setup for Playwright
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |