VigilQA Docs

API Contract

Consumer-driven contract tests that catch breaking API changes before they reach consumers.

What this module tests

The API Contract module generates and runs contract tests that verify your API's response structure, field types, and schema stability across releases. Unlike functional tests that assert on specific values, contract tests assert on the shape of responses — ensuring that changes to your API don't silently break consumers.

Tests cover:

  • Required field presence in all response shapes
  • Field type stability (no unexpected type changes between releases)
  • Enum value stability (no removal of existing enum values)
  • HTTP status code stability for documented request patterns
  • Breaking change detection: removed fields, renamed fields, type narrowing

How contract tests are generated

During the initial pipeline run, AppExplorer samples your API endpoints and records the response shapes as baseline contracts. ScriptGen generates tests that assert against these contracts. On subsequent runs, any deviation from the baseline is flagged as a potential breaking change.

If you have an OpenAPI or Swagger spec, upload it in Project Settings → API Spec. The spec is used as the authoritative contract baseline, producing more rigorous contract tests.

Baseline management

Contract baselines are versioned. When you intentionally change your API (adding a new field, changing a response shape as part of a feature), you update the baseline from the Contracts tab in the project dashboard:

  1. Navigate to Project → Contracts
  2. Review the detected changes (added fields, removed fields, type changes)
  3. Approve the changes you intended and reject the ones you didn't
  4. The approved changes become the new baseline for future runs

Non-breaking additions (new optional fields, new endpoints) do not fail contract tests by default. Only removals, type changes, and required-field additions are flagged as breaking. This behaviour can be adjusted in Project Settings → Contract Strictness.

KB scenario format for contract tests

# Contract scenario example
domain: orders-api
scenarios:
  - id: ORD-CONTRACT-001
    title: "GET /orders/{id} response shape is stable"
    module: api_contract
    endpoint: /api/v1/orders/{id}
    method: GET
    steps:
      - Send GET to /api/v1/orders/{id} with a valid order ID
    expected: >
      HTTP 200.
      Response body includes: id (string/UUID), status (string enum: pending/processing/shipped/delivered/cancelled),
      created_at (ISO 8601 datetime), total_amount (number), line_items (array).
      Each line_item includes: product_id (string), quantity (integer), unit_price (number).