cc-e2e

CLI tool to scaffold E2E testing infrastructure for Claude Code projects.

Overview

This tool provides a complete E2E testing setup including:

• Claude Code slash commands for E2E test workflow
• Documentation templates for test design and progress tracking
• Coding standards for Playwright best practices
• Directory structure for organized test files
• Playwright configuration auto-generated

Installation

# Using npx (recommended)
npx cc-e2e init

# Or install globally
npm install -g cc-e2e
cc-e2e init

Usage

Initialize E2E Setup

# Interactive setup
npx cc-e2e init

# Skip prompts with defaults
npx cc-e2e init -y

# Skip documentation templates
npx cc-e2e init --no-docs

Note: Authentication requirements are automatically detected by /e2e:init command in Claude Code, not by CLI options.

Update Existing Setup

# Update all templates
npx cc-e2e update

# Update only commands
npx cc-e2e update --commands-only

# Force overwrite
npx cc-e2e update --force

Add Specific Components

# Add only commands
npx cc-e2e add commands

# Add only configuration
npx cc-e2e add config

# Add documentation templates
npx cc-e2e add docs

# Add coding standard
npx cc-e2e add coding-standard

Two-Phase Setup

This tool uses a two-phase approach: CLI scaffolding followed by Claude Code adaptation.

Phase 1: cc-e2e init (CLI)

Scaffolds auth-neutral template files:

your-project/
├── .claude/
│   ├── commands/e2e/
│   │   ├── init.md             # /e2e:init
│   │   ├── generate.md         # /e2e:generate
│   │   ├── case-generate.md    # /e2e:case-generate
│   │   ├── code-generate.md    # /e2e:code-generate
│   │   ├── qg-case.md          # /e2e:qg-case
│   │   ├── qg-code.md          # /e2e:qg-code
│   │   ├── steering.md         # /e2e:steering
│   │   ├── validate-gap-case.md
│   │   └── validate-gap-code.md
│   ├── e2e-config.md           # Project configuration (auth TBD)
│   └── e2e-test-common.md      # Common rules
├── docs/
│   ├── e2e/
│   │   ├── README.md
│   │   ├── design.md
│   │   ├── progress.md
│   │   ├── histories/          # Test execution history
│   │   ├── quality-checklist.md
│   │   ├── risk-assessment.md
│   │   └── test-cases/
│   │       └── index.md
│   └── coding-standard/
│       └── playwright.md
├── playwright.config.ts        # Playwright configuration (auth-neutral)
└── playwright-tests/
    ├── tests/
    ├── pages/
    ├── fixtures/
    ├── utils/
    ├── .auth/                  # Directory structure (auth TBD)
    └── global-setup.ts         # Placeholder (auth TBD)

Phase 2: /e2e:init (Claude Code)

Analyzes project and adapts configuration with user confirmation:

1. Project Analysis

   • Detects project structure (monorepo, frontend-backend, single package)
   • Detects framework (Next.js, React, Vue, etc.)
   • Detects package manager (pnpm, npm, yarn)
   • Detects authentication requirements (login pages, auth providers, session code)

2. User Confirmation (Required)

   • Displays all detected settings for review
   • User can approve or modify any settings
   • Proceeds only after user confirmation

3. Configuration Generation

   • Customizes playwright.config.ts for the project (adds storageState if auth required)
   • Updates e2e-config.md with confirmed settings
   • Creates .auth.md if auth required
   • Updates global-setup.ts with auth check logic if auth required
   • Appends E2E section to CLAUDE.md if it exists
   • Generates basic Page Objects based on page structure

If authentication is required, these files are created/updated:

your-project/
├── .auth.md                    # Authentication instructions (CREATED)
├── .claude/
│   └── e2e-config.md           # Updated with auth settings
├── CLAUDE.md                   # E2E section appended
├── playwright.config.ts        # Updated with storageState
└── playwright-tests/
    └── global-setup.ts         # Updated with auth check logic

If authentication is NOT required:

• e2e-config.md updated with 認証が必要: false
• CLAUDE.md updated with E2E section (without auth instructions)

Quick Start

After setting up with cc-e2e init and /e2e:init, use the following workflow:

Basic Workflow

When you develop a new feature and want to add E2E tests:

# 1. Run full generation workflow (recommended)
/e2e:generate

This single command runs the complete E2E test generation pipeline:

1. Analyzes your feature and existing test coverage
2. Generates test cases based on requirements
3. Implements test code with browser verification
4. Runs quality gates for both cases and code

Individual Commands

You can also run each step separately:

# Generate test cases only
/e2e:case-generate

# Implement test code only
/e2e:code-generate

# Run tests and update progress
/e2e:steering

Claude Code Commands

After initialization, the following slash commands are available in Claude Code:

| Command | Description | |---------|-------------| | /e2e:init | Analyze project and adapt E2E configuration | | /e2e:generate | Run full E2E generation workflow | | /e2e:validate-gap-case | Analyze missing test cases | | /e2e:validate-gap-code | Analyze missing test code | | /e2e:case-generate | Generate test cases (browser required) | | /e2e:code-generate | Generate test code (browser required) | | /e2e:qg-case | Quality gate for test cases | | /e2e:qg-code | Quality gate for test code | | /e2e:steering | Run tests and update progress |

Browser Verification Required

Important: /e2e:case-generate and /e2e:code-generate require browser verification using Playwright MCP. The commands will:

1. Open the browser and navigate to the application
2. Inspect actual UI elements and data-testid attributes
3. Verify user flows and interactions
4. Generate test cases/code based on real observations

This ensures test cases and code accurately reflect the actual application behavior.

Configuration

After running init, customize .claude/e2e-config.md:

With Authentication:

## Project Configuration

| Setting | Value | Description |
|---------|-------|-------------|
| Dev Server URL | http://localhost:3000 | Base URL for tests |
| Test Directory | playwright-tests/ | Playwright test location |
| Docs Directory | docs/e2e/ | E2E documentation location |
| Dev Server Command | npm run dev | Command to start dev server |
| Build & Start Command | npm run build && npm start | Production build command |

## Authentication

| Setting | Value | Description |
|---------|-------|-------------|
| Auth Required | true | Whether auth is needed |
| Auth Document | .auth.md | Authentication instructions |
| Auth Command | pnpm refresh-auth | Command to refresh auth |
| Auth State Path | playwright-tests/.auth/user.json | Stored auth state |

Without Authentication:

## Project Configuration

| Setting | Value | Description |
|---------|-------|-------------|
| Dev Server URL | http://localhost:3000 | Base URL for tests |
| Test Directory | playwright-tests/ | Playwright test location |
| Docs Directory | docs/e2e/ | E2E documentation location |
| Auth Required | false | This app doesn't require auth |
| Dev Server Command | npm run dev | Command to start dev server |
| Build & Start Command | npm run build && npm start | Production build command |

Authentication Setup

Authentication is automatically detected by /e2e:init based on:

• Login pages (login, signin, auth, etc.)
• Auth providers (NextAuth, Auth0, Firebase Auth, Supabase Auth)
• Session/token management code

If authentication is detected:

1. /e2e:init creates .auth.md with authentication instructions
2. /e2e:init updates playwright.config.ts with storageState
3. /e2e:init updates global-setup.ts with auth check logic
4. Customize .auth.md for your authentication procedure
5. Implement the auth refresh command (e.g., pnpm refresh-auth)
6. The auth state will be stored in playwright-tests/.auth/user.json

If authentication is NOT detected:

• .auth.md will not be created
• global-setup.ts remains a simple placeholder
• Auth-related settings will not appear in e2e-config.md

Best Practices

This tool enforces several best practices:

• Browser verification required - Always verify with actual browser before generating tests
• No retries - Tests should be deterministic
• No waitForTimeout - Use explicit waits instead
• Browser-first testing - API calls only for setup/teardown
• Page Object Model - Separate UI selectors from test logic
• test.step() - Structure complex tests

See docs/coding-standard/playwright.md for detailed guidelines.

Requirements

• Node.js >= 18.0.0
• Claude Code CLI
• Playwright MCP (for browser verification)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT