# 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 testing framework with TypeScript that uses BDD (Behavior-Driven Development) with Gherkin feature files. The project tests multiple web applications using a modular architecture.

## Essential Commands

### Development Commands

- `pnpm bddgen` - Generate Playwright `.spec` files from BDD Gherkin feature files (required before running tests)

### Running Tests Locally (Makefile)

- `make test <file>` - Generate BDD specs and run a specific test file
- `make test TAGS="<tag>"` - Run tests matching a tag (supports multiple: `TAGS="@tag1 or @tag2"`)
- `make debug <file>` - Same as `make test` but with `PWDEBUG=1` for Playwright Inspector
- `make debug TAGS="<tag>"` - Run tagged tests with Playwright Inspector
- `make help` - List all available make targets

Examples:

```bash
make test .features-gen/features/abacus/abacusContract2.feature.spec.js
make test .features-gen/features/abacus/abacusContract2.feature.spec.js:51
make test TAGS="@id_ee732b50acbed8c72ede09e0530355fa9dd4f0dadbb95962149847f742c1fa71"
make test TAGS="@qa_smoke or @qa_regression"
make debug TAGS="@id_ee732b50acbed8c72ede09e0530355fa9dd4f0dadbb95962149847f742c1fa71"
```

### Quality Commands

- `pnpm lint:fix` - Fix linting issues
- `pnpm format:fix` - Fix formatting

## Architecture Overview

### BDD Structure

- Feature files in `features/` are written in Gherkin syntax
- `pnpm bddgen` generates corresponding `.spec.ts` files in `.features-gen/`
- Step definitions are in `src/bdd-steps/`
- Tests use `playwright-bdd` to compile Cucumber/Gherkin .feature files into Playwright tests

### App Modularization

The codebase is organized around multiple applications, each with its own:

- **App Factory**: `src/apps/{appName}/index.ts` - creates app instances
- **Requests**: `src/apps/{appName}/requests.ts` - request interception helpers
- **Queries**: `src/apps/{appName}/queries.ts` - app-specific database queries
- **Pages**: `src/pages/{appName}/` - Page Object Model classes
- **Steps**: `src/bdd-steps/{appName}/` - app-specific step definitions
- **Types**: `src/types/{appName}.ts` - app-specific TypeScript types
- **Fixtures**: `src/fixtures/{appName}/` - app-specific Fixtures
- **Components**: `src/components/{appName}/` - app-specific Components

Current apps: auth, fansifter, insights, workstation, oa, documents, abacus, collaborators, content, distribution, publishing, moneyhub, settings.

### Test Execution

- Uses Playwright BDD configuration in `playwright.config.ts`
- Parallel execution framework in `framework/src/`
- Local test reports are written to `playwright-report/` (HTML report + trace files)

### Key Files

- `src/playwright-bdd.ts` - Main test fixtures and BDD setup
- `src/context.ts` - Test context management
- `src/apps/index.ts` - App factory registry
- `src/utils/database.ts` - Database client setup
- `playwright.config.ts` - Playwright configuration
- `framework/` - Contains execution scripts for parallel runs, AWS Lambda, ECS

## Development Workflow for New Features or Tests

1. Create or extend page objects in `src/pages/{appName}/` following existing patterns (use components in `src/components/solfege` if applicable)
2. Add app-specific logic to respective `src/apps/{appName}/` folders
3. Implement step definitions in `src/bdd-steps/{appName}/` (before adding new steps, check if similar steps already exist in app steps folder or in common steps in `src/bdd-steps/` to avoid duplication)
4. Write feature files in `features/` using Gherkin syntax
5. Run `pnpm bddgen` to generate test specs and validate step definitions