# Thirdparty Api Integration Test

> Create and run gated Go integration tests for third-party APIs with real external calls, strict configuration gates, bounded timeouts, and safe runtime controls. Use for vendor/client contract verification and failure triage.

- **Type:** Skill
- **Install:** `agentstack add skill-johnqtcg-awesome-skills-thirdparty-api-integration-test`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [johnqtcg](https://agentstack.voostack.com/s/johnqtcg)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [johnqtcg](https://github.com/johnqtcg)
- **Source:** https://github.com/johnqtcg/awesome-skills/tree/main/skills/thirdparty-api-integration-test
- **Website:** https://johnqtcg.github.io/awesome-skills/

## Install

```sh
agentstack add skill-johnqtcg-awesome-skills-thirdparty-api-integration-test
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)
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 (for example: `ENV`, `CONFIG_DIR`, target IDs/label IDs).
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:
   - 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
7. Load runtime config via project config loader (`config.MustLoad()`).
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 1-2 retries, bounded backoff, no infinite loop
11. Execute real API call and assert both:
   - protocol-level contract (status/code/required response fields)
   - business-level invariant (identifier consistency, semantic constraints)
12. For expected failure paths, assert explicit error type/code (not only `require.Error`).
13. 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"
5. Never log secrets/tokens in assertions or failure output.
6. 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](https://github.com/johnqtcg)
- **Source:** [johnqtcg/awesome-skills](https://github.com/johnqtcg/awesome-skills)
- **License:** MIT
- **Homepage:** https://johnqtcg.github.io/awesome-skills/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-johnqtcg-awesome-skills-thirdparty-api-integration-test
- Seller: https://agentstack.voostack.com/s/johnqtcg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.