Ilia Denisov
126 lines
5.1 KiB
Markdown
126 lines
5.1 KiB
Markdown
# 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
|
|
├── authsessionmail/
|
|
│ ├── authsession_mail_test.go
|
|
│ └── harness_test.go
|
|
├── gatewayauthsessionmail/
|
|
│ ├── gateway_authsession_mail_test.go
|
|
│ └── harness_test.go
|
|
├── 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
|
|
├── redis_container.go
|
|
├── smtp_capture.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`.
|
|
- `authsessionmail` verifies the integration boundary between real `Auth / Session Service` and real `Mail Service`.
|
|
- `gatewayauthsessionmail` verifies the public auth flow across real `Edge Gateway`, real `Auth / Session Service`, and real `Mail 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 still use one isolated `miniredis` instance plus either
|
|
real downstream processes or external stateful HTTP stubs where appropriate.
|
|
`authsessionmail` and `gatewayauthsessionmail` are the deliberate exceptions:
|
|
they use one real Redis container through `testcontainers-go`, because those
|
|
boundaries must exercise the real Redis-backed `Mail Service` runtime.
|
|
`authsessionmail` additionally contains one targeted SMTP-capture scenario for
|
|
the real `smtp` provider path, while `gatewayauthsessionmail` keeps `Mail
|
|
Service` in `stub` mode and extracts the confirmation code through the trusted
|
|
operator delivery surface.
|
|
|
|
## Running
|
|
|
|
Run from the module directory:
|
|
|
|
```bash
|
|
cd integration
|
|
go test ./gatewayauthsession/...
|
|
go test ./authsessionuser/...
|
|
go test ./authsessionmail/...
|
|
go test ./gatewayauthsessionmail/...
|
|
go test ./gatewayuser/...
|
|
go test ./gatewayauthsessionuser/...
|
|
```
|
|
|
|
Useful regression commands after boundary changes:
|
|
|
|
```bash
|
|
go test ./gatewayauthsession/...
|
|
go test ./authsessionuser/...
|
|
go test ./authsessionmail/...
|
|
go test ./gatewayauthsessionmail/...
|
|
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`.
|
|
|
|
## Real Redis Suites
|
|
|
|
Fast suites stay on `miniredis` by default.
|
|
When one boundary explicitly needs real Redis semantics, prefer a package-local
|
|
container setup through `testcontainers-go` plus reusable helpers in
|
|
`internal/harness`, as done by `authsessionmail` and
|
|
`gatewayauthsessionmail`.
|
|
|
|
Current rule of thumb:
|
|
|
|
- use `miniredis` when the boundary does not depend on Redis persistence or
|
|
scheduling behavior
|
|
- use `testcontainers-go` only when the real Redis process materially changes
|
|
the behavior being verified
|