Wiretap

One record

Record assertions

Use these when your test has already consumed a ConsumerRecord and you want to verify metadata, headers, or payload content in one readable chain.

For topic-wide checks, jump to Topic assertions. For collection-style assertions over keys, values, or JsonPath results, see Extraction assertions.

Typed payload JsonPath assertions use the library's Jackson 3 wiretapTestObjectMapper bean and support Java time fields by default. Set wiretap.test.object-mapper-bean-name only when assertions should use another Spring Boot tools.jackson.databind.ObjectMapper bean.

Entry point

Start with KafkaAssertions.assertThat(record) when you already have the consumed record, or use KafkaAssertions.assertThatRecord(...) when you want the library to read a single record from the shared broker first:

Java
import static io.typecheck.wiretap.core.assertions.KafkaAssertions.assertThat;
import static io.typecheck.wiretap.core.assertions.KafkaAssertions.assertThatRecord;

ConsumerRecord<String, OrderEvent> record =
        KafkaTopicReader.readSingleRecord(broker, "orders-topic", OrderEvent.class);

assertThatRecord("orders-topic", OrderEvent.class)
        .hasJsonPath("$.product", "Widget");

Metadata

hasTopic(String)

Java
assertThat(record).hasTopic("orders-topic");

hasPartition(int)

Java
assertThat(record).hasPartition(0);

hasOffset(long)

Java
assertThat(record).hasOffset(15L);

Key and value

hasKey(Object)

Java
assertThat(record).hasKey("order-123");

hasKeyMatching(Matcher)

Java
assertThat(record).hasKeyMatching(startsWith("order-"));

hasValue(Object) / hasNoValue()

Java
assertThat(record).hasValue(expectedOrderEvent);
Java
assertThat(record).hasNoValue();

Headers

hasHeader(String)

Java
assertThat(record).hasHeader("X-Correlation-Id");

hasHeaderWithValue(String, String)

Java
assertThat(record).hasHeaderWithValue("X-System-Origin", "checkout-service");

doesNotHaveHeader(String)

Java
assertThat(record).doesNotHaveHeader("Authorization");

Payload matching

hasJsonPath(String)

Java
assertThat(record).hasJsonPath("$.orderId");

hasJsonPath(String, Object)

The most flexible assertion in the set. Evaluates a JsonPath expression against the record value, whether the payload started as a raw JSON string, a Java object serialised as JSON, an Avro record represented as JSON internally, or a Protobuf message rendered as proto3 canonical JSON.

Java
assertThat(record).hasJsonPath("$.customer.id", "cust-42");

hasJsonPath(String, nullValue())

Use Hamcrest's nullValue() matcher for explicit JSON null checks. Missing paths still fail, so null and absent fields remain distinct.

Java
assertThat(record).hasJsonPath("$.customer.middleName", nullValue());

hasJsonPath(String, Matcher)

Java
assertThat(record).hasJsonPath("$.product", equalTo("Widget"));

Reusable payload matchers

KafkaPayloadMatchers supplies Hamcrest factories for the matcher overloads you already use. Base64 matchers accept standard and URL-safe encodings and ignore whitespace, so JSON fields that carry files can be checked without adding JSON-path-specific methods.

Use validBase64(), base64DecodedAs(FileType), base64DecodedSize(...), base64DecodedUtf8(...), validUuid(), validUlid(), validUri(), validIsoInstant(), jsonEquivalentTo(...), and jsonPath(...) with hasJsonPath, hasHeaderWithValue, and other matcher-based assertions.

Java
import static io.typecheck.wiretap.core.assertions.FileType.PDF;
import static io.typecheck.wiretap.core.assertions.KafkaPayloadMatchers.*;

assertThat(record)
    .hasHeaderWithValue("X-Correlation-Id", validUuid())
    .hasJsonPath("$.attachment.data", validBase64())
    .hasJsonPath("$.attachment.data", base64DecodedAs(PDF))
    .hasJsonPath("$.attachment.data", base64DecodedSize(greaterThan(512)))
    .hasJsonPath("$.publishedAt", validIsoInstant());

Chaining assertions together

Routing and payload

Java
assertThat(record)
    .hasKey("order-123")
    .hasPartition(0)
    .hasJsonPath("$.status", "CREATED")
    .hasJsonPath("$.customer.id", "cust-42");

Headers and content

Java
assertThat(record)
    .hasHeader("X-Correlation-Id")
    .hasHeaderWithValue("X-System-Origin", equalTo("checkout-service"))
    .doesNotHaveHeader("Authorization")
    .hasJsonPath("$.total", 29.99);