Architect a domain event testing strategy with snapshot fixtures, contract tests, and…
- User
Architect a domain event testing strategy with snapshot fixtures, contract tests, and golden assertions.
Assistant
The user wants a comprehensive testing strategy for "domain events" in software architecture. Key components requested:
- Snapshot fixtures: Storing the state of an event at a specific point in time to compare against future runs.
- Contract tests: Ensuring the event adheres to a specific schema or structure (producer/consumer agreement).
- Golden assertions: Similar to snapshot testing but often implies comparing specific output against a "golden" master file to ensure consistency.
The strategy needs to be architectural, meaning it should define how to test these events across the system, not just provide code snippets.
1. Understanding Domain Events:
- They represent something that happened in the domain.
- They are immutable (usually).
- They drive communication between bounded contexts (microservices) or within a monolith.
2. Deconstructing the Strategy:
-
Phase 1: The Unit Level (The Event Class)
- We need to ensure the event class holds data correctly.
- Technique: Golden Assertions / Snapshots. If I create an
UserRegisteredevent, serialize it to JSON, it should look exactly like this known "golden" JSON file.
-
Phase 2: The Publishing/Producer Level (Integration)
- We need to ensure the domain logic actually emits the event when a state change occurs.
- Technique: Spies/Mocks or an in-memory event bus collector.
-
Phase 3: The Schema/Contract Level (Interop)
- Different services consume these events. They need to agree on the shape.
- Technique: Contract Testing (Pact, AsyncAPI, or Schema Registry).
- Specifics: Snapshotting the schema (e.g., Avro, JSON Schema) to prevent breaking changes.
-
Phase 4: The Consumer Level (Side Effects)
- When a consumer reads the event, does it do the right thing?
- Technique: Contract tests (consumer side) + Integration tests.
3. Refining the Concepts requested:
- Snapshot Fixtures: This sounds like taking a concrete instance of an event and saving it as a fixture for tests. "Here is a valid
OrderPlacedevent." - Contract Tests: Schema validation + Breaking change detection.
- Golden Assertions: Comparing the serialized output of an event against a file.
4. Structuring the "Architect" response:
I should structure this as a formal architectural guide or ADR (Architecture Decision Record) style, but more practical.
- Introduction: Define the goal (reliable asynchronous communication).
- Layer 1: Golden Master Testing (The Shape): Focus on serialization and the "Golden" file concept.
- Layer 2: Contract Verification (The Schema): Focus on Schema Registry/Avro/Proto.
- Layer 3: Production Simulation (The Fixtures): Using factory-generated fixtures for integration tests.
- Implementation Guide: Concrete examples (I'll use TypeScript/Node or generic pseudocode, likely TypeScript as it's common for this type of testing, or maybe a mix of TS and Python). Let's stick to TypeScript/Jest as it has great tooling for snapshots, but keep principles generic.
5. Drafting the Content - Section by Section:
-
Strategy Overview: A pyramid approach.
-
1. Golden Assertions (Serialization consistency):
- Concept: "If I create this event, does it look right?"
- Tool:
jest-snapshotor custom file comparison. - Benefit: Catches accidental field renames or type changes immediately.
-
2. Snapshot Fixtures (Test Data Management):
- Concept: Don't manually build events in every test. Use a factory.
- Tool:
faker+factory-girlpattern. - Storage: Store these generated events as "Snapshots" (files) used as input for consumer tests.
-
3. Contract Testing (Schema Evolution):
- Concept: Producer vs Consumer contracts.
- Tool: Pact (message pact) or Schema Registry (Confluent/AWS).
- Process: "Backward compatibility" checks.
-
4. The Workflow:
- Dev creates event -> Unit test (Golden) -> CI runs Contract Test -> Schema updates.
6. Deep Dive into "Snapshot Fixtures" vs "Golden Assertions":
- Golden Assertion: "I assert that the output of this function matches the file
event.golden.json." (Verification) - Snapshot Fixture: "I need a realistic event to feed into my Read Model projector. I will use the file
event.snapshot.json." (Data Provisioning) - I need to make sure the distinction is clear.
7. Code Examples: I'll create a scenario: E-commerce
OrderShippedevent.- Domain Class: TypeScript interface/class.
- Golden Test: Jest snapshot test of the JSON serialization.
- Contract: JSON Schema validation.
8. Reviewing the "Architect" Persona: The tone should be authoritative, structured, and pragmatic. It shouldn't just be "use Jest snapshots." It should explain why and how to organize the files.
Self-Correction during drafting: Pure Jest snapshots are brittle. I should recommend Schema-based snapshots or strict JSON comparison over implicit Jest snapshots if the framework changes, but since the prompt specifically asks for "Golden Assertions," I will focus on the "Golden File" pattern (usually file-based comparison).
9. Final Polish: Organize into: I. The Philosophy (Why?) II. The Layered Strategy (The "What" and "How") 1. Unit: Golden Assertions (Structural Integrity) 2. Integration: Snapshot Fixtures (Data Realism) 3. E2E/Interop: Contract Tests (API Stability) III. Implementation Blueprint (Code)
Let's write the response following this structure. I will use TypeScript/Node.js as the implementation language for examples as it is the industry standard for demonstrating these patterns, but keep the concepts universal.
Key Nuance to add: Handling Evolution. If I change the event, the golden test fails. That's good. But how do I manage the contract?
- Consumer Driven Contracts: Mention Pact.
- Schema Registry: Mention Avro/Protobuf.
Let's stick to JSON for simplicity in the example but mention binary formats.
Plan:
- Define the Event Lifecycle: Creation -> Serialization -> Transport -> Consumption.
- Strategy 1: Golden Assertions (The "Mold"): Ensuring the event structure is stable.
- Strategy 2: Snapshot Fixtures (The "Payload"): Managing test data complexity.
- Strategy 3: Contract Tests (The "Law"): Ensuring compatibility.
- Pipeline Integration: How to automate this.
Let's go. This strategy treats domain events as a public API. Since events represent the immutable history of your system, they must be versioned, deterministic, and structurally reliable.
Here is an architectural strategy for testing domain events using Snapshot Fixtures, Contract Tests, and Golden Assertions.
The Architecture: The "Event Observatory"
The testing strategy is divided into three distinct layers, ensuring coverage from the internal logic of a single service to the external consumption by other systems.
Layer Testing Technique Focus Goal Unit / Integration Golden Assertions Internal Logic Verify the correct event is emitted with correct data. Contract Schema / Snapshot Interface Stability Ensure the event shape does not break consumers. Data Provisioning Snapshot Fixtures Test Data Management Provide realistic, deterministic event payloads for tests.
1. Golden Assertions (Unit/Integration Layer)
Goal: Verify that a specific domain action triggers the exact event structure you expect.
Instead of asserting
event.amount === 10, you serialize the entire event and compare it to a "Golden Master" file. This detects drift in any field, including metadata or timestamps (if frozen).Implementation Strategy:
- Trigger: Execute the domain logic (e.g.,
completeOrder). - Capture: Intercept the event dispatched by the Domain Event Publisher.
- Serialize: Convert the event to a deterministic format (JSON).
- Compare: Assert equality against the Golden File.
Example (TypeScript/Jest):
// order.events.test.ts import { Order } from '../domain/order.aggregate'; import { loadJson, writeJson } from './test-utils'; describe('Order Events', () => { it('emits OrderCompleted event with correct structure', () => { // 1. Setup const order = Order.reconstitute(existingOrderState); // 2. Act order.complete(); // Domain logic emits event internally // 3. Capture emitted events const emittedEvents = order.pullDomainEvents(); const eventPayload = emittedEvents[0].toPrimitives(); // 4. Golden Assertion // If the file doesn't exist, it creates it (Write mode) // If it exists, it compares (Read mode) expect(eventPayload).toMatchGoldenFile('__snapshots__/order-completed.golden.json'); }); });Why this works: If a developer changes a property name in the
OrderCompletedevent, the test fails immediately, forcing them to review the change (breaking change vs. fix).
2. Snapshot Fixtures (Data Provisioning Layer)
Goal: Decouple test data creation from test logic.
Snapshot fixtures are pre-serialized blobs of events stored in your codebase. They serve as the "Source of Truth" for event shapes. Instead of building events manually in every test, you hydrate from these snapshots.
Implementation Strategy:
- Capture Real Events: Use a script to extract real events from a staging environment or generate them via a Factory.
- Sanitize: Remove PII (Personally Identifiable Information) and normalize dynamic data (IDs, Dates).
- Store: Save as
.jsonfixtures.
Usage in Tests: When testing an Event Handler (e.g., a projector or saga), you don't mock the event object; you load the fixture.
// email-handler.test.ts import { OrderCompletedFixture } from '../fixtures/events/order-completed.fixture'; import { SendEmailHandler } from '../handlers/email.handler'; describe('Email Handler', () => { it('sends invoice when order completes', async () => { // Load the Golden Fixture const eventDto = OrderCompletedFixture.load(); // Optionally override specific data for this test context eventDto.data.total = 500.00; const handler = new SendEmailHandler(); await handler.handle(eventDto); expect(emailService.send).toHaveBeenCalled(); }); });
3. Contract Tests (Integration/Interop Layer)
Goal: Ensure that Producer (the Domain) and Consumers (other microservices) agree on the schema.
Golden assertions check the values. Contract tests check the schema definition. If you add a non-nullable field to an event, a Golden test might fail (or pass if the value is correct), but a Contract test ensures you know this is a Breaking Change.
Implementation Strategy: Use a schema definition standard (JSON Schema, Avro, or Protobuf).
The Contract Test Logic:
- Schema Registry: Store the schema of the event versioned (e.g.,
OrderCompleted.V1). - Backward Compatibility Check: Ensure the new schema can read old data.
- Forward Compatibility Check: Ensure old consumers can read new data (ignoring unknown fields).
Example (JSON Schema Validation):
// contract.test.ts import Ajv from 'ajv'; import { OrderCompletedSchemaV1 } from '../schemas/order-completed.v1.schema'; import { OrderCompleted } from '../domain/events/order-completed'; describe('Event Contracts', () => { const ajv = new Ajv({ allErrors: true }); it('validates OrderCompleted payload against V1 Schema', () => { const validate = ajv.compile(OrderCompletedSchemaV1); // Create a sample event const event = new OrderCompleted({ orderId: '123', occurredAt: new Date() }); const isValid = validate(event.toPrimitives()); if (!isValid) { console.error(validate.errors); } expect(isValid).toBe(true); }); });
4. The Workflow: How to Combine Them
This strategy works best when combined into a CI/CD pipeline verification step.
Scenario: Adding a
couponCodetoOrderCompleted-
Modify the Domain Class: Developer adds
couponCodeproperty to theOrderCompletedevent class. -
Update the Schema (Contract): The developer runs the schema tests. Since
couponCodeis optional, the test passes. If it were required, the test would fail (Breaking Change warning). -
Run Unit Tests (Golden Assertions): The unit test executes
order.complete(). The resulting event object now containscouponCode: null. Result: The test fails becauseorder-completed.golden.jsondoes not have thecouponCodefield.Action: Developer updates the Golden File (snapshots the new event). The diff in the PR shows exactly what changed in the event payload.
-
Consumer Verification (Fixtures): The downstream Analytics service uses
OrderCompletedFixtureto test its logic. Because the fixture file was updated, the analytics team sees their tests failing if they don't account for the new field.
Directory Structure Blueprint
To organize this, structure your test directory as follows:
/src/modules/sales /domain /events order-completed.ts /tests /events order-completed.test.ts <-- Golden Assertions /fixtures order-completed.json <-- Snapshot Fixture /contracts schemas/ order-completed.v1.json contract.test.ts <-- Schema ValidationSummary of Benefits
- No "Mystery" Failures: If an event changes, the Golden File test fails immediately with a git diff of the change.
- Zero-Boilerplate Fixtures: You stop writing
new Event({ id: 1, items: [], ... })in every test file. You load the snapshot fixture. - Versioning Safety: Contract tests ensure you aren't accidentally breaking the public API of your domain events without versioning them properly.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.