Playwright CLI

Playwright CLI is the command-line toolset for Microsoft Playwright - the modern browser automation framework. It lets you run tests, record tests via codegen, debug with inspector, view traces, manage browsers, and generate reports - all from your terminal.

How Codegen Generates Locators

Codegen automatically picks the most resilient locator strategy, in this order of priority:

Project 1: Automate Login on app.vwo.com using Playwright CLI

Objective

Use Playwright CLI codegen to record a login flow on app.vwo.com, then refine the generated test into a production-ready spec file.

Step 1: Record with Codegen

# Open codegen targeting app.vwo.com
npx playwright codegen https://app.vwo.com

# Save output directly to a file
npx playwright codegen --output tests/vwo_login.spec.js https://app.vwo.com

Step 2: Generated Code (Typical Output)

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

test('VWO Login Test', async ({ page }) => {
  // Navigate to VWO login page
  await page.goto('https://app.vwo.com');

  // Fill email field
  await page.getByPlaceholder('e.g. [email protected]')
    .fill('[email protected]');

  // Fill password field
  await page.getByPlaceholder('Enter password')
    .fill('your_password_here');

  // Click Sign In button
  await page.getByRole('button', { name: 'Sign in to VWO' })
    .click();

  // Assert successful login - dashboard is visible
  await expect(page).toHaveURL(/dashboard/);
});

Step 3: Refine into Framework Pattern

// tests/vwo_login.spec.js - Production-ready version
import { test, expect } from '@playwright/test';

// Test data (move to .env or config in real projects)
const LOGIN_URL = 'https://app.vwo.com';
const VALID_EMAIL = process.env.VWO_EMAIL || '[email protected]';
const VALID_PASS = process.env.VWO_PASS || 'TestPass123';

test.describe('VWO Login Suite', () => {

  test.beforeEach(async ({ page }) => {
    await page.goto(LOGIN_URL);
  });

  test('TC-001: Successful login with valid credentials',
    async ({ page }) => {
      await page.getByPlaceholder('e.g. [email protected]')
        .fill(VALID_EMAIL);
      await page.getByPlaceholder('Enter password')
        .fill(VALID_PASS);
      await page.getByRole('button', { name: 'Sign in to VWO' })
        .click();
      await expect(page).toHaveURL(/dashboard/);
  });

  test('TC-002: Login fails with invalid password',
    async ({ page }) => {
      await page.getByPlaceholder('e.g. [email protected]')
        .fill(VALID_EMAIL);
      await page.getByPlaceholder('Enter password')
        .fill('WrongPassword');
      await page.getByRole('button', { name: 'Sign in to VWO' })
        .click();
      await expect(
        page.getByText('Your email or password is incorrect')
      ).toBeVisible();
  });

  test('TC-003: Login fails with empty fields',
    async ({ page }) => {
      await page.getByRole('button', { name: 'Sign in to VWO' })
        .click();
      // Verify validation error appears
      await expect(
        page.getByText('required')
      ).toBeVisible();
  });
});

Step 4: Run the Tests

# Run all login tests
npx playwright test tests/vwo_login.spec.js --headed

# Run with trace for debugging
npx playwright test tests/vwo_login.spec.js --trace on

# Run on specific browser
npx playwright test tests/vwo_login.spec.js --project=chromium

# Debug mode with Inspector
npx playwright test tests/vwo_login.spec.js --debug

Project 2: Generate E2E Test Suite with Codegen

Objective

Use codegen to generate a complete E2E test suite for the-internet.herokuapp.com covering multiple pages, then run with reporting and tracing.

Step 1: Record Multiple Flows

# Record form authentication flow
npx playwright codegen \
  --output tests/auth.spec.js \
  https://the-internet.herokuapp.com/login

# Record dropdown interaction
npx playwright codegen \
  --output tests/dropdown.spec.js \
  https://the-internet.herokuapp.com/dropdown

# Record checkbox interactions
npx playwright codegen \
  --output tests/checkboxes.spec.js \
  https://the-internet.herokuapp.com/checkboxes

# Record on mobile viewport
npx playwright codegen \
  --device "iPhone 13" \
  --output tests/mobile_nav.spec.js \
  https://the-internet.herokuapp.com

Step 2: Save Auth State for Reuse

# Login once, save state
npx playwright codegen \
  --save-storage auth-state.json \
  https://the-internet.herokuapp.com/login

# Now use saved state in future codegen sessions
npx playwright codegen \
  --load-storage auth-state.json \
  https://the-internet.herokuapp.com/secure

Step 3: Configure and Run Full Suite

// playwright.config.js
module.exports = {
  testDir: './tests',
  timeout: 30000,
  retries: 1,
  workers: 3,
  reporter: [
    ['html', { open: 'never' }],
    ['json', { outputFile: 'reports/results.json' }]
  ],
  use: {
    baseURL: 'https://the-internet.herokuapp.com',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
    { name: 'firefox', use: { browserName: 'firefox' } },
    { name: 'webkit', use: { browserName: 'webkit' } },
  ],
};

# Run full suite across all browsers
npx playwright test

# View the HTML report
npx playwright show-report

# Run only auth tests with retries
npx playwright test --grep "auth" --retries=2

# Shard across 3 CI machines
npx playwright test --shard=1/3
npx playwright test --shard=2/3
npx playwright test --shard=3/3

Project 3: AI Agent + Playwright CLI Workflow

Objective

Use @playwright/cli with an AI agent (Claude Code) to interactively automate and test a web application with persistent sessions and token-efficient snapshots.

Step 1: Setup @playwright/cli with Skills

# Install and setup
npm install -g @playwright/cli@latest
playwright-cli install
playwright-cli install --skills

# Verify skill file was created
cat .claude/skills/playwright-cli/SKILL.md

Step 2: Interactive Session (via Claude Code or Terminal)

# Open a persistent session
playwright-cli open https://app.vwo.com -s=vwo-login --persistent

# Take an accessibility snapshot (saved to disk, not stdout)
playwright-cli snapshot -s=vwo-login

# Fill the email field (using snapshot ref e.g., e15)
playwright-cli fill e15 "[email protected]" -s=vwo-login

# Fill password (ref e22 from snapshot)
playwright-cli fill e22 "MyPassword123" -s=vwo-login

# Click the Sign In button (ref e28)
playwright-cli click e28 -s=vwo-login

# Take a screenshot to verify
playwright-cli screenshot -s=vwo-login

# Save auth state for reuse
playwright-cli state-save vwo-auth.json -s=vwo-login

# Start tracing for debugging
playwright-cli tracing-start -s=vwo-login

# ... do more actions ...

# Stop tracing and save
playwright-cli tracing-stop -s=vwo-login --output trace.zip

Step 3: AI Agent Workflow Example

// Example: What happens when you tell Claude Code
// "Login to app.vwo.com and verify the dashboard loads"

// Claude Code with @playwright/cli skill will:
// 1. Run: playwright-cli open https://app.vwo.com -s=test
// 2. Run: playwright-cli snapshot -s=test
// 3. Read snapshot file (25K tokens vs 115K with MCP)
// 4. Identify email field ref, fill it
// 5. Identify password field ref, fill it
// 6. Click sign-in button ref
// 7. Take screenshot to verify dashboard
// 8. Report results back to you

MCP vs CLI Token Comparison

How to Install

# Create the skill directory
mkdir -p .claude/skills/playwright-cli

# Copy the SKILL.md content below into this file:
# .claude/skills/playwright-cli/SKILL.md

SKILL.md Content

---
name: playwright-cli
description: >
  Automate browser interactions using Playwright CLI tools.
  Covers both standard CLI (npx playwright) for test execution,
  codegen, debugging, reporting, and the new @playwright/cli
  for AI-agent-friendly persistent browser sessions.
triggers:
  - playwright
  - codegen
  - browser test
  - e2e test
  - record test
  - login automation
  - headed mode
  - trace viewer
  - html report
---

# Playwright CLI Skill

## Standard CLI Commands (npx playwright)

### Run Tests
```bash
npx playwright test                         # Run all tests
npx playwright test --headed                # Visible browser
npx playwright test --debug                 # Debug with Inspector
npx playwright test --ui                    # Interactive UI mode
npx playwright test --grep "login"          # Filter by name
npx playwright test --project=chromium      # Specific browser
npx playwright test --workers=4             # Parallel execution
npx playwright test --retries=2             # Retry failures
npx playwright test --trace on              # Record traces
npx playwright test --shard=1/3             # Shard for CI
npx playwright test --list                  # List tests (no run)
```

### Record Tests (Codegen)
```bash
npx playwright codegen [url]                       # Record test
npx playwright codegen --output tests/my.spec.js   # Save to file
npx playwright codegen --target python              # Python output
npx playwright codegen --device "iPhone 13"         # Mobile
npx playwright codegen --save-storage auth.json     # Save auth
npx playwright codegen --load-storage auth.json     # Reuse auth
```

### Reports & Debugging
```bash
npx playwright show-report                 # Open HTML report
npx playwright show-trace trace.zip        # View trace file
npx playwright install                     # Install browsers
npx playwright install --with-deps         # + OS dependencies
npx playwright clear-cache                 # Clear browser cache
```

## @playwright/cli (AI Agent CLI)

### Setup
```bash
npm install -g @playwright/cli@latest
playwright-cli install
playwright-cli install --skills
```

### Interactive Commands
```bash
playwright-cli open [url] -s=[session]     # Open page
playwright-cli snapshot -s=[session]       # A11y snapshot
playwright-cli screenshot -s=[session]     # Screenshot
playwright-cli click [ref] -s=[session]    # Click element
playwright-cli fill [ref] "text" -s=[s]    # Fill input
playwright-cli type [ref] "text" -s=[s]    # Type text
playwright-cli press Enter -s=[session]    # Press key
playwright-cli select [ref] "val" -s=[s]   # Select option
playwright-cli state-save file.json -s=[s] # Save state
playwright-cli state-load file.json -s=[s] # Load state
playwright-cli close -s=[session]          # Close page
```

## Locator Priority (Codegen)
1. getByRole('button', { name: '...' })
2. getByText('...')
3. getByTestId('...')
4. getByPlaceholder('...')
5. CSS selectors (last resort)

## Common Patterns

### Login Automation
```javascript
test('login test', async ({ page }) => {
  await page.goto('https://app.example.com');
  await page.getByPlaceholder('Email').fill('[email protected]');
  await page.getByPlaceholder('Password').fill('pass123');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page).toHaveURL(/dashboard/);
});
```

### CI/CD Configuration
```bash
npx playwright test \
  --reporter=json,html \
  --workers=4 \
  --retries=2 \
  --trace=on-first-retry \
  --forbid-only
```