Skip to content

README.md

Latest commit

 

History

History
129 lines (94 loc) · 4.44 KB

README.md

File metadata and controls

129 lines (94 loc) · 4.44 KB

Quick Start Async: Contract Testing Against a Real Event Processor

This lab shows why async contract testing matters in real teams: producers and consumers often deploy independently, and schema drift in event payloads can break workflows silently. Here, the AsyncAPI contract is the shared source of truth, and Specmatic catches drift before release.

Objective

Run an async contract test against a real Kafka-based provider, observe the intentional failure, fix the provider implementation, and verify a passing run.

Time required to complete this lab

10-15 minutes (first run can take longer if Docker images are not cached locally).

Prerequisites

  • Docker Desktop (or Docker Engine + Compose v2) is installed and running.
  • You are in labs/quick-start-async-contract-testing.
  • Port 9092 is free (required for Kafka in this lab).
  • Ports 9000 and 9001 are free (required for Studio).

Files in this lab

  • .specmatic/repos/labs-contracts/asyncapi/quick-start/async.yaml - AsyncAPI contract (source of truth for this lab)
  • service/processor.py - Provider implementation with one intentional mismatch
  • specmatic.yaml - Specmatic async test configuration
  • docker-compose.yaml - Kafka, provider service, test runner, and optional Studio
  • create-topics.sh - Kafka topic bootstrap script used by kafka-init

Learner task

Fix the provider so the emitted response event matches the contract's allowed status values.

Lab Rules

  • Do not edit: the specs in .specmatic/repos/labs-contracts/asyncapi/quick-start/async.yaml
  • Do not edit: specmatic.yaml, docker-compose.yaml.
  • Edit only: service/processor.py.
  • If your baseline run unexpectedly passes, reset service/processor.py so process_message returns "status": "STARTED" before continuing.

Architecture mental model (before you run)

  • Consumer under test: Specmatic test runner (contract-test service).
  • Provider under test: Python processor (provider service).
  • Flow:
    1. Specmatic publishes an event/message to Kafka topic new-orders.
    2. Provider consumes that event, transforms payload, and emits to wip-orders.
    3. Specmatic validates emitted payload and headers against .specmatic/repos/labs-contracts/asyncapi/quick-start/async.yaml.

Intentional failure (baseline run)

From this folder, run:

docker compose up contract-test --build --abort-on-container-exit

Expected failure signal:

  • Contract test fails due to a mismatch in the provider's response event payload.
  • Failure points to status, where actual is "STARTED" and expected is one of the enum values in the contract (including "INITIATED").
Tests run: 1, Successes: 0, Failures: 1, Errors: 0

Then clean up:

docker compose down -v

Fix path

Open service/processor.py and update process_message:

From:

"status": "STARTED",

To:

"status": "INITIATED",

Pass criteria

Re-run:

docker compose up contract-test --build --abort-on-container-exit

Expected pass signal:

Tests run: 1, Successes: 1, Failures: 0, Errors: 0

Then clean up:

docker compose down -v

Run the same suite in Studio

Start Studio:

docker compose --profile studio up studio --build

Open Studio, load specmatic.yaml, and click Run Suite.

Also inspect the loaded contract in the left sidebar by opening .specmatic/repos/labs-contracts/asyncapi/quick-start/async.yaml.

Stop Studio stack:

docker compose --profile studio down -v

Troubleshooting (common beginner blockers)

  • port is already allocated:
    • Free 9092, 9000, and 9001, then retry.
  • kafka-init fails with shell/script errors on Windows:
    • Ensure shell scripts are checked out with LF line endings (create-topics.sh must not contain CRLF).
  • Test exits before provider is ready:
    • Re-run once; services are health-gated, but first image pull/startup can be slow.

What you learned

  • Async contract testing validates event-driven behavior against AsyncAPI contracts.
  • Contract failures provide precise mismatch diagnostics (rule code + field path).
  • Keeping the contract stable while fixing provider behavior is a practical producer-side workflow.
  • Specmatic gives actionable mismatch feedback for event payloads and headers.

Next step

If you are doing this lab as part of an eLearning course, return to the eLearning site and continue with the next module.