Reference

Configuration

The library is intentionally small. Most projects need a short list of properties and, occasionally, a few annotation attributes for class-specific topics.

Test properties

Every key the harness reads lives under wiretap.test.*. Define them in src/test/resources/application.properties or application-test.properties.

Topics

Property	Default	Description
`wiretap.test.topics` String	—	Comma-separated topic names to create when the broker under test starts.
`wiretap.test.partitions` int	`1`	Partition count for topics declared through `wiretap.test.topics`, and for a seeded topic that has to be created.
`wiretap.test.topics-file` String	—	YAML or JSON resource containing topic names and per-topic partition counts. When set, `wiretap.test.topics` is ignored.

Properties

wiretap.test.topics=orders,payments,audit-log
wiretap.test.partitions=2
wiretap.test.mock-schema-registry.enabled=true

wiretap.test.topics=orders,payments,audit-log
wiretap.test.partitions=2
wiretap.test.mock-schema-registry.enabled=true

Use wiretap.test.topics-file when different topics need different partition counts:

Properties

wiretap.test.topics-file=classpath:kafka-topics.yml
wiretap.test.mock-schema-registry.enabled=true

wiretap.test.topics-file=classpath:kafka-topics.yml
wiretap.test.mock-schema-registry.enabled=true

Topics declared through @EnableWiretapKafkaBroker(topics = ...) are added alongside either source.

Broker mode

Which broker the context talks to. Full detail, including the cleanup consequences, on Passthrough mode.

Property	Default	Description
`wiretap.test.mode` String	`embedded`	`embedded` starts one shared broker for the JVM; `passthrough` uses a cluster you already run. Any other value fails the context immediately.
`wiretap.test.passthrough.bootstrap-servers` String	—	The cluster to use in passthrough mode. Required there; ignored with a warning in embedded mode.
`wiretap.test.passthrough.allow-remote` boolean	`false`	Opts a passthrough suite in to a non-loopback cluster, because per-method cleanup is destructive on whatever the address points at.
`wiretap.test.broker-properties.<kafka.property>` map	`share coordinator settings`	Kafka broker properties applied before the embedded broker starts, for example `wiretap.test.broker-properties.group.share.record.lock.duration.ms=15000`. The broker is one per JVM: the first context wins and later contexts with different keys log a warning. Ignored in passthrough mode. wiretap always sets `share.coordinator.state.topic.replication.factor=1` and `share.coordinator.state.topic.min.isr=1` underneath; user keys win on conflict.

Seeding

Suite-level fixtures. Class- and method-level seeding is @KafkaSeed — see Seeding.

Property	Default	Description
`wiretap.test.seed.locations` List<String>	—	Fixture files applied before any class-level `@KafkaSeed`, as a comma-separated list or a YAML list. Each entry names one file; the topic comes from its file name.
`wiretap.test.seed.mode` String	`per-class`	`per-class` re-applies suite seeds after every cleanup; `per-method` applies them once at class start. Any other value fails the context immediately.

Clients and helpers

Property	Default	Description
`wiretap.test.mock-schema-registry.enabled` boolean	`false`	Enables a mock Schema Registry URL for Avro- and Protobuf-based tests. Works in both modes.
`wiretap.test.bean-overrides.enabled` boolean	`false`	Adjusts application Kafka client beans to use the broker under test while preserving bean names.
`wiretap.test.bean-overrides.consumer.auto-offset-reset` String	`earliest`	Consumer `auto.offset.reset` applied by bean overrides; use `preserve` to keep the application value.
`wiretap.test.bean-overrides.consumer.unique-group-ids` boolean	`true`	Adds a unique suffix to configured consumer group ids when bean overrides are enabled.
`wiretap.test.bean-overrides.share.auto-offset-reset` String	`earliest`	`share.auto.offset.reset` written to each wiretap-suffixed share group before its containers start (`earliest`, `latest`, `by_duration:<ISO-8601>`, or `none` to leave group configuration untouched). Only when bean overrides are enabled.
`wiretap.test.bean-overrides.consumer.group-id-suffix` String	`—`	Explicit suffix for configured consumer group ids. Unset means a context-local `-wiretap-<uuid>` suffix is generated — in either case only when bean overrides are enabled.
`wiretap.test.object-mapper-bean-name` String	`—`	Spring bean name for the Jackson 3 `ObjectMapper` used by typed JSON publishing, reading, and assertions. Unset falls back to a `wiretapTestObjectMapper` bean when the context has one, else wiretap's own mapper.
`wiretap.test.listeners.ready-timeout` Duration	`PT15S`	Default timeout for the listener-readiness helpers, in ISO-8601 `Duration` form.

Jackson ObjectMapper

By default, JSON DTO publishing, typed reading, JsonPath assertions, and JSON snapshot assertions use the library's wiretapTestObjectMapper bean. It is built with Jackson 3, discovers modules, omits null values, ignores unknown fields, allows null primitive values, and writes Java time values as ISO strings rather than timestamps.

If your test application already has a customised mapper, point the library at it by bean name:

Properties

wiretap.test.object-mapper-bean-name=objectMapper

wiretap.test.object-mapper-bean-name=objectMapper

The named bean must be a Jackson 3 tools.jackson.databind.ObjectMapper. This is useful when your tests rely on custom naming strategies, serializers, mix-ins, or modules. The default bean name is library-specific, so it does not collide with an application's usual objectMapper bean unless you explicitly point the property at that bean.

Logging

The shared broker honours the importing test app's usual Spring Boot logging.level.* properties before the embedded Kafka broker starts.

Properties

logging.level.org.apache.kafka=WARN
logging.level.kafka=WARN
logging.level.state.change.logger=WARN
logging.level.org.springframework.kafka=WARN

logging.level.org.apache.kafka=WARN
logging.level.kafka=WARN
logging.level.state.change.logger=WARN
logging.level.org.springframework.kafka=WARN

Spring logging groups are supported too, so a project can define logging.group.kafka-broker and then set logging.level.kafka-broker.

Dynamic bean overrides

Some applications define named Kafka beans with production-only authentication settings. When those beans are only different because tests need the shared embedded broker, enable dynamic overrides instead of creating parallel @TestConfiguration beans:

Properties

wiretap.test.bean-overrides.enabled=true

wiretap.test.bean-overrides.enabled=true

When enabled, the library updates matching ProducerFactory, ConsumerFactory, KafkaTemplate, KafkaAdmin, and ConcurrentKafkaListenerContainerFactory beans so they connect to the shared broker. Original bean names, qualifiers, serialisers, deserialisers, and listener factory settings are preserved where possible.

See Bean overrides for the full guide.

Topic file shape

YAML and JSON share the same structure:

kafka-topics.yml

topics:
  - name: "orders"
    partitions: 4
  - name: "inventory"
    partitions: 2
  - name: "shipping_updates"
    partitions: 8
  - name: "error_logs"
    partitions: 1

topics:
  - name: "orders"
    partitions: 4
  - name: "inventory"
    partitions: 2
  - name: "shipping_updates"
    partitions: 8
  - name: "error_logs"
    partitions: 1

The location can be any Spring resource supported by the test application context, such as classpath:kafka-topics.yml or file:/tmp/kafka-topics.json. The file is validated against the bundled JSON Schema before topics are created, so invalid YAML or JSON fails fast with the field path and validation reason.

@EnableWiretapKafkaBroker attributes

Use annotation attributes when a single test class needs class-specific topics.

Property	Default	Description
`topics` String[]	`{}`	Extra topics to create for that test class.
`partitions` int	`1`	Partition count for topics declared through the annotation.

Java

@EnableWiretapKafkaBroker(topics = {"retry-topic", "dlq-topic"}, partitions = 3)
class RetryHandlerTest {
}

@EnableWiretapKafkaBroker(topics = {"retry-topic", "dlq-topic"}, partitions = 3)
class RetryHandlerTest {
}

Topics declared through the annotation are added alongside the ones from properties. Their partition count is controlled by the annotation, not by wiretap.test.partitions.

In Spring tests, annotation-declared topics are created while the application context is being prepared, before auto-starting @KafkaListener containers subscribe.

Auto-injected properties

The library adds these to the Spring Environment when the context starts.

Property	Default	Description
`spring.kafka.bootstrap-servers`	—	The address of the broker under test, in both modes.
`spring.embedded.kafka.brokers`	—	Same address, kept for compatibility with older test setups. Embedded mode only — in passthrough mode nothing embedded is running, so the key is not published.
`spring.kafka.properties.schema.registry.url`	—	`mock://wiretap` when mock Schema Registry is enabled.
`wiretap.test.active`	—	`true` in any context wiretap has wired.
`wiretap.test.mode`	—	The mode wiretap resolved — `embedded` or `passthrough` — so test infrastructure can read which one it is in.

Cleanup between tests

After each test method, the library:

purges records from the topics in scope
deletes consumer groups so committed offsets do not leak between tests
re-applies the class's @KafkaSeed fixtures, and the suite fixtures when wiretap.test.seed.mode=per-class

This keeps topic definitions in place while resetting their contents, which is much faster than deleting and recreating topics or marking the Spring context dirty. Kafka internal topics (those beginning with __) are left alone.

On the embedded broker “in scope” means every non-internal topic and every consumer group: wiretap owns that broker outright. In passthrough mode it is narrowed to the topics wiretap created or seeded on that cluster and the consumer groups carrying wiretap's unique suffix, and the cluster is never enumerated to discover what to clean.

Clearing non-Kafka state

Kafka state is only part of test isolation. If your consumers write to a database, cache, or file store, clear that state in the usual way between tests.

Java

@Autowired
private StoredEventRepository repository;

@BeforeEach
void clearState() {
    repository.deleteAll();
}

@Autowired
private StoredEventRepository repository;

@BeforeEach
void clearState() {
    repository.deleteAll();
}