# Architecture > KTestify's three-layer architecture. Transport, Orchestration, and Assertion, and why it matters. Source: https://docs.ktestify.xyz/docs/extend/architecture KTestify is built on a strict **three-layer separation of concerns**. Each layer has one job and knows nothing about the other layers' implementation details. Since version `1.1.1`, the transport layer has **two sibling contracts** instead of one. `RecordFetcher` models a background stream you poll until a record appears (Kafka, Azure Blob). `RequestResponseClient` models a synchronous, caller-initiated call where you send a request right now and get an answer immediately (HTTP, gRPC, SOAP). Both return `List>`, so the orchestration and assertion layers below stay identical no matter which contract a given transport implements. ```mermaid --- config: layout: elk --- flowchart LR subgraph TRANSPORT A[KafkaRecordFetcher] A2[RequestResponseClient<Req,V>] end subgraph ORCHESTRATION B[AbstractKafkaConsumer] C[RawKafkaConsumer] D[AvroKafkaConsumer] B2[AbstractSynchronousConsumer] end subgraph ASSERTION E[RecordMatcher<V>] F[FileRecordMatcher] G[XmlRecordMatcher] H[AvroFileRecordMatcher] I[AttributeRecordMatcher] end A -->|List<ConsumedRecord>| B B --> C B --> D B -->|List<ConsumedRecord>| E A2 -->|List<ConsumedRecord>| B2 B2 -->|List<ConsumedRecord>| E E --> F E --> G E --> H E --> I classDef transport fill:#E1F5EE,stroke:#0F6E56,color:#085041 classDef orchestration fill:#EEEDFE,stroke:#534AB7,color:#3C3489 classDef assertion fill:#FAC775,stroke:#854F0B,color:#412402 class A,A2 transport class B,C,D,B2 orchestration class E,F,G,H,I assertion ``` **`ConsumedRecord` is the only data type that crosses layer boundaries.** Synchronous transports additionally populate a new `attributes` map on `ConsumedRecord` (an HTTP status code, a future gRPC status code, an MQ reason code) for metadata that is not a protocol header. Asynchronous transports leave it empty. See [Core Concepts →](core-concepts) for the full field list. --- ## Why the separation matters The three layers are connected by exactly one type, `ConsumedRecord`. Because the transport layer only ever emits that type and the assertion layer only ever consumes it, the two are fully decoupled. The practical payoff is threefold: - **Swap transports without touching assertions.** A new broker is a new `RecordFetcher` (or `RequestResponseClient`) implementation. Every `RecordMatcher` keeps working because it only sees `ConsumedRecord`. - **Reuse matchers across transports.** The same `FileRecordMatcher` asserts a Kafka `String` body and an HTTP response body, because both arrive as `ConsumedRecord`. - **Stay test-framework agnostic.** `ktestify-cucumber` (or any future adapter) drives the engine through `ConsumerContext` / `ProducerContext` and reads back `ConsumedRecord`. It never imports a broker client. ## Layer responsibilities ### Transport - `RecordFetcher` The transport layer turns a concrete message broker into a stream of `ConsumedRecord`. The contract itself is deliberately tiny, a single `fetch()` method plus `close()`: ```java public interface RecordFetcher extends AutoCloseable { List> fetch() throws FetchException; void close(); } ``` `fetch()` blocks until at least one record that passes the configured filters is available, or the read timeout expires. It returns a non-empty, unmodifiable list, or throws `FetchException`. The only implementation today is `KafkaRecordFetcher`, which knows Kafka brokers, partitions, offsets, and the deduplication registry. Swapping Kafka for IBM MQ means writing a new `IbmMqRecordFetcher` that implements the same interface. Nothing in the layers above changes. --- ### Transport, synchronous - `RequestResponseClient` Knows: how to send one request and turn the answer into `ConsumedRecord`. Does NOT know: matchers, files, test frameworks, and does not block waiting for something to "appear". ```java public interface RequestResponseClient extends AutoCloseable { List> execute(Req request) throws FetchException; void close(); } ``` This is the contract an HTTP client plugin implements. See [Synchronous Transports →](transports/synchronous-transports) for the full guide. --- ### Orchestration - `AbstractKafkaConsumer` Knows: fetch → match → result wiring. Does NOT know: Kafka internals, comparison algorithms. ```java // AbstractKafkaConsumer.call(), simplified try (KafkaRecordFetcher fetcher = new KafkaRecordFetcher<>(context)) { List> records = fetcher.fetch(); // transport MatchContext matchCtx = buildMatchContext(); MatchResult result = matcher.match(records, matchCtx); // assertion return result.isPassed(); } catch (FetchException e) { throw new ConsumerException(e.getMessage()); } ``` --- ### Orchestration, synchronous - `AbstractSynchronousConsumer` Knows: buildRequest → execute → match → result wiring, for transports where the caller supplies the request explicitly instead of the fetcher blocking on a subscription. Does NOT know: HTTP, gRPC, or any transport internals. ```java // AbstractSynchronousConsumer.call(), simplified try { Req request = buildRequest(); List> records = client.execute(request); // transport MatchResult result = matcher.match(records, buildMatchContext()); // assertion return result.isPassed(); } catch (FetchException e) { throw new ConsumerException(e.getMessage()); } ``` Unlike `AbstractKafkaConsumer`, the client is not closed in a `finally` block here. A `RequestResponseClient` is expected to be a longer lived, connection pooled client (like `java.net.http.HttpClient`), owned and closed by the plugin's shared scenario resources, not created and discarded per call. --- ### Assertion - `RecordMatcher` Knows: `ConsumedRecord`, expected values, comparison algorithm. Does NOT know: Kafka, IBM MQ, any transport. ```java @FunctionalInterface public interface RecordMatcher { MatchResult match(List> records, MatchContext context); } ``` --- ## Module boundaries ``` ktestify-core ktestify-cucumber ─────────────────────────────── ────────────────────────────────── RecordFetcher BackgroundStepDefinition RequestResponseClient ValidationStepDefinition KafkaRecordFetcher ◄──────── ConsumerContext (config only) AbstractKafkaConsumer ConsumerValidationService.** It uses `ConsumerContext` / `ProducerContext` (ktestify-core abstractions) to configure the engine and receives only `ConsumedRecord` back. This is what keeps the Cucumber layer free of broker specifics and lets the same step definitions drive Kafka, HTTP, or any future transport without modification PollingRequestResponseClient RecordMatcher MatchContext / MatchResult ConsumedRecord ``` **`ktestify-cucumber` must never import `org.apache.kafka.*`**. It uses `ConsumerContext` / `ProducerContext` (ktestify-core abstractions) to configure the engine and receives only `ConsumedRecord` back. --- ## Class hierarchy ```mermaid --- config: layout: elk --- flowchart TD A["Callable<Boolean>"] B["AbstractConsumer"] C["AbstractKafkaConsumer<K, V>"] D["RawKafkaConsumer\nK=String, V=String"] E["AvroKafkaConsumer\nK=String, V=GenericRecord"] C2["AbstractSynchronousConsumer<Req, V>"] A --> B --> C --> D C --> E B --> C2 F(["RecordFetcher<V> · interface"]) G["KafkaRecordFetcher<K, V>"] F --> G H(["RequestResponseClient<Req,V> · interface"]) I["PollingRequestResponseClient<Req,V>"] H --> I classDef abstract fill:#EEEDFE,stroke:#534AB7,color:#3C3489 classDef concrete fill:#E1F5EE,stroke:#0F6E56,color:#085041 classDef iface fill:#FAC775,stroke:#854F0B,color:#412402 class A,B,C,C2 abstract class D,E,G,I concrete class F,H iface ``` ### Matchers hierarchy ``` RecordMatcher (@FunctionalInterface) ├── NoOpRecordMatcher ├── FileRecordMatcher ├── XmlRecordMatcher ├── XPathRecordMatcher ├── FieldsRecordMatcher ├── FileKeyRecordMatcher ├── KeyRecordMatcher ├── AttributeRecordMatcher ├── AvroFileRecordMatcher ├── AvroFileKeyRecordMatcher ├── AvroFieldsRecordMatcher └── AvroKeyRecordMatcher ``` --- ## See also - [Core concepts →](core-concepts) - [Transports, Kafka →](transports/kafka) - [Adding a transport →](transports/adding-a-transport) - [Synchronous transports →](transports/synchronous-transports) - [Built-in matchers →](matchers/built-in-matchers)