# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Playwright end-to-end testing project for SmartDocs 360, a cloud-based entity and document management platform. The project includes specialized agents for test planning, generation, and healing.

## Commands

### Running Tests
```bash
# Run all tests
npm test

# Run tests in headed mode (visible browser)
npm run test:headed

# Run tests in UI mode (interactive)
npm run test:ui

# Debug tests with step-through debugging
npm run test:debug

# Show HTML test report
npm run report
```

### Running Individual Tests
```bash
# Run a specific test file
npx playwright test tests/smartdocs-login.spec.ts

# Run tests matching a pattern
npx playwright test tests/**/entity*.spec.ts

# Run a specific test by title
npx playwright test -g "verify successful login"
```

## Architecture

### Test Structure

**Fixtures (`tests/fixtures/auth.ts`)**: Custom Playwright fixtures that handle authentication flow with SSO and TOTP. The `loggedInPage` fixture provides a fully authenticated page object to tests, encapsulating the login process with automatic 30-second minimum test duration to satisfy TOTP constraints.

**Seed Test (`tests/seed.spec.ts`)**: The foundational test that performs login and navigates to the entities list page. This is used as the starting point for specialized agents.

**Utility Functions (`tests/utils/`)**:
- `totp.ts`: Generates 6-digit TOTP codes from Base32-encoded secrets using HMAC-SHA1
- `dismiss-splash-page.ts`: Handles optional splash page dismissal after login

### Configuration

**Playwright Config (`playwright.config.ts`)**: Configured with:
- Test directory: `./tests`
- Base URL: `http://localhost:3000` (override for UAT testing)
- Single worker for sequential test execution (TOTP constraint)
- Chromium browser only
- HTML reporter
- Trace on first retry

### Specialized Agents

**Planner Agent (`.claude/agents/playwright-test-planner.md`)**: Creates comprehensive test plans by exploring web applications. Navigates through the interface, maps user flows, and generates detailed test scenarios with step-by-step instructions.

**Generator Agent (`.claude/agents/playwright-test-generator.md`)**: Converts test plans into executable Playwright tests. Reads test plan specifications, manually executes each step using Playwright tools, and generates spec files with proper test structure and comments.

**Healer Agent (`.claude/agents/playwright-test-healer.md`)**: Debugs and fixes failing tests systematically. Runs tests, investigates failures using snapshots and browser tools, identifies root causes, and updates test code to resolve issues.

## Authentication Flow

Tests use SSO authentication with TOTP (Time-based One-Time Password):
1. Navigate to SSO login page
2. Enter username and password
3. Wait for MFA page
4. Generate and submit TOTP code
5. Wait for redirect to entities page
6. Dismiss splash page if present

**TOTP Constraint**: Tests must maintain a minimum 30-second duration between TOTP code generations to prevent reuse failures. This is enforced by the `testStartTime` fixture.

## Test Writing Guidelines

- Always use the `loggedInPage` fixture from `tests/fixtures/auth.ts` for authenticated tests
- Reference `tests/seed.spec.ts` as the seed file in test plans and generated tests
- Include step descriptions as comments before each test action
- Place generated tests in the `tests/` directory with descriptive filenames
- Wrap tests in `test.describe()` blocks matching the top-level test plan item
- Generator agent must read TESTING-RULES.md if present for project-specific patterns
