← All Posts

How to Do Playwright Testing on Claude Code

You can run Playwright end-to-end tests directly inside Claude Code by prompting it to scaffold tests, execute npx playwright test via the terminal, and interpret failures in context. Claude Code handles the full loop: writing test files, running them, reading the output, and iterating on failures without you leaving your editor. The main constraint is usage limits — long Playwright sessions consume tokens fast, especially when Claude reads DOM snapshots and retries flaky tests.

  • Playwright test runs are token-intensive: each failure trace + retry can burn hundreds of tokens
  • Claude Code supports /test slash command for running tests and surfacing results inline
  • Claude Code usage limits reset on a 5-hour rolling window — a long Playwright debug session can trigger a lockout mid-PR

What is Playwright and why use it inside Claude Code?

Playwright is Microsoft's open-source end-to-end testing framework for web apps. It controls Chromium, Firefox, and WebKit browsers programmatically, letting you simulate real user interactions: clicks, form fills, navigation, and network interception.

Using it inside Claude Code means you get an AI pair-programmer that can write tests against your actual codebase, run them, and read the failure output in the same context window. No copy-pasting stack traces between tools. No context switching.

How to set up Playwright in a Claude Code project

If Playwright isn't installed yet, prompt Claude Code to handle the setup:

Install Playwright in this project and scaffold a basic test for the login page.

Claude will run the following in the integrated terminal:

npm init playwright@latest

This installs @playwright/test, creates a playwright.config.ts, and generates an example test in /tests. According to the official Playwright documentation, this command also downloads browser binaries for Chromium, Firefox, and WebKit automatically.

Key config options to set early

  • baseURL: set to your local dev server (e.g., http://localhost:3000) so tests don't hardcode URLs
  • testDir: point to your /e2e or /tests folder
  • headless: keep true for CI; use false locally when debugging visual issues
  • retries: set to 1 or 2 in CI to reduce flake impact

How to write Playwright tests with Claude Code

The most effective workflow is to describe the user journey in plain English and let Claude generate the test scaffold:

Write a Playwright test that logs in as a user, navigates to the dashboard, and verifies the usage chart renders.

Claude Code will generate a .spec.ts file using Playwright's Locator API — the preferred, auto-waiting approach that replaces older CSS selector patterns. A typical output looks like:

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

test('dashboard renders usage chart after login', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('password');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByTestId('usage-chart')).toBeVisible();
});

Using the /test slash command

Once tests are written, use Claude Code's built-in /test slash command to trigger a run. Claude will execute the test suite, capture stdout/stderr, and surface failures inline so it can immediately propose fixes. You can also be explicit:

Run the Playwright tests in /e2e and fix any failures.

Claude Code will call npx playwright test, read the output, and attempt auto-repair in one loop.

How to debug Playwright failures inside Claude Code

When a test fails, paste the error or let Claude read the terminal output directly. Common failure patterns Claude handles well:

  • Element not found: Claude will suggest more resilient locators using getByRole, getByLabel, or getByTestId instead of brittle CSS selectors
  • Timeout errors: Claude can add explicit await page.waitForLoadState('networkidle') or increase the default actionTimeout in config
  • Flaky tests: Claude can identify race conditions and introduce proper expect().toBeVisible() assertions as synchronization points
  • Auth state reuse: Claude can implement Playwright's storageState pattern to avoid re-logging in on every test

Using Playwright's trace viewer

Enable traces in playwright.config.ts with trace: 'on-first-retry'. After a failure, ask Claude Code:

Open the Playwright trace for the last failed test and explain what went wrong.

Claude will run npx playwright show-trace and interpret the step-by-step DOM snapshots.

How to run Playwright tests in CI via Claude Code

For GitHub Actions or similar pipelines, prompt Claude to generate a workflow file:

Create a GitHub Actions workflow that installs dependencies and runs Playwright tests on every PR.

Claude will scaffold a .github/workflows/playwright.yml using the official Playwright CI guide, including browser installation with npx playwright install --with-deps and artifact upload for HTML reports.

Parallel test sharding

Large test suites can be sharded across multiple CI runners. Ask Claude to configure sharding:

Add Playwright test sharding across 4 CI runners to speed up the test suite.

This uses Playwright's built-in --shard=1/4 flag and reduces total CI wall-clock time significantly on suites with 50+ tests.

Managing Claude Code usage during long Playwright sessions

Playwright debugging is one of the most token-intensive workflows in Claude Code. Each iteration — failing test output, DOM snapshot, proposed fix, re-run — compounds quickly. A single debugging loop on a complex test can consume a meaningful chunk of your hourly usage allocation.

Claude Code usage resets on a 5-hour rolling window. If you hit your limit mid-session (mid-PR, mid-debug loop), you're locked out until the window resets. That's a 5-hour wait at the worst possible moment.

Usagebar sits in your macOS menu bar and shows your live Claude Code usage at a glance. It fires smart notifications at 50%, 75%, and 90% of your limit so you can decide whether to pace yourself, wrap up the current test suite, or push through before the reset. Credentials are stored in macOS Keychain. It's free for students, and pay-what-you-want for everyone else.

For more on keeping usage efficient during test-heavy sessions, see how to reduce Claude Code token usage and how Claude Code usage affects your Pro limits.

Related testing guides: React component testing on Claude Code and API testing on Claude Code.

Key takeaways

  1. Install Playwright with npm init playwright@latest and let Claude set up the config
  2. Use plain-English prompts to generate .spec.ts files against your actual UI flows
  3. Use the /test slash command to run tests and auto-repair failures in one loop
  4. Enable trace: 'on-first-retry' so Claude can interpret failure snapshots
  5. Use storageState for auth reuse to reduce token overhead on every test run
  6. Monitor your usage with Usagebar — Playwright sessions burn tokens fast and a mid-session lockout kills momentum

Sources

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar