thirdparty-api-integration-test

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 the host repository's existing style — its assertion library (testify/require, testify/assert, or stdlib t.Fatalf), its config loader, and its test-package convention. The examples below use testify/require and config.MustLoad() as one common shape; mirror what the repo already does rather than importing a new dependency. Clear skip conditions and a bounded timeout are required regardless.
• Apply to any third-party API integration.
• Treat vendor examples (MCS/USS/etc.) as templates, not scope limits.
• The NON-NEGOTIABLE parts are the safety gates (run gate, prod/host/account fail-closed checks, destructive gating, bounded budget, ID/URL redaction) — not the choice of assertion or config library.

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 package the repo uses for tests (same package, or its _test external package — match the surrounding convention). Name each integration test function with an Integration marker (e.g. TestStripe_CreateCharge_Integration): the runner refuses to report success unless at least one …Integration test actually PASSED, which keeps a plain unit test from masquerading as a passed integration run (override the marker via VENDOR_TEST_NAME_MATCH).
2. Add both build constraints at file top (for backward compatibility):
   • //go:build integration (Go 1.17+)
   • // +build integration (Go <1.17 compat)
3. Add explicit run gate env var (example: THIRDPARTY_INTEGRATION=1 or vendor-specific gate), otherwise t.Skip(...).
4. Validate required runtime env vars up front (ENV, CONFIG_DIR, the API base URL, the vendor test account, target IDs). When the run gate is set but a required var is missing/empty, t.Fatalf — do NOT t.Skip (see §Skip vs Fail (CI Integrity)).
5. Block production/live vendor targets by ENV and by resolved host and account (never ENV alone):
   • refuse if ENV is prod/production, OR the base-URL host is not on the explicit sandbox allowlist (VENDOR_SANDBOX_HOSTS), OR the vendor account is not a designated test account (VENDOR_TEST_ACCOUNTS) — unless INTEGRATION_ALLOW_PROD=1. When the gate is set, this refusal is t.Fatalf, not t.Skip. Use requireVendorIntegration (§Go Implementation Baseline).
6. Parse and validate env var payloads:
   • Always strings.TrimSpace before comparison or use
   • Use strconv.ParseInt for numeric IDs
   • Split comma-separated lists and validate each element
   • Log only non-sensitive parsed values at t.Logf; mask identifiers with maskID and never log secrets/tokens (raw account/customer/tenant/target IDs are sensitive)
7. Load runtime config via the project's existing config loader (e.g. config.MustLoad() — use whatever the repo already uses; do not introduce a new config mechanism for the test).
8. Build real third-party client with production code path.
9. Use context.WithTimeout(...) to prevent hanging requests.
10. Use bounded retry policy only when justified:

• default: no retry
• if enabled: max 2 retries (3 total attempts), bounded backoff, no infinite loop. Rate-limit (429/Retry-After) retries count toward this same budget — getHonoringRateLimit is called with maxRetries=2.

1. Execute real API call and assert both:

• protocol-level contract (status/code/required response fields)
• business-level invariant (identifier consistency, semantic constraints)

1. For expected failure paths, assert explicit error type/code (not only require.Error).
2. Define test data lifecycle explicitly:

• setup source, idempotency key strategy, cleanup or safe reuse policy.