60 seconds

Quick start

You can usually move to a shared broker in a few minutes. Add the dependency, declare the topics your tests need, and replace @EmbeddedKafka with @EnableWiretapKafkaBroker.

Add the dependency

Add the library to your test scope. Your own BOM can still override Spring and Kafka versions in the usual way.

pom.xml

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>wiretap-spring-boot</artifactId>
    <version>5.2.3</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>io.typecheck</groupId>
    <artifactId>wiretap-spring-boot</artifactId>
    <version>5.2.3</version>
    <scope>test</scope>
</dependency>

Declare shared topics

In src/test/resources/application.properties, list the topics that should exist for the suite.

application.properties

wiretap.test.topics=orders,payments,notifications
wiretap.test.partitions=2

wiretap.test.topics=orders,payments,notifications
wiretap.test.partitions=2

If the suite needs different partition counts per topic, point the library at a YAML or JSON topic file instead:

Properties

wiretap.test.topics-file=classpath:kafka-topics.yml

wiretap.test.topics-file=classpath:kafka-topics.yml

src/test/resources/kafka-topics.yml

topics:
  - name: "orders"
    partitions: 4
  - name: "payments"
    partitions: 2

topics:
  - name: "orders"
    partitions: 4
  - name: "payments"
    partitions: 2

If your tests use Confluent Avro or Protobuf serialisers, enable the mock Schema Registry as well:

Properties

wiretap.test.mock-schema-registry.enabled=true

wiretap.test.mock-schema-registry.enabled=true

The library then sets spring.kafka.properties.schema.registry.url to mock://wiretap for you.

Annotate your test

Replace @EmbeddedKafka with @EnableWiretapKafkaBroker:

OrderIntegrationTest.java

@SpringBootTest
@EnableWiretapKafkaBroker
class OrderIntegrationTest {
    @Autowired
    private KafkaTemplate<String, OrderEvent> kafkaTemplate;

    @Test
    void shouldPublishOrder() throws Exception {
        var order = OrderEvent.create("Widget", 3, new BigDecimal("29.99"));
        kafkaTemplate.send("orders", order.getId(), order).get();
    }
}

@SpringBootTest
@EnableWiretapKafkaBroker
class OrderIntegrationTest {
    @Autowired
    private KafkaTemplate<String, OrderEvent> kafkaTemplate;

    @Test
    void shouldPublishOrder() throws Exception {
        var order = OrderEvent.create("Widget", 3, new BigDecimal("29.99"));
        kafkaTemplate.send("orders", order.getId(), order).get();
    }
}

That is enough to get the shared broker running.

What happens at runtime

When the first @EnableWiretapKafkaBroker test starts, the library:

starts a single embedded Kafka broker for the JVM
injects the broker address into the Spring environment
creates the topics declared in your test configuration or topic file
registers the broker as a Spring bean

After each test method, it clears records from non-internal topics and removes consumer groups so the next test starts cleanly without recreating the broker or restarting the Spring context.

Add topics for a single class

If one test class needs extra topics, declare them on the annotation:

Java

@EnableWiretapKafkaBroker(topics = {"special-topic"}, partitions = 3)
class SpecialTopicTest {
}

@EnableWiretapKafkaBroker(topics = {"special-topic"}, partitions = 3)
class SpecialTopicTest {
}

Those topics are added on top of anything declared in application.properties.

Use it with @TestConfiguration

Existing @TestConfiguration classes and @Primary bean overrides continue to work. By default, the library only supplies the broker and the properties your Kafka beans depend on. If production-only authentication is the reason you have test Kafka beans, see Bean Overrides.

Java

@SpringBootTest
@EnableWiretapKafkaBroker
@Import(MyKafkaTestConfig.class)
class AuthBypassTest {
    @Autowired
    private KafkaTemplate<String, Object> kafkaTemplate;
}

@SpringBootTest
@EnableWiretapKafkaBroker
@Import(MyKafkaTestConfig.class)
class AuthBypassTest {
    @Autowired
    private KafkaTemplate<String, Object> kafkaTemplate;
}

Run the suite

This project treats integration tests as the default verification path.

classes ending in IT run through Maven Failsafe
mvn verify runs the integration suite
coverage reports are generated during verify