> ## Documentation Index
> Fetch the complete documentation index at: https://engineering.unkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration tests

> Testing components with real dependencies

## When to use integration tests

Use integration tests to cover behavior across service boundaries, real databases, caches, and storage. These tests catch failures that mocks miss.

## Container patterns

Use `pkg/testutil/containers` for isolated, per-test containers. Helpers register cleanup with `t.Cleanup` immediately after creating a container, so failed readiness checks don't leak resources. Run tests that use these helpers through Bazel so schema runfiles are available.

```go theme={"theme":"kanagawa-wave"}
redisURL := containers.Redis(t)
```

## Test harness

Use `pkg/testutil` when you need a full service graph and seeded data:

```go theme={"theme":"kanagawa-wave"}
h := testutil.NewHarness(t)
workspace := h.CreateWorkspace()
```

## Bazel sizing

Integration tests that start containers must use `size = "large"`. Shared-container tests can use `size = "medium"`.

## Debugging failures

Use verbose output for failing tests:

```bash theme={"theme":"kanagawa-wave"}
bazel test //pkg/vault/integration:integration_test --test_output=all
```