AWS Contract Testing

A Serverless Framework project demonstrating how to validate and enforce event contracts between services using AWS Lambda, SQS, and schema validation.
It helps catch breaking changes early and ensures event-driven systems remain reliable and decoupled.

Learn More

You can find a detailed explanation of this project and its concepts in the accompanying article on dev.to:

Preventing Breaking Changes in Event-Driven Systems with Contracts and Validation

The article walks through the reasoning, architecture, and implementation details step-by-step — including event versioning, schema validation, and contract testing using AWS Lambda, SQS, and Zod in TypeScript.

Getting Started

1. Install dependencies

   npm i

2. Run locally

   sls invoke local --function <yourFunctionName>

   Or, if you have a script:

   npm run start

Deploying

Deploy to your AWS account/region from your configured credentials:

sls deploy

Removing the Stack

Tear everything down:

sls remove

Short Explanation

This project shows how to define and validate event contracts in an event‑driven architecture.
By validating message schemas at publish/consume time and in CI, you can catch breaking changes early and keep services autonomous yet safe.

Sample Messages

These examples show how valid and invalid messages look for each version of the contract.
Invalid messages will fail validation at runtime and be retried or sent to the DLQ, depending on your configuration.

Valid v1

A valid v1 message that includes all required fields: id, type, and a properly formatted payload.

{
  "id": "e7b1c37b-7b73-4d84-97a4-dc5a3e91c121",
  "type": "INFO",
  "payload": {
    "title": "Legacy Order Processed",
    "description": "Order completed successfully.",
    "timestamp": "2025-10-28T10:00:00Z"
  }
}

Invalid v1

This message is missing the description field inside payload and will fail validation.

{
  "id": "e7b1c37b-7b73-4d84-97a4-dc5a3e91c121",
  "type": "INFO",
  "payload": {
    "title": "Legacy Order Processed",
    "timestamp": "2025-10-28T10:00:00Z"
  }
}

Valid v2

A valid v2 message with the new version field and optional userEmail included.

{
  "version": "2",
  "id": "a8cb7c7f-93a0-4b24-b15d-63d9289ce9b1",
  "type": "INFO",
  "payload": {
    "title": "User Registered",
    "description": "New user created account.",
    "timestamp": "2025-10-28T10:10:00Z",
    "userEmail": "john@example.com"
  }
}

Invalid v2

This message fails validation because the userEmail field is not a valid email address and the timestamp format is invalid.

{
  "version": "2",
  "id": "a8cb7c7f-93a0-4b24-b15d-63d9289ce9b1",
  "type": "INFO",
  "payload": {
    "title": "User Registered",
    "description": "New user created account.",
    "timestamp": "not-a-date",
    "userEmail": "not-an-email"
  }
}