Skip to content

zebbern/claude-code-guide / skills/playwright/playwright-cli

playwright-cli

Unverified

Automates browser interactions for web testing, form filling, screenshots, and data extraction using playwright-cli. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, extract information from web pages, mock network requests, manage browser sessions, or generate test code.

FileKindSize
SKILL.mdskill md9.3 KB
advanced-workflows.mdmarkdown18.3 KB
core-commands.mdmarkdown10.6 KB
device-emulation.mdmarkdown13.1 KB
request-mocking.mdmarkdown10.4 KB
running-custom-code.mdmarkdown14.8 KB
screenshots-and-media.mdmarkdown10.3 KB
session-management.mdmarkdown9.5 KB
storage-and-auth.mdmarkdown11.2 KB
test-generation.mdmarkdown11.1 KB
tracing-and-debugging.mdmarkdown12.1 KB

test-generation.md

View on GitHub
# Test Generation

> **When to use**: Generating Playwright test code from interactive CLI sessions — recording user flows, building test scaffolds, converting manual testing into automated tests.
> **Prerequisites**: [core-commands.md](core-commands.md) for basic CLI usage

## Quick Reference

```bash
# Every CLI action outputs the equivalent Playwright code
playwright-cli open https://example.com/login
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
# Output: await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');

playwright-cli fill e2 "password123"
# Output: await page.getByRole('textbox', { name: 'Password' }).fill('password123');

playwright-cli click e3
# Output: await page.getByRole('button', { name: 'Sign In' }).click();
```

## How It Works

Every action you perform with `playwright-cli` automatically generates the corresponding Playwright TypeScript code in the output. This code uses the same **role-based locators** that Playwright recommends for production tests.

The workflow:

1. **Open a page** → generates `await page.goto(url)`
2. **Take a snapshot** → see element refs and their accessible roles
3. **Interact** → each action generates one line of Playwright code
4. **Collect the code** → assemble generated lines into a complete test

## Recording a Flow

### Example: Login Flow

```bash
playwright-cli open https://example.com/login
# Ran Playwright code:
# await page.goto('https://example.com/login');

playwright-cli snapshot
# Output:
# e1 [textbox "Email"]
# e2 [textbox "Password"]
# e3 [button "Sign In"]
# e4 [link "Forgot password?"]

playwright-cli fill e1 "user@example.com"
# Ran Playwright code:
# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');

playwright-cli fill e2 "password123"
# Ran Playwright code:
# await page.getByRole('textbox', { name: 'Password' }).fill('password123');

playwright-cli click e3
# Ran Playwright code:
# await page.getByRole('button', { name: 'Sign In' }).click();
```

### Assemble into a Test

Collect the generated code and wrap it in a Playwright test:

```typescript
import { test, expect } from "@playwright/test"

test("user can log in", async ({ page }) => {
  await page.goto("https://example.com/login")
  await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")
  await page.getByRole("textbox", { name: "Password" }).fill("password123")
  await page.getByRole("button", { name: "Sign In" }).click()

  // Add assertions (not generated — you add these)
  await expect(page).toHaveURL(/.*dashboard/)
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
})
```

```javascript
const { test, expect } = require("@playwright/test")

test("user can log in", async ({ page }) => {
  await page.goto("https://example.com/login")
  await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")
  await page.getByRole("textbox", { name: "Password" }).fill("password123")
  await page.getByRole("button", { name: "Sign In" }).click()

  await expect(page).toHaveURL(/.*dashboard/)
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
})
```

## Locator Strategies in Generated Code

The generated code uses Playwright's recommended locator hierarchy:

| Priority | Locator Type | Example                                   | When used                    |
| -------- | ------------ | ----------------------------------------- | ---------------------------- |
| 1        | Role-based   | `getByRole('button', { name: 'Submit' })` | Elements with ARIA roles     |
| 2        | Label-based  | `getByLabel('Email')`                     | Form inputs with labels      |
| 3        | Placeholder  | `getByPlaceholder('Search...')`           | Inputs with placeholder text |
| 4        | Text-based   | `getByText('Welcome back')`               | Static text content          |
| 5        | Test ID      | `getByTestId('submit-btn')`               | Elements with `data-testid`  |

These locators are **resilient to markup changes** — they mirror how users perceive the page rather than relying on CSS selectors or XPath.

## Recording Complex Flows

### E-Commerce Checkout

```bash
playwright-cli open https://shop.example.com

# Browse products
playwright-cli snapshot
playwright-cli click e5                # "Add to Cart" button
# await page.getByRole('button', { name: 'Add to Cart' }).click();

playwright-cli click e12               # Cart icon
# await page.getByRole('link', { name: 'Cart' }).click();

playwright-cli snapshot
playwright-cli click e3                # "Proceed to Checkout"
# await page.getByRole('button', { name: 'Proceed to Checkout' }).click();

# Shipping info
playwright-cli snapshot
playwright-cli fill e1 "Jane Doe"
# await page.getByRole('textbox', { name: 'Full Name' }).fill('Jane Doe');
playwright-cli fill e2 "123 Main St"
# await page.getByRole('textbox', { name: 'Address' }).fill('123 Main St');
playwright-cli fill e3 "Springfield"
# await page.getByRole('textbox', { name: 'City' }).fill('Springfield');
playwright-cli select e4 "IL"
# await page.getByRole('combobox', { name: 'State' }).selectOption('IL');
playwright-cli fill e5 "62701"
# await page.getByRole('textbox', { name: 'ZIP Code' }).fill('62701');
playwright-cli click e6               # "Continue to Payment"
```

### Multi-Step Wizard

```bash
playwright-cli open https://example.com/onboarding

# Step 1
playwright-cli snapshot
playwright-cli fill e1 "Acme Corp"
playwright-cli select e2 "technology"
playwright-cli click e3    # Next

# Step 2
playwright-cli snapshot
playwright-cli check e1    # Feature checkbox
playwright-cli check e3    # Another feature
playwright-cli click e5    # Next

# Step 3
playwright-cli snapshot
playwright-cli click e2    # "Complete Setup"
```

### Search with Dynamic Results

```bash
playwright-cli open https://example.com
playwright-cli snapshot

playwright-cli fill e1 "playwright testing"
# await page.getByRole('searchbox', { name: 'Search' }).fill('playwright testing');

playwright-cli press Enter
# await page.keyboard.press('Enter');

playwright-cli snapshot    # See search results — new refs assigned

playwright-cli click e3    # First result
# await page.getByRole('link', { name: 'Getting Started with Playwright' }).click();
```

## Adding Assertions

Generated code captures **actions** but not **assertions**. Always add assertions manually to create meaningful tests.

### Common Assertions to Add

```typescript
// URL changed after navigation
await expect(page).toHaveURL(/.*dashboard/)
await expect(page).toHaveURL("https://example.com/success")

// Element is visible
await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible()
await expect(page.getByText("Order confirmed")).toBeVisible()

// Element contains text
await expect(page.getByTestId("total")).toHaveText("$99.99")
await expect(page.getByRole("alert")).toContainText("saved")

// Element has specific attribute
await expect(page.getByRole("button", { name: "Submit" })).toBeDisabled()
await expect(page.getByRole("checkbox")).toBeChecked()

// Element count
await expect(page.getByRole("listitem")).toHaveCount(5)

// Page title
await expect(page).toHaveTitle(/Dashboard/)

// Screenshot comparison
await expect(page).toHaveScreenshot("checkout.png")
```

### Where to Place Assertions

```typescript
test("complete checkout flow", async ({ page }) => {
  await page.goto("https://shop.example.com/products")

  // Action: Add item to cart
  await page.getByRole("button", { name: "Add to Cart" }).click()

  // Assertion: Cart badge updates
  await expect(page.getByTestId("cart-count")).toHaveText("1")

  // Action: Go to cart
  await page.getByRole("link", { name: "Cart" }).click()

  // Assertion: Correct page
  await expect(page).toHaveURL(/.*cart/)
  await expect(page.getByRole("heading", { name: "Your Cart" })).toBeVisible()

  // Action: Proceed to checkout
  await page.getByRole("button", { name: "Checkout" }).click()

  // Action: Fill shipping
  await page.getByRole("textbox", { name: "Full Name" }).fill("Jane Doe")
  await page.getByRole("textbox", { name: "Address" }).fill("123 Main St")
  await page.getByRole("button", { name: "Place Order" }).click()

  // Assertion: Order confirmed
  await expect(page.getByText("Order confirmed")).toBeVisible()
  await expect(page.getByTestId("order-number")).toBeVisible()
})
```

## Best Practices

### 1. Explore Before Recording

Take a snapshot first to understand the page structure. Don't blindly click — know what elements are available:

```bash
playwright-cli open https://example.com
playwright-cli snapshot
# Review the elements, plan your flow, then start interacting
```

### 2. Use Semantic Locators

The generated code already prefers role-based locators. If you see CSS selectors in generated output, consider filing an issue — role-based locators are more resilient:

```typescript
// Generated (good — semantic, resilient)
await page.getByRole("button", { name: "Submit" }).click()

// Avoid writing manually (fragile — breaks if CSS changes)
await page.locator("#submit-btn").click()
await page.locator(".btn.btn-primary").click()
```

### 3. Keep Tests Focused

One test = one user behavior. Don't record an entire session into a single test:

```typescript
// Good: Focused test
test("user can add item to cart", async ({ page }) => {
  // Just the add-to-cart flow
})

test("user can complete checkout", async ({ page }) => {
  // Just the checkout flow (use auth state to skip login)
})

// Bad: Monolith test
test("user journey", async ({ page }) => {
  // Login + browse + add to cart + checkout + verify email...
})
```

### 4. Parameterize Test Data

Replace hardcoded values from the recording with variables or test data:

```typescript
// Instead of hardcoded values from recording
test("registration", async ({ page }) => {
  const user = {
    name: "Jane Doe",
    email: `test+${Date.now()}@example.com`,
    password: "SecurePass123!",
  }

  await page.goto("/register")
  await page.getByRole("textbox", { name: "Name" }).fill(user.name)
  await page.getByRole("textbox", { name: "Email" }).fill(user.email)
  await page.getByRole("textbox", { name: "Password" }).fill(user.password)
  await page.getByRole("button", { name: "Create Account" }).click()

  await expect(page).toHaveURL(/.*welcome/)
})
```

### 5. Add Wait Strategies for Flaky Steps

If a recorded action depends on async content loading, add explicit waits:

```typescript
// Before clicking a dynamically loaded element
await page.waitForSelector(".results-loaded")
await page.getByRole("link", { name: "First Result" }).click()

// Or use Playwright's auto-waiting (preferred)
await expect(page.getByRole("link", { name: "First Result" })).toBeVisible()
await page.getByRole("link", { name: "First Result" }).click()
```

## Tips

- **Generated code is a starting point** — always review, add assertions, and parameterize before committing to your test suite
- **Re-snapshot after dynamic changes** — refs change when the DOM updates
- **Combine with `state-save`** — record a login flow once, save state, then start all other recordings from the authenticated state
- **Use `--filename` for snapshots** — save before/after snapshots for complex flows to help write assertions later
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexUnverifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexUnverifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall