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)
+```