# Set up TestPerch

Connect this repository's Playwright suite, enable AI test selection for pull
requests, and verify a real test run.

Use the [OpenAPI reference](/api/public/v1/openapi.json) for endpoints,
authentication, request fields, and recovery behavior. Send requests to the origin
serving this guide. Adapt the setup to the repository using your usual tools.

## 1. Understand the existing setup

Inspect the Playwright configuration, package manager, CI workflows, and repository
identity. Reuse existing TestPerch configuration, credentials, and saved onboarding.
Ask when the intended suite or workspace is unclear, or authorized access is
missing. Missing credentials are not a reason to create another trial.

## 2. Create or resume access

For a new setup, use the onboarding API to create a workspace and project with
names based on the repository. Save the exact request before sending it so an
interrupted attempt can recover the same workspace. Retry that saved request;
retries do not extend access or reopen an expired onboarding.

Keep credentials and recovery state private, durable, and outside version control.
Never print secrets or include them in commits or messages. The credentials have
separate purposes:

- The ingestion key sends Playwright results through the reporter.
- The project API key reads and configures the project.
- The claim secret authorizes temporary onboarding operations.

## 3. Configure the project

Identify the long-lived branches that actually run tests. Use the project APIs to
create a branch environment for each, plus a separate pull-request environment for
each tested target branch. PR patterns match the target branch. Use exact branch
matches, enable AI selection for PR environments, and keep branch runs as
full-suite baselines.

Reuse existing environments and preserve always-run tags and custom guidance.
Resolve conflicting choices with the person and flag CI distinctions the matching
rules cannot represent, such as regions or manual deployment targets.

For new onboarding, start the GitHub connection flow and share its authorization
link. Continue reporter setup while approval is pending, following the API's next
action. Once connected, map the exact repository through the project API. Existing
workspaces connect GitHub through their workspace settings. Check AI readiness;
configuration alone does not prove selection is working.

## 4. Connect Playwright

Install `@testperch/playwright` with the repository's package manager and add
`testPerchReporter` alongside its existing reporters. Use the installed package's
README and types for reporter options. Preserve the existing Playwright and CI
behavior.

Provide the ingestion key through `TESTPERCH_API_KEY` and the guide's origin through
`TESTPERCH_URL`. Ensure the test process loads them; the reporter does not load env
files. Use private local configuration or authorized CI secrets.

## 5. Verify a real run

Run the repository's test command locally, or use CI when local execution is
impractical. Track that exact invocation: a saved UUIDv7 reporter run ID locally,
or the CI provider, build ID, and attempt in CI. Use the run and diagnostics APIs
to confirm executed tests and delivered results, accounting for all jobs and
shards. Failed tests can still verify the integration; pending ingestion cannot.

If execution or delivery is blocked, report what remains and retain enough state
to resume. Verify AI selection on an eligible pull-request run before claiming it
works.

## 6. Hand back the result

Return the results link, test outcome, AI readiness, and any remaining actions.
For an unclaimed workspace, create a browser handoff to the verified run and share
its short-lived link with the claim deadline. The person claims ownership through
signup or login; existing owners use the normal results link.

New workspaces have **7 days and $1 in shared AI credit**. Claiming preserves the
setup. The person then completes Stripe Checkout, with no card required, to start
a **14-day trial with $5 in shared AI credit**, just like manual setup. Claiming
alone does not activate the trial. Canceled or failed Checkout can resume from
the workspace’s trial setup page without recreating the workspace. Paid upgrade
is a separate decision.

Ask before committing or opening a PR.
