api-integration-test

name	api-integration-test
description	Create, maintain, and run gated Go integration tests for internal APIs and service-to-service clients (HTTP/gRPC). Use for endpoint verification, contract checks with real runtime config, opt-in execution, timeout/retry safety, and integration failure triage in Go services.
allowed-tools	Read, Write, Grep, Glob, Bash(go test*), Bash(go build*), Bash(make*)

API Integration Test

Goal

Build production-representative, opt-in integration tests for internal APIs with strict safety controls, reproducible execution, and clear failure diagnosis.

When To Use

Trigger this skill when the user asks for:

• Internal API integration tests (HTTP or gRPC)
• Service-to-service adapter tests requiring real runtime config
• Internal endpoint contract verification against real responses
• Integration test failure triage or debugging

Scope

Use this skill for:

1. Internal HTTP API integration tests.
2. Internal gRPC client/server integration tests.
3. Service-to-service adapter tests requiring real runtime config.
4. Internal endpoint contract verification against real responses.

Do not use this skill for:

1. Pure unit tests with heavy mocks — use $unit-test.
2. Full end-to-end browser journeys.
3. Third-party vendor API tests — use $thirdparty-api-integration-test.

Mandatory Gates

Gates execute in strict serial order. Any gate failure blocks all subsequent steps.

1) Scope        2) Go Version   3) Config       4) Mode
   Validation ──→  Gate       ──→  Completeness ──→  Selection
   │               │               │                │
   out of scope?   read go.mod    Full/Scaffold/   auto-select
   → stop+redirect → adapt        Blocked?         Smoke/Std/Comp
                                   Blocked → STOP
        │               │               │                │
        5) Production   6) Execution    7) Reference
           Safety     ──→  Integrity  ──→  Loading
           │               │               │
           ENV=prod?       actually ran?   load by trigger
           → t.Skip        → report        pattern

1) Scope Validation Gate

Confirm the task falls within this skill's scope:

• Internal HTTP or gRPC API → proceed
• Pure unit test → redirect to $unit-test, STOP
• Third-party vendor API → redirect to $thirdparty-api-integration-test, STOP
• Full end-to-end browser journey → out of scope, inform user, STOP

Hard stop: If the target is out of scope, the entire remaining workflow is skipped. Output only: (1) scope verdict, (2) recommended skill or approach, (3) reason. Do NOT generate test code, do NOT proceed to subsequent gates.

2) Go Version Gate

Read go.mod for the project's Go version. Adapt patterns:

Feature	Minimum Go	Adaptation
t.Setenv	1.17	Below: use os.Setenv + t.Cleanup
context.WithTimeout (no leak)	all	Always defer cancel()
Range var capture fix	1.22	Below 1.22: copy loop variable in closures
t.Parallel() + t.Setenv safe	1.24	Below 1.24: do NOT combine in same subtest

If go.mod is not found, state Go version: unknown and use the most conservative patterns.

3) Configuration Completeness Gate

Apply references/common-integration-gate.md and determine degradation level:

Level	Condition	Action
Full	All env vars documented, service address known	Proceed to generate complete tests
Scaffold	Some env vars missing	Generate test with t.Skip(...) + // TODO: markers. State what is missing in output.
Blocked	Gate env var unknown or service address undetermined	STOP. Output only: variable checklist + example command + setup instructions.

Never hardcode guessed endpoints, credentials, or identifiers to make tests look runnable.

4) Execution Mode Gate

Auto-select mode based on task signals, then state the selection in output:

Signal	→ Mode
User says "smoke", "connectivity check", "health check"	Smoke
First-time environment validation	Smoke
Single endpoint, read-only operation	Smoke
User says "full", "comprehensive", "release gate"	Comprehensive
Post-migration or new service onboarding	Comprehensive
≥ 5 endpoints or security-sensitive API (auth/payment/PII)	Comprehensive
User says "review", "audit", "improve", "upgrade" existing tests	Standard (unless explicit mode requested)
Everything else	Standard (default)

If the user explicitly requests a specific mode, use that mode regardless of signals.

5) Production Safety Gate

• If ENV resolves to prod or production, the generated test must t.Skip unless INTEGRATION_ALLOW_PROD=1.
• For destructive operations (DELETE, UPDATE, DROP), require additional gate: INTEGRATION_ALLOW_DESTRUCTIVE=1.

6) Execution Integrity Gate

Never claim tests were executed unless they actually ran.

• If go test -tags=integration was not run, output:
  • Not run
  • reason (e.g., service unreachable, env vars missing)
  • exact command to reproduce
• Do not imply pass/fail for tests that did not execute.
• Never report PASS when tests were actually skipped.

7) Load References Selectively

Always load:

• references/common-integration-gate.md — before authoring or determining degradation level.
• references/common-output-contract.md — before reporting results.

Load on condition:

• references/checklists.md — only when authoring new tests or triaging failures.
• references/internal-api-patterns.md — only when writing HTTP/gRPC test code (not for scope rejection or result reporting).
• references/advanced-patterns.md — only when Comprehensive mode, CI integration, httptest adapter tests, or test data lifecycle management.

Execution Modes

Smoke (connectivity check)

• Test 1 key endpoint per service — the simplest read-only call.
• Timeout: 5s. No retry.
• Assert only: connectivity + HTTP 200/gRPC OK + non-empty response.

Standard (default)

• Cover primary endpoints: at least 1 success path + 1 expected-failure path per endpoint.
• Timeout: 15s. Max 1 retry for transient failures only.
• Assert both protocol-level and business-level outcomes.

Comprehensive (full coverage)

• Cover all endpoints + error paths + boundary conditions.
• Timeout: 30s. Max 2 retries with bounded backoff.
• Include: concurrent request safety, large payload, pagination, rate limiting.

Required Test Pattern

1. Use file name <domain>_integration_test.go near the client/package under test.
2. Add build constraint at file top:
   • //go:build integration
   • // +build integration
3. Enforce explicit run gate env var (for example INTERNAL_API_INTEGRATION=1), otherwise t.Skip.
4. Validate all required env vars at test start and provide actionable skip message.
5. Block production by default:
   • if ENV resolves to prod/production, t.Skip unless INTEGRATION_ALLOW_PROD=1.
6. Parse and validate env var payloads where needed (strconv, strings.TrimSpace, list parsing).
7. Build real client instance (or real handler + httptest server) through production code path.
8. Guard each external call with context.WithTimeout.
9. Use bounded retry policy only when justified:
   • default: no retry
   • if enabled: max 1-2 retries, bounded backoff, no infinite loop
10. Assert both:
    • protocol-level contract (HTTP status / gRPC code / required response fields)
    • business invariants (identity mapping, state transitions, key numeric constraints)
11. For expected failure paths, assert failure type/code explicitly (not only require.Error).
12. Keep tests idempotent and avoid destructive operations by default.
13. Define test data lifecycle explicitly:
    • setup source, idempotency key strategy, cleanup or safe reuse policy.

Anti-Examples — DO NOT Write These Tests

1. Mocking the client you are integrating against — if you replace http.Client or the gRPC connection with a fake, it is a unit test, not an integration test. The entire point is to exercise the real transport path.

2. Asserting on unstable response fields — timestamps, request IDs, trace IDs, and randomly-ordered lists change per call. Assert on identity/contract fields, not volatile metadata.

   // BAD
   require.Equal(t, "2026-03-08T12:00:00Z", resp.CreatedAt)
   // GOOD
   require.False(t, resp.CreatedAt.IsZero())
   

3. Creating data with no cleanup strategy — writing to a service that has no delete/archive API without documenting the data lifecycle leaves garbage that eventually breaks the test environment.

4. Unbounded or unconditional retry loops — retrying every error hides real failures. See references/internal-api-patterns.md §Retry/Timeout Policy Pattern for bounded retry with transient error classification.

5. Testing internal implementation details — asserting on the number of DB rows, internal cache state, or internal RPC call counts rather than the API's observable response contract.

6. Running destructive operations without explicit opt-in — DELETE /users/:id or DROP TABLE in a test without a separate env gate (e.g., INTEGRATION_ALLOW_DESTRUCTIVE=1) risks production data.

7. Treating integration tests as performance benchmarks — a single-call latency measurement has no statistical significance. Use dedicated load testing tools for performance.

8. Ignoring context cancellation in retry loops — always check ctx.Done() before sleep in retry loops. See references/internal-api-patterns.md §Retry/Timeout Policy Pattern.

Go Implementation Baseline

//go:build integration
// +build integration

func TestUserProfileIntegration(t *testing.T) {
    if os.Getenv("INTERNAL_API_INTEGRATION") != "1" {
        t.Skip("set INTERNAL_API_INTEGRATION=1 to run")
    }

    env := strings.ToLower(strings.TrimSpace(os.Getenv("ENV")))
    if (env == "prod" || env == "production") && os.Getenv("INTEGRATION_ALLOW_PROD") != "1" {
        t.Skip("refuse prod by default: set INTEGRATION_ALLOW_PROD=1 to override")
    }

    cfgDir := strings.TrimSpace(os.Getenv("CONFIG_DIR"))
    userID := strings.TrimSpace(os.Getenv("TEST_USER_ID"))
    if env == "" || cfgDir == "" || userID == "" {
        t.Skip("set ENV, CONFIG_DIR, TEST_USER_ID to run")
    }

    cfg := config.MustLoad()
    client, err := NewInternalClient(cfg.InternalAPI)
    require.NoError(t, err)

    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()

    // Success path: protocol-level + business-level assertions
    resp, err := client.GetUserProfile(ctx, userID)
    require.NoError(t, err)
    require.NotNil(t, resp)
    require.Equal(t, http.StatusOK, resp.StatusCode)
    require.Equal(t, userID, resp.Body.UserID)
    require.NotEmpty(t, resp.Body.DisplayName)
}

func TestUserProfile_NotFound_Integration(t *testing.T) {
    if os.Getenv("INTERNAL_API_INTEGRATION") != "1" {
        t.Skip("set INTERNAL_API_INTEGRATION=1 to run")
    }
    // ... env gates same as above ...

    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()

    // Expected failure path: assert specific error, not just require.Error
    resp, err := client.GetUserProfile(ctx, "nonexistent-user-id-000")
    require.NoError(t, err) // HTTP call succeeded
    require.Equal(t, http.StatusNotFound, resp.StatusCode)
}

For Scaffold mode pattern (tests with t.Skip + // TODO: markers for missing config), see references/common-integration-gate.md §Scaffold Mode Example.

Safety Rules

1. Never hardcode secrets, tokens, or private endpoints.
2. Use dedicated test tenant/account data.
3. Prefer read-only or reversible operations; explicitly gate destructive flows.
4. Refuse production environment by default.
5. Keep timeout bounded (typically 5-30s) and retries strictly limited.
6. Skip with actionable instructions when prerequisites are missing.

Execution Commands

# Smoke mode
INTERNAL_API_INTEGRATION=1 ENV=dev CONFIG_DIR=/path/to/config TEST_USER_ID=123 \
  go test -tags=integration ./internal/pkg/client/user -run Integration -v -timeout=30s

# Standard mode (default)
INTERNAL_API_INTEGRATION=1 ENV=dev CONFIG_DIR=/path/to/config TEST_USER_ID=123 \
  go test -tags=integration ./internal/pkg/client/user -run Integration -v -timeout=120s

# Comprehensive mode
INTERNAL_API_INTEGRATION=1 ENV=dev CONFIG_DIR=/path/to/config TEST_USER_ID=123 \
  go test -tags=integration ./internal/pkg/client/user -run Integration -v -timeout=300s -count=1

Output Contract

Use the shared output contract:

• references/common-output-contract.md Load always when reporting results.

CI Integration

Check if the project already has a Makefile with integration test targets (e.g., make test-api-integration). If so, align with existing targets rather than adding new ones. Cross-reference $go-makefile-writer when Makefile targets should be added or repaired.

Integration tests in CI require service dependencies. For GitHub Actions service containers, Makefile targets, and Docker Compose patterns, see references/advanced-patterns.md §CI Execution Pattern.