# CLAUDE.md

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

## Purpose

This repo stores Jenkinsfiles for scheduled test pipelines that run on cron schedules and/or trigger off upstream project builds. It is owned by `@theorchard/qa-automation-team`.

## Repository Structure

- `playwright/prod/Jenkinsfile.<feature>` — One Jenkinsfile per feature area for Playwright E2E prod tests
- `playwright/qa/Jenkinsfile.<feature>` — QA environment pipeline variants (no `configEnvironment` param, different Slack channels)

## Jenkinsfile Pattern

All Jenkinsfiles follow the same structure and delegate to `playwrightTests()` from the `jenkins-global-libraries` shared library. The key variables per pipeline are:

- **Trigger**: `cron(...)` schedule, optionally with `upstream(upstreamProjects: ...)` to also run on upstream builds
- **TAGS**: Playwright tag filter (e.g. `@collaborators_prod`, `@songwhip_app_prod`)
- **configEnvironment**: `'prod'` for prod pipelines, omitted (defaults to `'qa'`) for QA pipelines
- **slackNotificationChannels**: Additional Slack channels beyond the always-notified `#playwright-test-e2e-results`

### `playwrightTests()` parameters

| Parameter | Default | Description |
|---|---|---|
| `tags` | *(required)* | Playwright tag expression to filter tests |
| `configEnvironment` | `'qa'` | App environment under test — `'qa'` or `'prod'` |
| `frameworkEnvironment` | `'prod'` | Environment for the test framework itself |
| `runtimeEnvironment` | `'lambda'` | Execution runtime — `'lambda'` or `'ecs'` (for long-running suites) |
| `branchName` | `'*/master'` | Branch of `playwright-tests` repo to check out; `PR-123` triggers PR fetch |
| `frameworkRunnerTag` | `'latest'` | ECR tag for the `framework-runner` Docker image |
| `githubUser` | `'theorchard'` | GitHub org owning the `playwright-tests` repo |
| `reportSuffix` | `''` | Suffix for report name and workspace dir — required when running multiple steps in one pipeline |
| `slackNotificationChannels` | `[]` | Extra Slack channels to notify on failure/recovery |
| `envVars` | `[:]` | Additional key/value env vars injected into the container (see below) |
| `pnpmSetupScriptName` | `''` | Setup script to run in the container before tests |

### `envVars` reference

| Variable | Description |
|---|---|
| `TRACE` | Playwright trace mode: `"on"`, `"off"`, `"on-first-retry"`, `"on-all-retries"` (default) |
| `USE_DYNAMIC_THROTTLING` | `"true"` to limit concurrent feature file execution (large suites hitting Lambda/ECS limits) |
| `MAX_CONCURRENT_FEATURES` | Hard cap on concurrent features; only used when `USE_DYNAMIC_THROTTLING=true` |
| `BASE_URL_OVERRIDE_<APPNAME>` | Override base URL for a specific app (e.g. `BASE_URL_OVERRIDE_OA`). Supported app names: `FANSIFTER`, `INSIGHTS`, `WORKSTATION`, `OA`, `DOCUMENTS`, `ABACUS`, `COLLABORATORS`, `CONTENT`, `DISTRIBUTION`, `PUBLISHING`, `MONEYHUB`, `SETTINGS`, `AUTH` |
| `TEST_WISE` | Set to `"false"` to skip real TransferWise payment processing in collaborator payment tests |
| `TASK_REVISION` | Pin ECS task definition revision (e.g. `"42"`); only applies when `runtimeEnvironment: 'ecs'` |
| `DEBUG` | Set to `"true"` to enable verbose `[DEBUG]`-prefixed framework log output |

## Adding a New Pipeline

Requires changes to **two repos** (merge this repo first):

1. Create `playwright/prod/Jenkinsfile.<feature>` here following existing patterns
2. In `theorchard/jenkins-config`, add the feature name to the `playwrightProdFeatures` list in `pipeline.theorchard.io/jobs/standalonePipelines.groovy` — the loop auto-generates a job named `<feature>-e2e-prod-tests-pipeline`