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 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 _integration_test.go in the same package directory.
2. Add both build constraints at file top (for backward compatibility):

• //go:build integration (Go 1.17+)
• // +build integration (Go <1.17 compat)

1. Add explicit run gate env var (example: THIRDPARTY_INTEGRATION=1 or vendor-specific gate), otherwise t.Skip(...).
2. Validate required runtime env vars up front (for example: ENV, CONFIG_DIR, target IDs/label IDs).
3. Block production by default:

• if ENV resolves to prod/production, t.Skip unless INTEGRATION_ALLOW_PROD=1.

1. 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 parsed values at t.Logf level for debugging

1. Load runtime config via project config loader (config.MustLoad()).
2. Build real third-party client with production code path.
3. Use context.WithTimeout(...) to prevent hanging requests.
4. Use bounded retry policy only when justified:

• default: no retry
• if enabled: max 1-2 retries, bounded backoff, no infinite loop

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.

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:

• Assert rate-limit response headers when available (X-RateLimit-Remaining, Retry-After)
• If test triggers rate-limit, classify failure as "rate-limit" not "contract"

1. Never log secrets/tokens in assertions or failure output.
2. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: johnqtcg
• Source: johnqtcg/awesome-skills
• License: MIT
• Homepage: https://johnqtcg.github.io/awesome-skills/

Install and usage instructions live in the source repository linked above.