Setup Beginner

Get Playwright installed and configured in your project, then use Claude Code to run your first AI-generated browser test. This lesson covers everything from installation to your first passing test.

1. Installing Playwright

Playwright provides an initialization command that sets up everything you need, including the browser binaries, configuration file, and example tests.

Terminal

# Initialize Playwright in your project
$ npm init playwright@latest

# The installer will ask:
# - TypeScript or JavaScript? (recommend TypeScript)
# - Where to put tests? (default: tests/)
# - Add a GitHub Actions workflow? (optional)
# - Install Playwright browsers? (Yes)

After initialization, your project will have these new files:

Project Structure

my-project/
  playwright.config.ts    # Playwright configuration
  tests/
    example.spec.ts       # Example test file
  package.json            # Updated with Playwright dependency

2. Configuring playwright.config.ts

The configuration file controls how Playwright runs your tests. Here is a practical configuration for working with Claude Code:

TypeScript (playwright.config.ts)

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  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,
  },
});

Claude Code Tip: You can ask Claude Code to customize this config for you: "Update the Playwright config to add mobile device testing for iPhone 14 and Pixel 7"

3. Setting Up the Test Directory

Organize your tests for scalability. A good structure separates test files, page objects, fixtures, and test data:

Project Structure

tests/
  e2e/
    auth.spec.ts          # Authentication tests
    checkout.spec.ts      # Checkout flow tests
    dashboard.spec.ts     # Dashboard tests
  pages/
    login.page.ts         # Login page object
    dashboard.page.ts     # Dashboard page object
  fixtures/
    test-data.ts          # Test data and factories
    auth.fixture.ts       # Authentication fixture

4. Running Your First Test

Let's use Claude Code to generate and run a test. Start Claude Code in your project directory:

Claude Code Session

$ claude

Claude > Write a simple Playwright test that checks the homepage
         loads correctly with the right title.

# Claude generates and saves the test file

Claude > Run the test with npx playwright test

# Claude runs the test and shows the results

Terminal

# You can also run tests directly
$ npx playwright test

# Run a specific test file
$ npx playwright test tests/e2e/auth.spec.ts

# Run in headed mode (see the browser)
$ npx playwright test --headed

# Run with the UI mode
$ npx playwright test --ui

# Show the HTML report
$ npx playwright show-report

5. Claude Code Commands for Playwright

Here are common Claude Code prompts for Playwright workflows:

Task	Claude Code Prompt
Generate a test	"Write a Playwright test for the user registration flow"
Run tests	"Run all Playwright tests and show me the results"
Fix a failure	"This test is failing with a timeout error. Fix it."
Add to config	"Add mobile viewport testing to the Playwright config"
Create page object	"Create a page object for the checkout page based on checkout.html"
Update browsers	"Run npx playwright install to update browsers"

Try It Yourself

Initialize Playwright in a project, start Claude Code, and ask it to generate a test for your homepage. Run the test and see it pass.

Next: Writing Tests →

← Introduction Writing Tests →