Claude Code CLI

# Install globally
$ npm install -g @anthropic-ai/claude-code

# Navigate to your project
$ cd ~/playwright-project

# Start Claude Code — browser opens for auth on first run
$ claude

# Or: use API key instead of subscription
$ export ANTHROPIC_API_KEY="sk-ant-..."
$ claude

# Interactive session
$ claude

# One-shot: single prompt, get answer, exit
$ claude -p "explain the page object pattern in tests/pages/"

# Continue last conversation
$ claude --continue    # or -c

# Pick from recent sessions
$ claude --resume      # or -r

# Pipe input
$ cat test-results/errors.log | claude -p "explain these test failures"

# JSON output for scripting
$ claude -p "list all spec files" --output-format json

# Specify model
$ claude --model claude-sonnet-4-6

# Best practice: append rules for Playwright project
$ claude --append-system-prompt "Always use Page Object Model. Import test from src/fixtures/base.fixture.ts, not @playwright/test."

# CI/CD: run with rules from file
$ claude -p "review tests/" --append-system-prompt-file .claude/ci-rules.md

# Allow specific tools
$ claude --allowedTools "Read,Grep,Glob,Write,Edit"

# YOLO mode — skip all prompts (containers only!)
$ claude --dangerously-skip-permissions

~/.claude/
    CLAUDE.md              ← Global: personal defaults for ALL projects
    settings.json          ← Global permissions, model preferences
    keybindings.json       ← Your keyboard shortcuts

./ (project root)
    CLAUDE.md              ← Project: team-shared (commit to git!)
    CLAUDE.local.md        ← Project: personal overrides (gitignored)
    .claudeignore          ← Files Claude should never read

./.claude/
    settings.json          ← Project settings (hooks, permissions)
    skills/
        SKILL.md           ← Project-wide skill
        playwright/
            SKILL.md       ← Domain-specific skill

./tests/
    CLAUDE.md              ← Directory-level: rules only for tests/

# Playwright E2E Test Framework

## Stack
Playwright 1.50+ · TypeScript 5.6+ · Faker.js · dotenv

## Commands
npm test              # run all tests
npm run test:ui       # Playwright UI mode
npm run test:chrome   # chromium only
npm run lint          # ESLint check
npm run typecheck     # TypeScript strict check

## Architecture
src/pages/       — Page Objects (extend BasePage)
src/fixtures/    — Custom Playwright fixtures (DI)
src/api/         — API client classes
src/utils/       — Env config, helpers, test data generator
src/data/        — Static test data, routes, users
tests/           — Test specs by feature

## Critical Rules
- ALWAYS import { test, expect } from `src/fixtures/base.fixture.ts`
  NOT from `@playwright/test`
- Use `data-testid` for selectors, never CSS classes
- Page objects: locators as readonly props, actions as methods
- Env vars via `src/utils/env.config.ts` — never hardcode
- Auth handled by `tests/auth.setup.ts` — tests start authenticated

## Naming
Files: kebab-case · Classes: PascalCase · Test IDs: kebab-case
Tests: start with "should" — "should login with valid credentials"

## Gotchas
- page.waitForTimeout() is an anti-pattern — use expect/waitForURL
- API tests don't use storageState — they get own token in beforeAll
- Never commit page.pause() — debug only

.claude/skills/
    SKILL.md                     ← Main project skill (auto-loaded)
    playwright-tests/
        SKILL.md                 ← Activated: "write a test", "fix spec"
    api-testing/
        SKILL.md                 ← Activated: "API test", "endpoint test"
    code-review/
        SKILL.md                 ← Activated: "review this", "check quality"

---
name: playwright-tests
description: >
  Activated when writing, fixing, or modifying Playwright tests.
  Triggers: test, spec, e2e, playwright, page object, fixture.
---

# Playwright Test Guidelines

## Creating a New Test
1. Does it need auth? Import from the correct fixture:
   - Auth tests → `src/fixtures/auth.fixture.ts`
   - Regular tests → `src/fixtures/base.fixture.ts`
   - API only → `@playwright/test` directly

2. Create page object first if it doesn't exist:
   - Extend `BasePage` from `src/pages/base.page.ts`
   - Locators = readonly properties via `this.byTestId()`
   - Actions = methods, Assertions = `expectX()` methods

3. Register page object in `src/fixtures/base.fixture.ts`

## Locator Priority
1. getByTestId() ← most reliable
2. getByRole()   ← semantic
3. getByText()   ← visible text
4. getByLabel()  ← form fields
5. locator()     ← last resort

## Anti-Patterns
✗ page.waitForTimeout(ms) — use auto-waiting
✗ Hardcoded URLs — use ROUTES from data/routes
✗ Hardcoded creds — use USERS from data/users
✗ page.pause() in committed code

{
  "hooks": {
    "post-edit": [
      {
        "command": "npx eslint --fix $FILE 2>/dev/null || true",
        "description": "Auto-fix lint after every edit"
      }
    ],
    "pre-commit": [
      {
        "command": "npm run typecheck && npx playwright test --reporter=list 2>&1 | tail -20",
        "description": "Type-check + quick test before commit"
      }
    ]
  }
}

# Don't wait for auto-compact at 95%. Do it manually at ~70%:
/compact focus on the auth setup refactoring decisions

# You can specify what to keep:
/compact keep only the page object patterns and fixture changes

# Prevent Claude from reading these — saves thousands of tokens
node_modules/
dist/
build/
playwright-report/
test-results/
blob-report/
coverage/
*.lock
*.min.js
*.min.css
*.map
*.log

# Switch in-session:
/model claude-haiku-4-5     # for exploration
/model claude-sonnet-4-6    # back to normal work

# Subagent gets its own clean context — doesn't pollute yours
> Use a subagent to explore the src/api/ directory
  and report: what endpoints exist, error handling patterns,
  and whether we have retry logic.

# Claude spawns a focused agent, explores, reports back
# Your main context stays clean

/rename playwright-auth-refactor
/rename adding-checkout-page-object

# Later, resume by name — no need to re-explain context:
$ claude --resume

# Picks up exactly where you left off — zero re-explanation needed
$ claude --continue    # or: claude -c

# Bookmark your usage dashboard:
https://claude.ai/settings/usage

# In-session: status bar shows context %
# Rule: compact at 70%, /clear at task boundaries

playwright-project/
    CLAUDE.md                    ← Project brain (section above)
    CLAUDE.local.md              ← Your personal overrides (.gitignored)
    .claudeignore                ← Exclusions (section above)
    .claude/
        settings.json            ← Hooks + permissions (hooks section)
        skills/
            playwright-tests/
                SKILL.md         ← Test writing skill (skills section)
    .eslintrc.json               ← Linting rules Claude follows
    tsconfig.json                ← TypeScript strict mode config
    prettier.config.js           ← Formatting rules
    .editorconfig                ← Editor settings
    .env.example                 ← Template for environment vars
    .gitignore                   ← Include .env, auth/, reports/
    playwright.config.ts         ← Multi-project Playwright config

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "Write", "Edit",
      "Bash(npm run *)",
      "Bash(npx *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  },
  "hooks": {
    "post-edit": [{
      "command": "npx eslint --fix $FILE 2>/dev/null || true",
      "description": "Auto-lint after every edit"
    }],
    "pre-commit": [{
      "command": "npm run typecheck && npm run lint",
      "description": "Quality gate before commit"
    }]
  }
}