Integration Test Runner

Runs integration tests package-by-package with caching, resume, and structured output.

bash

go run ./cmd/tools/integration run [flags] [filter...]

Or via task runner:

bash

task test:integration

Flags

Flag	Description
`--output-dir`	Directory for test output (default: `.integration/<timestamp>`)
`--clean`	Ignore cache, start a fresh run
`--debug`	Enable debug logging to stderr
`--race`	Enable race detector (sets `CGO_ENABLED=1`)
`--unit`	Run all tests, not just integration tests
`--cover-profile`	Generate coverage profile per package (`.cov` files)

--output-dir and --clean are mutually exclusive.

Positional arguments are substring filters on package paths:

bash

go run ./cmd/tools/integration run kafka redis

Features

Pause/Resume -- The runner automatically resumes from the latest run directory. Tests that already passed or were skipped are excluded via -skip regex. Use --clean to force a fresh run.
Error Links -- Failed tests include a direct file:line reference to the output log (e.g. FAIL TestFoo (0.5s) -> .integration/20260326094101/kafka.txt:42), allowing immediate navigation to the failure context.
Subtest Compaction -- When all subtests of a parent pass, they are collapsed into a single parent entry. When any subtest fails, all subtests are shown individually so failures remain visible.
Timeout Detection -- Tests that start (=== RUN) but never finish (--- PASS/FAIL/SKIP) are detected as timed out and reported as failures with an error link.
Per-Package Timeout -- Each package in packages.json can specify a custom timeout field. Default is 5 minutes.
Docker Cleanup -- Testcontainers are removed between packages to prevent resource leaks. Skipped in CI environments.
Race Detection -- The --race flag enables Go's race detector with CGO_ENABLED=1 set automatically.

Output Directory

All state is stored under .integration/:

.integration/
  20260326094101/         # timestamped run directory
    index.md              # Markdown index with structured results
    kafka.txt             # raw go test JSON output per package
    redis.txt
    aws-s3.txt

On resume, the runner picks the latest timestamped directory and appends new results to existing output files. Line numbers in error links remain stable across resumes.

Package List

The list of packages and their timeouts is defined in packages.json.