Gitea-Tools/tests/integration/README.md

Opt-in Gitea Integration Tests (#66)

Real-Gitea integration tests for the shared API client (gitea_auth.api_request / api_get_all). Skipped by default — the unit suite (pytest tests/ -q) stays fast, mocked, and network-free.

What they prove

Against a real, disposable Gitea instance:

• issue listing + pagination (multi-page walk, overall limit)
• PR listing through the same paginated client
• targeted label add/remove (one label removed, others untouched)
• permission denial fails closed (bad token → clear 401 error, token never echoed)
• real Gitea error payloads surface as safe, redacted RuntimeErrors

Environment variables

Variable	Meaning
GITEA_INTEGRATION=1	opt-in switch — the suite is skipped without it
GITEA_INTEGRATION_URL	base URL (default http://localhost:3003)
GITEA_INTEGRATION_TOKEN	API token for the local test instance

Never point these at a production Gitea and never use production tokens. The token is used only in the Authorization header; tests assert it does not appear in any error output.

Quick start (Docker)

tests/integration/gitea-integration up
export GITEA_INTEGRATION_TOKEN="$(tests/integration/gitea-integration token)"
GITEA_INTEGRATION=1 ./venv/bin/python -m pytest tests/integration/ -q
tests/integration/gitea-integration down

• Image is pinned (gitea/gitea:1.22.6 in docker-compose.yml); bump the pin deliberately, never :latest.
• up waits until /api/v1/version answers (60s timeout).
• token idempotently creates a TEST-ONLY admin (inttest-admin) inside the container and prints a fresh API token to stdout — nothing is written to disk.
• down removes the container and its volume (full teardown).

An existing local Gitea works too: set GITEA_INTEGRATION_URL and a token for any account allowed to create/delete its own repos.

Seed data and cleanup

• Each session creates one uniquely-named repo (inttest-<8 hex>), seeds issues/labels/one PR inside it, and deletes the repo on teardown (best-effort; a leaked repo is disposable and obvious).
• Nothing outside the seed repo is touched; the suite never mutates pre-existing repos, users, or instance settings.

Relationship to the unit suite

Unit tests remain the default and must stay mocked. Add an integration test only for behavior that genuinely depends on a real server (pagination metadata, permission semantics, live error payloads).