API Contract Governance
Short answer
TestChimp API contract governance answers a question UI coverage alone cannot: which OpenAPI operations and schema fields did our SmartTests actually exercise? Connect your OpenAPI root files, opt in to API payload capture on Playwright runs, then use the APIs surface to see endpoint and field coverage—and turn gaps into issues, new tests, or deliberate ignores.
Why API contract governance matters
Your OpenAPI (or equivalent) spec is the business contract of your product: methods, paths, request shapes, response codes, and fields clients depend on. UI E2E tests often hit those APIs as a side effect—but without a contract lens you cannot tell:
| Failure mode | What goes wrong | Contract governance response |
|---|---|---|
| Happy-path blind spots | Checkout works; error enums, optional filters, and rare response codes never run | Field- and response-code coverage on each operation |
| Spec drift | Traffic hits paths or fields the spec never declared | Spec defined vs observed / undocumented markers |
| Silent API debt | “We have E2E” but whole services have zero covering tests | Operations list with coverage scores and covering-test chips |
| Unowned gaps | Someone notices a hole; nothing is filed or authored | Create issue, Create test, or Ignore gap from the gap itself |
API contract governance is not a separate API testing product—it is the audit and triage layer that turns existing SmartTest traffic into accountable coverage of the contract.
How it works
- Discover the contract — Configure OpenAPI root path(s) from your connected repo. TestChimp parses the specs into services and operations.
- Observe traffic — Run SmartTests with
TESTCHIMP_ENABLE_API_CAPTURE=1(and@testchimp/playwright≥ 0.2.17). Matching HTTP interactions are recorded and uploaded; coverage denormalization runs after batches (and on a periodic sweep). - Measure coverage — The APIs list shows per-operation coverage score, latency, and covering tests. Drill into an operation for request/query/response schema field and response code coverage.
- Govern gaps — From an uncovered operation, field, or response code: file an issue, copy an agent prompt to create/update tests, or ignore the gap when it is intentional.
Open APIs from the main sidebar once OpenAPI roots are configured.
What you get on the surfaces
| Surface | Purpose |
|---|---|
| Setup | OpenAPI roots, capture env, URL filters, payload storage |
| List view | Service picker, coverage summary, searchable/filterable operations table, row-level gap actions |
| Detail view | Per-operation summary, covering tests, request/query/response schema trees, response-code panels, field-level governance |
Governance actions (gaps)
Wherever coverage is missing, TestChimp offers the same decision set:
| Action | When to use |
|---|---|
| Create issue | Track the gap as work—pre-filled title/description with method, path, operation id, and field or response code when applicable |
| Create test | Copy an agent prompt scoped to the operation (or field / response code) for /testchimp create tests |
| Ignore gap | Acknowledge the hole without filing work or authoring tests (intentional out-of-scope, deprecated surface, etc.) |
Use these from the list (operation-level) or the detail page (field- and response-code-level). Details: list view and detail view.
How it fits the rest of TestChimp
- SmartTests produce the traffic; the runtime plugin owns capture.
- Issues receive gap filings via the same Create Issue flow used elsewhere.
- Create tests workflows accept operation-id / field / response-code scopes from the copied prompts.
- Release management remains the ship decision; API contract governance hardens what your automation proved against the API surface—not version sign-off itself.
Related documentation
- Set up API contract governance
- Operations list view
- Operation detail view
- Playwright runtime plugin — API capture
- Create tests
- Issue management
Frequently asked questions
What is API contract governance in TestChimp?
API contract governance maps your OpenAPI operations to real and mocked SmartTest traffic so you can see endpoint and schema-field coverage, then triage gaps with create issue, create test, or ignore gap.
Do I need dedicated API tests?
No. Coverage is inferred from HTTP traffic your SmartTests already generate when API capture is enabled. You can still author dedicated API specs; the governance surface tracks both.
Why is my coverage empty after configuring OpenAPI?
Parsing the spec discovers operations, but scores and covering tests need runs with TESTCHIMP_ENABLE_API_CAPTURE=1 and a recent @testchimp/playwright. Capture is off by default.
What does Ignore gap do?
Ignore gap marks an uncovered operation, field, or response code as intentionally ungoverned for now—without creating an issue or a test—so teams can acknowledge debt without false urgency.
Where do Create test prompts go?
They open a copyable agent prompt scoped to the TestChimp operation id (and optional field or response code), meant for /testchimp create tests or an equivalent agent session.
Know the contract. Cover the edge cases.
Configure OpenAPI roots, enable API capture on SmartTest runs, and triage endpoint and field gaps from the APIs surface—before unaudited branches ship.