HTTP Contracts

HTTP steps verify your API surface by making real requests against a base URL and asserting on the response.

Stoney focuses on enforcing invariants — not brittle snapshot testing.

Basic Example

version: 1
feature: core
 
contracts:
  - name: health
    checks:
      - id: health_ok
        says: "Health endpoint must respond with 200 and ok=true"
        steps:
          - http:
              method: GET
              path: /health
            expect:
              status: 200
              json:
                ok: true

Deep Subset Matching

Stoney uses deep subset matching for JSON assertions.

If your API returns additional fields, the contract still passes — as long as the specified subset matches.

Example response:

{
  "ok": true,
  "version": "1.2.3",
  "region": "us-east-1"
}

If your contract specifies only:

json:
  ok: true

The contract passes.

This keeps contracts resilient as systems evolve.

CI Configuration Example

- uses: stoney-dev/stoney@v0
  with:
    base_url: ${{ secrets.STONEY_BASE_URL }}
    suite: "contracts/*.yml"
    retries: "2"
    timeout_ms: "15000"

Best Practices

• Point Stoney at staging unless intentionally validating production.
• Assert only what must never drift.
• Keep contracts focused and readable.

Contracts define intent — not exhaustive test coverage.