Initialise with smoke tests for various GeneNetwork services.

The code in this commit was written by claude code, and is yet to be
reviewed. Expect changes once the code has been reviewed.

1 files changed, 92 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..69ba217
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# gn-integration-tests
+
+Integration and end-to-end tests for the GeneNetwork stack
+([gn2](https://github.com/genenetwork/genenetwork2),
+[gn3](https://git.genenetwork.org/genenetwork3),
+[gn-auth](https://git.genenetwork.org/gn-auth)).
+
+Tests run against a live deployment (CD or production) — no mocking, no
+local stack required for the smoke suite.
+
+## Quick start
+
+```sh
+pip install -e .          # or: pip install requests pytest
+pytest -m "smoke"         # run all smoke tests (no credentials needed)
+```
+
+By default tests target **CD** (`cd.genenetwork.org` / `auth-cd.genenetwork.org`).
+Override with environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `GN2_BASE_URL` | `https://cd.genenetwork.org` | genenetwork2 root |
+| `GN3_BASE_URL` | `https://cd.genenetwork.org/api3` | gn3 API proxy path |
+| `GN_AUTH_BASE_URL` | `https://auth-cd.genenetwork.org` | gn-auth server |
+
+To target **production**:
+
+```sh
+GN2_BASE_URL=https://genenetwork.org \
+GN3_BASE_URL=https://genenetwork.org/api3 \
+GN_AUTH_BASE_URL=https://auth.genenetwork.org \
+pytest -m "smoke"
+```
+
+## Test marks
+
+| Mark | Description |
+|---|---|
+| `smoke` | Public endpoints, no credentials, fast |
+| `gn2` | Tests targeting genenetwork2 |
+| `gn3` | Tests targeting the gn3 REST API |
+| `gn_auth` | Tests targeting gn-auth |
+| `auth_flow` | Requires valid test-user credentials (see below) |
+
+Run a specific service:
+
+```sh
+pytest -m "gn_auth and smoke"
+pytest -m "gn3 and smoke"
+pytest -m "gn2 and smoke"
+```
+
+## Auth-flow tests (Phase 2)
+
+Set the following environment variables to enable credential-backed tests:
+
+```sh
+export GN_TEST_EMAIL=testuser@example.com
+export GN_TEST_PASSWORD=secret
+export GN_OAUTH2_CLIENT_ID=<uuid>
+export GN_OAUTH2_CLIENT_SECRET=<secret>
+pytest -m "auth_flow"
+```
+
+Without these variables the `auth_flow` tests are automatically skipped.
+
+## CI integration (planned)
+
+Each component repo's CI triggers only its relevant mark after a successful
+per-repo build:
+
+- genenetwork2 CI → `pytest -m gn2`
+- genenetwork3 CI → `pytest -m gn3`
+- gn-auth CI → `pytest -m gn_auth`
+
+Target: `cd.genenetwork.org` before merges; nightly against production.
+
+## URL structure notes
+
+nginx on the deployment host rewrites `/api3/<path>` → `/api/<path>` before
+proxying to gn3, and gn-auth lives on a separate subdomain:
+
+```
+https://cd.genenetwork.org/          → gn2
+https://cd.genenetwork.org/api3/     → gn3 (/api3/foo → gn3's /api/foo)
+https://auth-cd.genenetwork.org/     → gn-auth
+
+https://genenetwork.org/             → gn2  (production)
+https://genenetwork.org/api3/        → gn3  (production)
+https://auth.genenetwork.org/        → gn-auth (production)
+```