{"id":29640817,"url":"https://github.com/specmatic/specmatic-kafka-avro-sample","last_synced_at":"2025-07-21T21:06:07.298Z","repository":{"id":295773286,"uuid":"987447704","full_name":"specmatic/specmatic-kafka-avro-sample","owner":"specmatic","description":"Sample project to demonstrate how specmatic-kafka can be used to run contract tests against an async application where Avro Schema Registry is being used","archived":false,"fork":false,"pushed_at":"2025-07-18T10:32:05.000Z","size":102571,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-18T13:35:06.337Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/specmatic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-21T05:04:42.000Z","updated_at":"2025-07-18T10:32:09.000Z","dependencies_parsed_at":"2025-05-27T10:27:59.218Z","dependency_job_id":"851f4824-4b79-4ae8-b0d7-5a964f42a7a7","html_url":"https://github.com/specmatic/specmatic-kafka-avro-sample","commit_stats":null,"previous_names":["znsio/specmatic-kafka-avro-sample","specmatic/specmatic-kafka-avro-sample"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/specmatic/specmatic-kafka-avro-sample","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-kafka-avro-sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-kafka-avro-sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-kafka-avro-sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-kafka-avro-sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/specmatic","download_url":"https://codeload.github.com/specmatic/specmatic-kafka-avro-sample/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-kafka-avro-sample/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266379363,"owners_count":23920159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-21T21:06:04.933Z","updated_at":"2025-07-21T21:06:07.282Z","avatar_url":"https://github.com/specmatic.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contract Testing with AsyncAPI \u0026 Avro Schema Registry\n\n\u003e **Leveraging your Avro schema files by referencing them from AsyncAPI spec to test your event-driven microservices**\n\n## Overview\n\nThis sample demonstrates **contract-first development** for asynchronous microservices communication. It showcases how to implement reliable contract testing using AsyncAPI specifications with Avro Schema Registry integration.\n\n## Architecture\n\n![Architecture Diagram](avro-sample-architecture.png)\n\n#### TODO: AsyncAPI spec in middle with reference to schema registry, need a test architecturre diagram also\n\nThe application demonstrates a typical order processing flow between `checkout-service` and `order-service` communicating through Kafka topics with Avro serialization.\n\n## Key Benefits \n\n#### TODO: Maybe push this to the end or remove it altogether, we need to get to running tests quickly after orienting users or architecture\n\n### 🎯 Contract-First Development\n- **AsyncAPI 3.0 specification** captures the API contract in an unambiguous mutually understood industry standard format\n- **Schema Registry integration** ensures that provider, consumer teams and everyone involved are referring to single source of truth\n- **Automated contract testing** ensure service implementations adhere to API contract\n\n### 🔄 Schema Evolution Management\n- **Avro schemas** provide backward compatibility\n- **Multi-format schema support** in AsyncAPI specifications\n- **Dynamic schema references** to Schema Registry endpoints\n\n### 🚀 Production Confidence\n- **Automated validation** catches breaking changes early\n- **Type-safe messaging** with generated POJOs\n- **End-to-end testing** with real infrastructure\n\n## AsyncAPI Specification Highlights\n\n### Referencing your existing Avro files your schema registry in AsyncAPI spec\n\nThe AsyncAPI specification that this application is based on reuses the Avro schemas by referencing them instead of redefining them again. \nThis ensures that we have a single source of truth for the schemas which is the schemas present in the schema registry.\n\n```yaml\ncomponents:\n  messages:\n    OrderRequest:\n      name: OrderRequest\n      title: An order request\n      payload:\n        schemaFormat: 'application/vnd.apache.avro+json;version=1.9.0'\n        schema:\n          $ref: 'http://localhost:8085/subjects/new-orders-value/versions/1/schema'\n```\n\n### Key Benefits:\n- **Live schema references** - Always uses current registry schemas\n- **No schema duplication** - Single source of truth\n- **Runtime validation** - Ensures spec-to-implementation consistency\n\n## Schema Management\n\n### Schema Organization\n```\nsrc/main/avro/\n├── NewOrders.avsc          # Order creation events\n├── WipOrders.avsc          # Work-in-progress updates\n├── OrdersToCancel.avsc     # Cancellation requests\n└── CancelledOrders.avsc    # Cancellation confirmations\n```\n\n### Registration Process\nSchemas are automatically registered during test setup via `register-schemas.sh` script, ensuring tests run against the actual schema registry.\n\n## Contract Testing Strategy\n\n### What Gets Tested:\n- **Message publishing** to correct topics\n- **Schema compatibility** with registry\n- **Consumer behavior** on message receipt\n- **Error handling** for malformed messages\n\n## Quick Start\n\n### Prerequisites\n- Java 17+\n- Docker \u0026 Docker Compose\n\n### Run Contract Tests Programmatically\n```bash\n# 1. Pull dependencies\ndocker compose pull\n\n# 2. Execute contract tests\n./gradlew clean test\n```\n\nYou can also run the [contract test](src%2Ftest%2Fkotlin%2Fcom%2Fexample%2Forder%2FContractTest.kt) from your IDE using the play button once you've pull all the required images.\nThe contract test makes use of `testcontainers` to set up the environment for testing.\n\n#### Test Configuration\nThe test requires the following properties to be set with the correct values as you can see in the [contract test](src%2Ftest%2Fkotlin%2Fcom%2Fexample%2Forder%2FContractTest.kt).\n```properties\nSCHEMA_REGISTRY_URL=http://localhost:8085\nSCHEMA_REGISTRY_KIND=CONFLUENT\nAVAILABLE_SERVERS=localhost:9092\n```\n\n### Run Contract Tests using Docker CLI\n\n#### Run the application \n```bash\n# 1. Pull dependencies\ndocker compose pull\n\n# 2. Run the dependencies\ndocker compose up -d\n\n# 3. Run the application\n./gradlew bootRun\n```\n\n#### Run the contract tests\nWait for the application to start and then run the following command to execute the contract tests using Specmatic:\n\n```bash\ndocker run --network avro-app-network \\\n       -v \"$PWD/specmatic.yaml:/usr/src/app/specmatic.yaml\" \\\n       -v \"$PWD/api-specs:/usr/src/app/api-specs\" \\\n       -v \"$PWD/build:/usr/src/app/build\" \\\n       --rm specmatic/specmatic-kafka:1.0.1 test \\\n       --broker=broker:9093 \\\n       --schema-registry-url=http://schema-registry:8085 \\\n       --schema-registry-kind=CONFLUENT\n```\n\n#### Stop the application\nStop the application by stopping the `./gradle bootRun` process using Ctrl + C\n\n#### Stop the containers \n```bash\ndocker compose down -v\n```\n\n## Business Impact\n\n### Development Benefits\n- **Catch integration issues early** - Before they reach production\n- **Reduce debugging time** - Type-safe contracts eliminate guesswork\n- **Confident deployments** - Automated validation prevents failures\n\n### Technical Benefits\n- **Schema evolution safety** - Backward compatibility validation\n- **Runtime consistency** - Specs match actual implementation\n- **Automated testing** - No manual contract verification needed\n\n## Why This Matters\n\nTraditional integration testing often misses **contract compatibility issues** that only surface in production. This approach ensures:\n\n1. **Services communicate correctly** - Validated message formats\n2. **Schema changes don't break consumers** - Compatibility testing\n3. **Deployments are safe** - Contract validation in CI/CD\n4. **Documentation stays current** - Living contracts via AsyncAPI\n\n---\n\n**Ready to implement contract testing in your microservices?** This sample provides the complete foundation for production-ready contract testing with AsyncAPI and Avro Schema Registry.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecmatic%2Fspecmatic-kafka-avro-sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspecmatic%2Fspecmatic-kafka-avro-sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecmatic%2Fspecmatic-kafka-avro-sample/lists"}