# Integration Tests

`integration` owns only true inter-service black-box tests.
Each suite must raise real service processes, speak only over public HTTP/gRPC/Redis contracts, and avoid imports from `internal/...` packages of tested services.

## Layout

```text
integration/
├── README.md
├── authsessionuser/
│   ├── authsession_user_test.go
│   └── harness_test.go
├── gatewayauthsession/
│   ├── harness_test.go
│   └── gateway_authsession_test.go
├── gatewayauthsessionuser/
│   ├── gateway_authsession_user_test.go
│   └── harness_test.go
├── gatewayuser/
│   ├── gateway_user_test.go
│   └── harness_test.go
├── go.mod
├── go.sum
└── internal/
    ├── contracts/
    │   ├── gatewayv1/
    │   │   └── contract.go
    │   └── userv1/
    │       └── contract.go
    └── harness/
        ├── binary.go
        ├── keys.go
        ├── mail_stub.go
        ├── process.go
        └── user_stub.go
```

## Rules

- Keep suites black-box. Do not import `galaxy/gateway/internal/...`, `galaxy/authsession/internal/...`, or any other service-owned internal package.
- Start real binaries from `cmd/...` and talk to them only through their published HTTP, gRPC, and Redis contracts.
- Put boundary-specific orchestration and assertions into the owning suite package, not into shared helpers.
- Put only generic process/runtime utilities into `internal/harness`.
- Put only public-contract helpers into `internal/contracts/...`.

## Current Boundary Suites

- `gatewayauthsession` verifies the integration boundary between real `Edge Gateway` and real `Auth / Session Service`.
- `authsessionuser` verifies the integration boundary between real `Auth / Session Service` and real `User Service`.
- `gatewayuser` verifies the direct authenticated self-service boundary between real `Edge Gateway` and real `User Service`.
- `gatewayauthsessionuser` verifies the full public-auth plus authenticated-account chain across real `Edge Gateway`, real `Auth / Session Service`, and real `User Service`.

The current fast suites use one isolated `miniredis` instance plus either
real downstream processes or external stateful HTTP stubs where appropriate.

## Running

Run from the module directory:

```bash
cd integration
go test ./gatewayauthsession/...
go test ./authsessionuser/...
go test ./gatewayuser/...
go test ./gatewayauthsessionuser/...
```

Useful regression commands after boundary changes:

```bash
go test ./gatewayauthsession/...
go test ./authsessionuser/...
go test ./gatewayuser/...
go test ./gatewayauthsessionuser/...
cd ../gateway && go test ./...
cd ../authsession && go test ./... -run GatewayCompatibility
cd ../user && go test ./...
```

Do not use `go test ./...` from the repository root. The repository is organized through `go.work`, so verification should stay module-scoped.

## Adding A New Boundary Suite

1. Create `integration/<boundary>/` for the new inter-service boundary.
2. Keep suite-local fixtures, scenario helpers, and assertion helpers inside that package.
3. Reuse `internal/harness` only for generic concerns such as binary build/run, ports, keys, Redis, and shared external stubs.
4. Add new helpers to `internal/contracts/<contract>/` only when they describe a reusable public wire contract.
5. Prefer fast deterministic infrastructure by default: in-memory test doubles, `httptest` stubs, and `miniredis`.

## Future Real Redis Smoke Suites

Fast suites stay on `miniredis` by default.
When a boundary needs one real Redis smoke suite later, keep it in the same boundary package and gate it explicitly with environment-driven configuration such as `INTEGRATION_REAL_REDIS_ADDR`.
That smoke suite should complement, not replace, the deterministic `miniredis` coverage.