Playwright + Claude Code Tutorial: AI Testing from Scratch

Writing Playwright tests by hand is powerful, but it is also slow. You stare at the DOM, hunt for the right locator, wire up assertions, and repeat — test after test. Claude Code changes that equation entirely. You describe the test in English, and Claude writes production-ready Playwright TypeScript in seconds.

This tutorial walks you through the complete setup: installing Claude Code, connecting it to Playwright via the MCP server, generating your first AI-written test, debugging a failure, and running everything in GitHub Actions. By the end, you will have a working workflow that turns plain-English descriptions into executable Playwright tests.

If you are new to Playwright itself, start with our Playwright automation for beginners guide first. This tutorial assumes basic familiarity with TypeScript and the command line.

What Is Claude Code?

Claude Code is Anthropic's official command-line interface for Claude AI. Unlike the web chat interface, Claude Code runs in your terminal and has direct access to your project files, your shell, and — critically — any MCP servers you configure.

MCP stands for Model Context Protocol. It is an open standard that lets AI models interact with external tools. When you connect the Playwright MCP server to Claude Code, Claude gains the ability to launch browsers, navigate pages, read live DOM elements, take screenshots, and interact with your application — all programmatically, all from a single conversation in your terminal.

The result: you describe what you want to test in plain English, and Claude generates complete, runnable Playwright test code that uses real selectors from your actual application. No guessing, no placeholder locators, no copy-paste from documentation.

Prerequisites

Before you start, make sure you have these installed:

• Node.js 18+ — required for both Playwright and the MCP server
• A Playwright project — if you do not have one, we will create one in the next step
• An Anthropic account — you need a Claude Code subscription to use the CLI
• A terminal — macOS Terminal, iTerm2, Windows Terminal, or VS Code integrated terminal

Step 1: Install Claude Code and Playwright

First, install Claude Code globally. Open your terminal and run:

# Install Claude Code CLI globally
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

# Create a new Playwright project (skip if you have one)
mkdir my-playwright-tests && cd my-playwright-tests
npm init playwright@latest

# Install browsers
npx playwright install

The npm init playwright@latest command scaffolds a complete project with playwright.config.ts, an example test file, and the recommended folder structure. Choose TypeScript when prompted — Claude Code generates TypeScript by default, and it is the standard for modern Playwright projects.

Step 2: Configure the Playwright MCP Server

This is the step that unlocks everything. The Playwright MCP server gives Claude Code the ability to launch a real browser, navigate your application, and read the live page structure. Without it, Claude is guessing at selectors. With it, Claude sees exactly what your users see.

Add the Playwright MCP server to Claude Code with a single command:

# Register the Playwright MCP server
claude mcp add playwright -- npx @anthropic-ai/playwright-mcp@latest

# Verify it was added
claude mcp list

# You should see:
# playwright: npx @anthropic-ai/playwright-mcp@latest

That is it. No JSON config files to edit, no environment variables to set. The claude mcp add command registers the server in your Claude Code configuration, and it will be available in every future session.

For a deeper dive into what the MCP server can do — including screenshot capture, network interception, and accessibility tree reading — see our full guide on the Playwright MCP server for Claude AI.

Step 3: Generate Your First AI-Written Playwright Test

Now for the part that changes your workflow forever. Open Claude Code in your project directory and ask it to write a test:

# Navigate to your project
cd my-playwright-tests

# Start Claude Code
claude

# In the Claude Code prompt, type:
> Navigate to https://demo.playwright.dev/todomvc and write a
  Playwright test that adds three todos, marks the second one
  as complete, filters to show only active items, and verifies
  that only two items are visible.

Claude Code will launch the Playwright MCP browser, navigate to the TodoMVC app, inspect the page structure, and generate a complete test file. Here is what the output looks like:

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

test('add todos, complete one, filter active', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc');

  // Add three todo items
  const input = page.getByPlaceholder('What needs to be done?');
  await input.fill('Buy groceries');
  await input.press('Enter');
  await input.fill('Write Playwright tests');
  await input.press('Enter');
  await input.fill('Review pull request');
  await input.press('Enter');

  // Mark the second item as complete
  const todoItems = page.getByTestId('todo-item');
  await todoItems.nth(1).getByRole('checkbox').check();

  // Filter to active items
  await page.getByRole('link', { name: 'Active' }).click();

  // Verify only two items are visible
  await expect(todoItems).toHaveCount(2);
  await expect(todoItems.nth(0)).toContainText('Buy groceries');
  await expect(todoItems.nth(1)).toContainText('Review pull request');
});

Notice what Claude did: it used getByPlaceholder, getByTestId, and getByRole — Playwright's recommended locator strategies — because it read the actual DOM structure through the MCP server. These are not guessed selectors. They are derived from the real page, which means they will work when you run the test.

Run the generated test to verify:

npx playwright test tests/todo.spec.ts

If the test passes on the first run — and it almost always does when generated through the MCP server — you just saved 10-15 minutes of manual test writing. Scale that across a suite of 50 tests and you are looking at hours saved per sprint.

Step 4: Debug Failing Tests with Claude Code

Generating tests is only half the story. Tests break — locators change, application flows evolve, and flaky timing issues appear. Debugging is where Claude Code saves just as much time as it does in generation.

When a test fails, copy the error output and paste it into Claude Code:

> This test is failing with "locator.click: Error: strict mode
  violation: getByRole('button', { name: 'Submit' }) resolved
  to 3 elements." Fix it.

  [paste the full test code below]

Claude will analyze the error, understand that the locator is matching multiple elements, and suggest a fix — such as narrowing the scope with .first(), adding a parent locator with .locator('.checkout-form').getByRole('button', { name: 'Submit' }), or using a more specific selector entirely.

For visual debugging, Claude Code can take a screenshot of the current page state through the MCP server. Ask it to "navigate to the page and show me what the checkout form looks like" and Claude will capture and display the screenshot directly in your terminal, helping you understand why a locator is not matching.

Step 5: Run AI-Generated Tests in CI/CD

Tests generated by Claude Code are standard Playwright TypeScript files. They have no dependency on Claude Code or the MCP server at runtime. This means you can run them in any CI/CD pipeline exactly the way you run hand-written Playwright tests.

Here is a complete GitHub Actions workflow that runs your Playwright tests on every push:

name: Playwright Tests
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14

This workflow installs dependencies, downloads browser binaries, runs all Playwright tests, and uploads the HTML report as an artifact — whether the tests pass or fail. For a complete CI/CD setup guide with parallel sharding and Slack notifications, see our Playwright GitHub Actions CI/CD tutorial.

Advanced Patterns: Beyond Basic Test Generation

Once you have the basic workflow down, Claude Code enables several advanced patterns that are difficult or tedious to implement by hand:

1. Page Object Model generation

Ask Claude Code to "create a Page Object Model for the checkout page" and it will navigate to your checkout page, read the DOM, and generate a complete POM class with typed methods for every interactive element. This is especially powerful for large applications where manually cataloguing every form field and button is time-consuming. See our Playwright Page Object Model tutorial for the full pattern.

2. API + UI test integration

Claude Code can generate tests that combine API calls (for setup/teardown) with UI assertions — for example, creating a user via API, then verifying the user appears in the admin dashboard via Playwright. Learn more in our Playwright API testing guide.

3. Self-healing locators

When Claude Code generates tests through the MCP server, it prefers resilient locator strategies — getByRole, getByText, getByLabel — that are less likely to break when CSS classes or DOM structure changes. This built-in preference for self-healing locators reduces long-term maintenance cost significantly.

4. Bulk test generation from user stories

Feed Claude Code a list of user stories or acceptance criteria and ask it to generate a test for each one. In a single session, you can generate 10-20 well-structured tests that would take a full day to write manually. This is where the AI QA automation productivity gains become undeniable.

Best Practices for Claude Code + Playwright

After working with hundreds of engineers who use this workflow, here are the patterns that consistently produce the best results:

1. Be specific in your prompts. "Test the login flow" is vague. "Test that a user with email user@test.com and password Test1234 can log in and sees the dashboard with their name in the header" gives Claude the context to generate a precise, complete test.
2. Always let Claude use the MCP server. If Claude is not navigating to your application, it is guessing at selectors. The MCP server is what makes the generated tests accurate.
3. Review and commit, do not blindly trust. Claude-generated tests are high quality, but they are not infallible. Read the generated code, verify the assertions match your requirements, and then commit. Treat Claude as a very fast junior engineer who needs code review.
4. Use Claude for refactoring too. Ask Claude Code to "refactor this test file to use fixtures for authentication" or "extract the repeated setup into a beforeEach hook." Claude is as good at restructuring existing tests as it is at writing new ones.
5. Keep your Playwright version current. Claude Code knows the latest Playwright APIs. If you are on an older version, the generated code may use features your installation does not support. Run npm update @playwright/test regularly.

For a comprehensive list of testing patterns that work well with AI generation, see our Playwright best practices for 2026 guide. And if you are exploring other AI tools alongside Claude Code, our comparison of AI tools for writing Playwright tests covers the full landscape.

Frequently Asked Questions

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn