Skip to content

Third Party API Integration Test

Write Go integration tests for real third-party API calls using explicit run gates, predictable safeguards, and strong contract assertions.

Scope

  • Validate external API integration end-to-end with real config and real client.
  • Keep tests opt-in by default so normal CI/unit workflows are not blocked.
  • Follow repository style: testify/require, clear skip conditions, bounded timeout.
  • Apply to any third-party API integration.
  • Treat vendor examples (MCS/USS/etc.) as templates, not scope limits.

Scope Validation Gate

Confirm the task targets a third-party vendor API: - Third-party HTTP or gRPC API client → proceed - Internal service/handler (own HTTP server) → redirect to $api-integration-test, STOP - Pure unit test → redirect to $unit-test, STOP - Full end-to-end browser journey → out of scope, inform user, STOP

Hard stop: If the target is not a third-party vendor API, 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.

Required Pattern

  1. Keep file name as <client>_integration_test.go in the same package directory.
  2. Add both build constraints at file top (for backward compatibility):
  3. //go:build integration (Go 1.17+)
  4. // +build integration (Go <1.17 compat)
  5. Add explicit run gate env var (example: THIRDPARTY_INTEGRATION=1 or vendor-specific gate), otherwise t.Skip(...).
  6. Validate required runtime env vars up front (for example: ENV, CONFIG_DIR, target IDs/label IDs).
  7. Block production by default:
  8. if ENV resolves to prod/production, t.Skip unless INTEGRATION_ALLOW_PROD=1.
  9. Parse and validate env var payloads:
  10. Always strings.TrimSpace before comparison or use
  11. Use strconv.ParseInt for numeric IDs
  12. Split comma-separated lists and validate each element
  13. Log parsed values at t.Logf level for debugging
  14. Load runtime config via project config loader (config.MustLoad()).
  15. Build real third-party client with production code path.
  16. Use context.WithTimeout(...) to prevent hanging requests.
  17. Use bounded retry policy only when justified:
  18. default: no retry
  19. if enabled: max 1-2 retries, bounded backoff, no infinite loop
  20. Execute real API call and assert both:
  21. protocol-level contract (status/code/required response fields)
  22. business-level invariant (identifier consistency, semantic constraints)
  23. For expected failure paths, assert explicit error type/code (not only require.Error).
  24. Define test data lifecycle explicitly:
  25. setup source, idempotency key strategy, cleanup or safe reuse policy.

Configuration Gate (Mandatory)

Before generating or updating test code, apply the shared gate in: - references/common-integration-gate.md

Vendor-Specific Safety Additions

  1. Prefer idempotent endpoints for default integration flows.
  2. For mutation endpoints, require dedicated test tenant/account and explicit opt-in gate.
  3. Keep retry policy bounded; avoid hidden infinite retries in tests.
  4. Validate rate-limit behavior when relevant:
  5. Assert rate-limit response headers when available (X-RateLimit-Remaining, Retry-After)
  6. If test triggers rate-limit, classify failure as "rate-limit" not "contract"
  7. Never log secrets/tokens in assertions or failure output.
  8. Refuse production environment by default.

Safety Rules

  • Use dedicated test tenant/account identifiers only.
  • Prefer idempotent or low-risk API operations.
  • Never hardcode secrets/tokens in test source.
  • Skip test when required env vars are missing instead of failing local pipelines.
  • Keep timeout strict (for example 10-30s) and avoid unbounded retries.
  • Refuse ENV=prod unless explicit override is provided.

Execution

Use vendor-specific run commands documented in: - references/vendor-examples.md

Output Contract

Use the shared output contract in: - references/common-output-contract.md

References (Load Selectively)

  1. Always read: references/common-integration-gate.md — gate design and skip message quality. Shared with $api-integration-test.
  2. Always read: references/common-output-contract.md — structured report format. Shared with $api-integration-test.
  3. Read if authoring new tests or triaging failures: references/checklists.md
  4. Read if no vendor pattern exists in the repo: references/vendor-examples.md — generic template and run commands