Browse all tutorials →
Claude Code November 20, 2026 13 min read

CLAUDE.md for Test Automation: A Copy-Ready Playwright Template

The quality of the Playwright tests Claude Code writes depends mostly on one file. Here is a complete CLAUDE.md for a test automation project, why each section is there, how to split it for big teams, and the rules that stop the AI from writing brittle or dishonest tests.

Quick answer: CLAUDE.md is the instruction file Claude Code loads at the start of every session. For a Playwright project it should contain five things: the commands to run tests, the folder structure, your locator and assertion conventions, how test data is created, and guardrails that forbid weakening assertions or adding hard waits. Generate a starter with /init, then paste in the template below and trim it to fit your project.

Ask Claude Code to "write a login test" in an empty project and you will get a reasonable test. Ask the same thing in a project with a good CLAUDE.md and you get a test that uses your page objects, your fixtures, your tags and your locator strategy, and that you can merge almost without edits.

That gap is the difference between "AI testing is a toy" and "AI testing saves me hours a week". This guide gives you a full, copy-ready template and explains every rule in it.


What Is CLAUDE.md?

CLAUDE.md is a plain Markdown file that Claude Code reads automatically when a session starts. Think of it as the onboarding document you would give a new automation engineer, written for an AI teammate. Claude Code looks for it in a few places:

Location Used for Commit it?
./CLAUDE.md (repo root) Team-wide project rules Yes
tests/api/CLAUDE.md (subfolders) Rules for one area, loaded when Claude works there Yes
~/.claude/CLAUDE.md (your home folder) Personal preferences across all projects No

Run /init in Claude Code to generate a first draft from your repository, and use /memory to open and edit the loaded files. New to Claude Code? Start with the Playwright + Claude Code tutorial.

Why CLAUDE.md Matters More for Testing Than for Development

Bad AI-written application code usually fails loudly. Bad AI-written tests fail quietly: they pass while checking nothing, or they work today and become flaky next week. The specific risks are:

  • Brittle locators such as div:nth-child(3) > button that break on the next redesign.
  • Hard waits (waitForTimeout) that make tests slow and flaky.
  • Weak assertions that pass whatever the page shows.
  • "Make it green" fixes that change an expected value and hide a real bug.
  • Duplicate code that ignores your existing page objects and fixtures.

Every one of these can be prevented by a single line in CLAUDE.md.

The Full CLAUDE.md Template for Playwright

Copy this into the root of your Playwright project, then replace the angle-bracket placeholders and delete anything that does not apply.

CLAUDE.md
# <Project name> — E2E & API Test Suite

Playwright + TypeScript tests for <app name> (<one line: what the app does>).
App under test runs at BASE_URL (default http://localhost:3000).

## Commands
- Install:            npm ci && npx playwright install --with-deps
- Run all:            npx playwright test
- Run one file:       npx playwright test tests/e2e/checkout.spec.ts
- Run by tag:         npx playwright test --grep @smoke
- Re-run failures:    npx playwright test --last-failed
- Flakiness check:    npx playwright test <file> --repeat-each=20 --workers=1
- Type check:         npx tsc --noEmit
- Lint:               npm run lint
- Report:             npx playwright show-report

## Structure
- tests/e2e/        UI specs, one file per feature
- tests/api/        API specs using the request fixture
- tests/pages/      Page objects (one class per page/component)
- tests/fixtures/   Custom fixtures (auth, test data)
- tests/data/       Static test data (JSON); no real customer data
- playwright.config.ts  Projects: chromium, firefox, webkit, mobile

## Writing tests
- Locators, in order of preference: getByRole > getByLabel >
  getByPlaceholder > getByText > getByTestId. No CSS/XPath unless
  there is no alternative; explain why in a comment if you use one.
- Use web-first assertions: await expect(locator).toBeVisible(),
  toHaveText(), toHaveURL(). Never assert on a one-off textContent().
- NEVER use page.waitForTimeout(). Wait for a state, a response
  (page.waitForResponse) or an assertion instead.
- Put locators and actions in page objects under tests/pages/.
  Reuse existing page objects before creating new ones.
- Each test must be independent: create its own data, no reliance
  on test order. Use the fixtures in tests/fixtures/.
- Log in with the authenticated storageState fixture, not the UI,
  except in tests that are about login itself.
- One behaviour per test. Test names describe the behaviour:
  "guest can apply a valid coupon", not "test coupon 1".
- Tag every test: @smoke (critical path, runs on every PR),
  @regression (nightly), @slow (over 30s).

## Test data
- Create data through the API helpers in tests/fixtures/api.ts.
- Use unique values (e.g. `user+${Date.now()}@example.com`).
- Never hard-code credentials; read them from process.env.

## Fixing failing tests — guardrails
- First classify the failure: locator changed / timing / test data /
  environment / real application bug. Show the evidence.
- If the application is wrong, STOP and tell me. Do not edit the test.
- NEVER change expected values, delete assertions or make them weaker
  (e.g. toHaveText -> toContainText) without asking me first.
- NEVER add test.skip(), test.fixme(), retries or longer timeouts to
  make a test pass without asking.
- Fix locators in the page object, then rerun every spec using it.

## Using the browser (Playwright MCP)
- Before writing a test for a page you have not seen, open it with
  the Playwright MCP browser and read the accessibility snapshot.
- Only use local or staging URLs. Never production.

## Before you finish a task
- Run the tests you created or changed, on chromium at minimum.
- Run npx tsc --noEmit and npm run lint.
- Summarise: files changed, tests added, anything you were unsure of.

## More detail
- Locator and page object conventions: @docs/testing-conventions.md

At around 90 lines, this is long enough to cover what matters and short enough that every rule still gets attention.

Go from template to a full AI testing workflow

The Udemy course takes you from Playwright basics to Claude Code project setup, the MCP Server and your own QA AI agent, step by step.

See the course plan →

The Template, Section by Section

Commands

Claude Code runs your tests itself, so it needs the exact commands. Without them it guesses, for example running npm test when your suite needs npx playwright test, or running the whole suite when one file would do. Including the flakiness-check command means it will actually use it.

Structure

A short folder map stops duplicate page objects and tests ending up in random folders. Only list folders that matter; Claude Code can explore the rest.

Writing tests

This is where most of the quality comes from. The locator preference order mirrors Playwright's own recommendation. The "no waitForTimeout" rule alone prevents a large share of the flaky tests AI tools write. Tag rules connect generated tests to your CI pipeline.

Test data

AI-written tests often reuse the same hard-coded user, which works alone and fails in parallel. Pointing to your API helpers and requiring unique values fixes that. See Playwright test data management.

Guardrails

The most important section. It stops Claude Code from turning a real bug into a passing test. The detailed workflow behind these rules is in how to fix failing tests with Claude Code.

Using the browser

With the Playwright MCP server connected, telling Claude Code to look before it writes produces locators based on the real page instead of guesses.

Before you finish

A definition of done. Without it, AI tools often stop as soon as the code is written, before it has been run.

Structuring CLAUDE.md for Bigger Teams

  • Keep the root file short. Everything in it is loaded every session. Move long conventions into docs/ and import them with @docs/testing-conventions.md.
  • Use subfolder files for different rules. A tests/api/CLAUDE.md can say "use the request fixture, validate response schemas with zod" without cluttering the UI rules.
  • Review it like code. Changes to CLAUDE.md change every test the AI writes, so they deserve a pull request.
  • Add a rule every time the AI repeats a mistake. The file should grow from real problems, not from theory.
  • Pair it with project MCP config. Commit a .mcp.json (via claude mcp add --scope project ...) so everyone gets the same Playwright MCP setup.

How to Test Your CLAUDE.md

Treat the file like any other test asset and check that it works:

  1. Start a fresh Claude Code session and ask: "Summarise the rules you must follow when writing tests in this repo." If it misses a rule, the rule is unclear or buried.
  2. Ask for a test for one real flow. Check: page object reused? Correct locators? Tags? No hard waits?
  3. Break a locator on purpose and ask Claude Code to fix the failing test. Did it classify the failure and fix it in the page object?
  4. Change an expected value in the app and ask for a fix. Did it stop and report a bug instead of editing the assertion?

Common CLAUDE.md Mistakes

  • Pasting a whole style guide. 800 lines means key rules get lost. Prioritise.
  • Vague rules. "Write good tests" does nothing. "Use getByRole before getByTestId" does.
  • Outdated commands. If a script was renamed, Claude Code will keep running the old one.
  • Secrets in the file. Never put passwords, tokens or customer data in CLAUDE.md.
  • Never updating it. Review it whenever your framework or conventions change.

Want ready-made prompts to use with this setup? See 25 Claude Code prompts for testers.

Frequently Asked Questions

What is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code automatically loads into context at the start of a session. It holds project-specific instructions such as commands, folder structure, coding conventions and rules, so you do not have to repeat them in every prompt.

Where should I put CLAUDE.md in a Playwright project?

Put the main file in the repository root and commit it so the whole team shares it. You can add extra CLAUDE.md files in subfolders, such as tests/api/, for rules that only apply there; Claude Code picks those up when it works with files in that folder. Personal preferences go in your user-level file in ~/.claude/CLAUDE.md.

How do I create a CLAUDE.md file?

Run /init inside Claude Code to generate a starting file based on your repository, then edit it by hand. Add your testing conventions and guardrails from this template, remove anything generic, and keep it short.

How long should CLAUDE.md be?

As short as possible while still covering the rules that matter, usually under 150 to 200 lines. Everything in it is loaded into context every session, so long files cost tokens and important rules get diluted. Move detailed guides into separate files and reference them.

Does CLAUDE.md work with Cursor or GitHub Copilot?

No, CLAUDE.md is specific to Claude Code. Cursor uses rules in .cursor/rules and Copilot uses .github/copilot-instructions.md. The content of this template works in those files too with small format changes.

What testing rules should go in CLAUDE.md?

The most valuable rules are: preferred locators (getByRole, getByLabel, getByTestId), web-first assertions only, no waitForTimeout, where page objects and fixtures live, how to create test data, which tags to use, and guardrails that forbid weakening assertions or changing expected values without asking.

Can CLAUDE.md import other files?

Yes. You can reference other files with the @path syntax, for example @docs/testing-conventions.md, so detailed conventions live in their own documents and CLAUDE.md stays short.

Should CLAUDE.md be committed to git?

Yes. The project CLAUDE.md should be committed and reviewed like code so every team member and CI run gets the same rules. Keep secrets, tokens and passwords out of it.


Asim Noaman, Playwright and Claude AI course instructor

Asim Noaman

Sr. SQA Manager & AI Automation Engineer

18+ years in QA. Asim currently runs an 80+ engineer QA function at Tkxel and built a Testing Center of Excellence for a major Saudi bank. He builds AI testing agents with Playwright, Claude AI and the MCP Server at work, and teaches the same workflow in his courses.

18+ Years in QA 80+ engineer QA function
Udemy Instructor 4.5★ · 140+ ratings · 570+ students
Anthropic Certificates Claude API · MCP
Connect on LinkedIn

Full profile →

Playwright + Claude AI Course on Udemy

Learn Playwright and Claude Code in One Course

The course teaches Playwright in JavaScript from scratch (locators, assertions, hooks and the Page Object Model), then Claude Code, the Playwright MCP Server, your own QA AI agent and Playwright Test Agents. Rated 4.5★ from 130+ ratings, 510+ students.

  • Playwright from scratch, no prior coding needed
  • Claude Code project setup, test generation and custom QA subagents
  • Playwright MCP Server test generation and your own QA AI agent
  • Playwright Test Agents and prompt engineering for testers
See the Course Plan →

New to testing? Start with Manual Testing & QA with AI or AI Software Testing for Beginners · Which course is right for me?