State assumptions

Record:

  • API and specification version or access date;
  • client-library version;
  • authentication method;
  • test environment and account;
  • rate and data limits;
  • operations with side effects; and
  • safe cleanup procedure.

The OpenAPI Specification defines a machine-readable interface description. A generated client can still be wrong when the description is stale, incomplete, or interpreted differently from runtime behavior.

Build a recorded contract fixture

For one representative operation, preserve sanitized examples of:

  • method, path, query, and required headers;
  • request body after serialization;
  • status code and response headers;
  • success body;
  • documented error body; and
  • pagination or continuation state.

Do not commit access tokens or personal data. If a recording contains sensitive fields, replace them deterministically and document the sanitization.

Run eight behavior cases

Case Expected evidence
Valid success Runtime response passes explicit parsing
Invalid credential Authentication failure is classified, not retried forever
Missing permission Authorization failure is distinct from absence
Invalid input Field-level error reaches the caller safely
Pagination No item is skipped or duplicated across boundaries
Rate limit or transient failure Retry follows provider and HTTP semantics
Repeated mutation Idempotency policy prevents unintended duplicate effect
Contract drift Unknown or missing required fields produce a visible failure

The IETF's HTTP Semantics specification defines method properties and status semantics. It does not supply a provider's retry or idempotency contract; verify those in the provider's documentation and observed test behavior.

Parse at runtime

Treat the network response as untrusted input. Validate fields required by the business operation before using them:

function parseCreatedRecord(value) {
  if (!value || typeof value.id !== "string") {
    throw new Error("API contract failure: missing string id");
  }
  return { id: value.id };
}

This illustrative parser is deliberately small and untested here. A production schema should capture the actual contract without silently discarding fields needed for security, pagination, or correctness.

Isolate side effects

Use a sandbox when available. Generate a unique test identifier, assert the remote result, repeat the request according to the intended retry behavior, and clean up. If no sandbox exists, use a read-only operation until the team has an approved low-impact mutation plan.

Never let the agent select production credentials merely because the local fixture passes.

Define failure and recovery

Fail release when:

  • runtime parsing rejects a required response;
  • permission failures are collapsed into empty data;
  • retries can duplicate a business effect;
  • pagination loses or repeats records;
  • logs expose credentials or payloads; or
  • cleanup cannot identify the test artifacts.

Recovery may disable the integration, restore the previous client version, pause a worker, or reconcile duplicated remote records. Record which action is safe before release.

The integration is demonstrated only for the tested operations, account, versions, and failure cases. Everything else remains environment-specific.