# Live-Gitea integration tests

These tests run against a throwaway Gitea 28.1.0 started in Docker. They are
opt-in: without `AEGIS_INTEGRATION=1` every test here is skipped and Docker is
never touched, so the default `uv run pytest` stays fast.

```bash
AEGIS_INTEGRATION=1 uv run pytest tests/integration -m integration -v
```

An integration-only run covers little of `src/`, so the unit-test coverage gate
is lowered to 0 for runs that collect nothing but `tests/integration`. If Docker
is unavailable while `AEGIS_INTEGRATION=1` is set, the session fails with a clear
message instead of skipping.

## What the harness does

- Image: `GITEA_IMAGE` in `harness.py` (digest-pinned, single constant).
- One container and one network per run, both named `aegis-it-<8 hex>`.
  No host bind mounts, no image builds, no `docker prune`.
- Gitea is configured through `GITEA__section__KEY` env vars (sqlite3,
  `INSTALL_LOCK`, random `SECRET_KEY`/`INTERNAL_TOKEN`/OAuth2 JWT secret,
  Actions, packages and OAuth2 enabled, mailer off, webhook allowed host list
  `*`, `MAX_RESPONSE_ITEMS=50`).
- Readiness: polls `GET /api/v1/version` for up to 90 s. On failure the last 100
  log lines of the container are written to stderr.
- Seeding: admin `aegis-admin` (random password) via `gitea admin user create`,
  plus a full-scope token. All data is fake and random per run. Passwords and
  tokens are kept out of `repr` and error messages.
- Cleanup: `docker rm -f -v <container>` and `docker network rm <net>` from the
  session fixture finalizer, an `atexit` hook, and SIGTERM/SIGHUP handlers.

## Reachability modes

1. Local (default): a free loopback port is chosen, published as
   `127.0.0.1:<port>:3000`, and `ROOT_URL` is set to match. Base URL
   `http://127.0.0.1:<port>`.
2. CI (`AEGIS_IT_NETWORK_MODE=container`): for test runs inside a job container
   that shares the host Docker socket. No port is published. Gitea joins the
   per-run network, the job container (`$HOSTNAME`) is connected to the same
   network with `docker network connect`, and tests reach Gitea at
   `http://aegis-it-<id>:3000`. On cleanup the job container is disconnected
   again before the network is removed.

## Fixtures and helpers

- `gitea` (session): a `GiteaInstance` with `base_url`, `admin_login`,
  `admin_token`, `api(method, path, token=None, **kw)` (defaults to the admin
  token, `anonymous=True` sends no credentials), `create_user`, `mint_token`,
  `create_org`, `create_repo`, `unique`.
- `regular_user` (session): non-admin user with its own full-scope token.
- `unique_name` (function): a unique name derived from the test name.