app-api-contract-testing

Cross-App API Contract Testing

When this app calls another app via Gate AppApisApi.callAppApi(...), it becomes a consumer that depends on the provider operation behaving a certain way. A contract captures that expectation. Contracts are authored and validated locally, then verified centrally (public-api → Gate runs the real provider call) — there is no local runtime verification command.

A contract is identified by providerAppId + operationId — the business contract is the provider operation, not the HTTP transport.

When to do this (during app development)

• After adding or changing a callAppApi(...) dependency in runtime code.
• Before relying on a provider, or after a provider you depend on is upgraded (run verify-consumer).
• Before shipping a change to an app other apps call (run verify-provider to catch every dependent consumer org-wide).

Prerequisites

• fusebase auth --api-key=<id>.<key> (an API key is required).
• orgId/productId in fusebase.json, and the app configured with a path.
• The cross-app-api-calls-analysis flag (already enabled — this skill is only present when it is).

Workflow

# 1. Discover dependencies — scans runtime TS for callAppApi(...) and writes
#    fusebaseAppApiDependenciesMeta into fusebase.json
fusebase analyze app-apis --feature <appId>

# 2. Scaffold draft contracts from the resolved callsites
fusebase app-api-contracts scaffold --app <appId>
#    → drafts are bare { "expect": { "status": 200 } } with input inferred from
#      the call payload. EDIT them into real assertions (see "Contract files").
#    Existing *.contract.json files are SKIPPED (your edits are safe); only missing
#    ones are created. Pass --force to overwrite existing files back to fresh
#    drafts (discards your edits).

# 3. Validate offline — structure + that each contract maps to a real dependency.
#    No provider call.
fusebase app-api-contracts validate --app <appId>

# 4. Publish the validated set to central storage (full replacement, idempotent;
#    aborts and uploads nothing if any contract is invalid)
fusebase app-api-contracts publish --app <appId>

# 5. Verify centrally against the live provider
fusebase app-api-contracts verify-consumer --app <appId>          # this app's contracts
fusebase app-api-contracts verify-provider --app <providerAppId>  # org-wide inbound check