---
name: add-integration-test-user
description: Guide for adding a new integration test user — creating the AWS Secrets Manager secret in terraform-infra and wiring it into tests (Python or Node.js)
---

# Adding a New Integration Test User

## Overview

Integration tests that call real services authenticate as a real Auth0 user. When you need a new test identity (e.g. a user with a specific role like `seat_can_administer_users`), you need to:

1. **Create the Auth0 user** manually (out of band — not automated here).
2. **Provision the AWS secret** in `terraform-infra` so the test runner can retrieve the credentials at runtime.
3. **Populate the secrets** with the correct values — done by the human, not the agent.
4. **Configure the Jenkinsfile** to assume the IAM role terraform created, so CI can read the secrets.
5. **Wire the secret into the tests** using the appropriate library for your language.

---

## Step 1: Add the secret to terraform-infra

See [`references/terraform-infra.md`](references/terraform-infra.md) for full instructions, including:

- How to add a secret to an existing `qa/<service>/integration-test/` directory (Case A)
- How to create the directory from scratch with `main.tf` and `variables.tf` templates (Case B)

---

## Step 2: Populate the secrets (you, not the agent)

See [`references/populate-secrets.md`](references/populate-secrets.md) for the exact JSON shapes required for `*_AUTH0_CREDENTIALS` and `*_USER_CREDENTIALS`.

> Secret values must never pass through the agent. Populate them manually in the AWS console or CLI after the terraform PR is merged.

---

## Step 3: Configure the Jenkinsfile to assume the integration test IAM role

See [`references/jenkinsfile-iam-role.md`](references/jenkinsfile-iam-role.md) for how to wire the `withAWS` step to the role terraform created. The role name is deterministic — it is `qa-<service-name>-integration-test-role`, derived directly from the `service_name` variable in `variables.tf`.

---

## Step 4: Wire the secret into tests

### Node.js

See [`references/wire-tests-nodejs.md`](references/wire-tests-nodejs.md) for how to install `@theorchard/backend-jwtauth-testing`, configure global setup to share tokens across test suites, and use `loginFromSecretsManager` in tests.

### Python

See [`references/wire-tests-python.md`](references/wire-tests-python.md) for how to install `jwtauth[testing]` and use the `generate_bearer_token` fixture via the pytest plugin.

---

## Checklist

- [ ] terraform-infra: Add secret name(s) to `secrets_manager_secret_names` in `variables.tf`
- [ ] terraform-infra: Merge and confirm terraform apply runs successfully
- [ ] **You (not the agent)**: Populate `*_AUTH0_CREDENTIALS` in Secrets Manager with `{"auth0_client_id": "...", "auth0_client_secret": "..."}`
- [ ] **You (not the agent)**: Populate `*_USER_CREDENTIALS` in Secrets Manager with `{"email": "...", "password": "...", "otp_secret_key": "...or null"}`
- [ ] Jenkinsfile: Add `withAWS` wrapping the integration test step using `qa-<service-name>-integration-test-role`
- [ ] Service repo: Add constants for the new test user (secret names, identity UUID)
- [ ] Service repo: Write the test using the correct token fetch pattern (Node.js or Python)
- [ ] Verify integration tests pass in CI before merging

## Reference PRs

| PR | What it shows |
|---|---|
| theorchard/terraform-infra#26688 | Minimal terraform change: add one secret to an existing integration test module (graphql-user) |
| theorchard/terraform-infra#25404 | Full bootstrap: create integration-test terraform module from scratch for a new service |
| theorchard/graphql-user#728 | Node.js integration test adding a second test user |