Introduction

In Spring Boot tests, Kafka listeners are often the part you do not want running. A listener can consume messages, trigger background work, or fail the test context when Kafka is unavailable, even though the test is really about a controller, service, or repository.

If you only want listeners disabled for one test class, the best solution is usually to make listener startup configurable and override that setting in the test. That keeps production behavior unchanged while giving the test a quiet application context.

The Simplest Pattern: Make Startup Configurable

Spring Kafka lets a @KafkaListener override auto-startup behavior. Instead of hard-coding the listener to always start, bind it to a property:

1import org.springframework.kafka.annotation.KafkaListener;
2import org.springframework.stereotype.Component;
3
4@Component
5public class OrderEventsListener {
6
7    @KafkaListener(
8        id = "order-events-listener",
9        topics = "orders.created",
10        autoStartup = "${app.kafka.listeners.orders.enabled:true}"
11    )
12    public void onMessage(String payload) {
13        System.out.println("Received: " + payload);
14    }
15}

Now a single test can disable only that listener:

1import static org.assertj.core.api.Assertions.assertThat;
2
3import org.junit.jupiter.api.Test;
4import org.springframework.beans.factory.annotation.Autowired;
5import org.springframework.boot.test.context.SpringBootTest;
6import org.springframework.kafka.config.KafkaListenerEndpointRegistry;
7
8@SpringBootTest(properties = "app.kafka.listeners.orders.enabled=false")
9class OrderServiceTest {
10
11    @Autowired
12    KafkaListenerEndpointRegistry registry;
13
14    @Test
15    void listenerDoesNotStartInThisTestContext() {
16        assertThat(registry.getListenerContainer("order-events-listener").isRunning())
17            .isFalse();
18    }
19}

This is usually the cleanest answer because it is explicit, local to the test, and easy to understand months later.

Disabling All Kafka Listeners for One Test Class

Sometimes you do not care which listener starts. You just want the whole test context to come up without Kafka consumers. In that case, override the listener auto-startup property for the test:

1import org.junit.jupiter.api.Test;
2import org.springframework.boot.test.context.SpringBootTest;
3
4@SpringBootTest(properties = "spring.kafka.listener.auto-startup=false")
5class PaymentControllerTest {
6
7    @Test
8    void contextLoadsWithoutStartingKafkaConsumers() {
9    }
10}

This is useful for MVC tests, persistence tests, or service-layer integration tests that load the full application but do not need asynchronous message consumption.

The tradeoff is scope: this setting disables every listener in that test context, not just one.

Stopping a Specific Listener Programmatically

If you need the listener bean present but stopped after the context starts, use the KafkaListenerEndpointRegistry. This is helpful when the same application context is reused and you need precise lifecycle control.

1import org.junit.jupiter.api.BeforeEach;
2import org.junit.jupiter.api.Test;
3import org.springframework.beans.factory.annotation.Autowired;
4import org.springframework.boot.test.context.SpringBootTest;
5import org.springframework.kafka.config.KafkaListenerEndpointRegistry;
6import org.springframework.kafka.listener.MessageListenerContainer;
7
8@SpringBootTest
9class InventoryServiceTest {
10
11    @Autowired
12    KafkaListenerEndpointRegistry registry;
13
14    @BeforeEach
15    void stopListener() {
16        MessageListenerContainer container =
17            registry.getListenerContainer("order-events-listener");
18
19        if (container != null && container.isRunning()) {
20            container.stop();
21        }
22    }
23
24    @Test
25    void testBusinessLogicWithoutBackgroundConsumption() {
26    }
27}

This approach works, but it is less ideal than a property-based startup flag because the listener may have already started briefly before you stop it. If consuming even one message would break the test, prefer disabling startup before the context is refreshed.

When Profiles Help

Profiles are still useful when many tests share the same "Kafka listeners off" rule. For example, you might keep application-test.yml with:

1spring:
2  kafka:
3    listener:
4      auto-startup: false

Then activate it with @ActiveProfiles("test"). That is convenient for a whole suite, but it is broader than the original question of "one particular test." For a single class, inline test properties are usually clearer.

Common Pitfalls

One common mistake is disabling the wrong thing. Mocking KafkaTemplate or changing producer settings does not stop @KafkaListener containers from starting. Listener startup is controlled separately.

Another issue is forgetting the listener id. If you want to inspect or stop a specific container with KafkaListenerEndpointRegistry, the listener needs a stable id value.

Test context caching can also confuse people. If one test class starts a context with listeners enabled and another uses different properties, Spring may build a separate context. That is expected, but it can make test startup slower if you overuse per-class variations.

Finally, avoid stopping listeners in @BeforeEach when your real goal is "never start them at all." Programmatic stop works after startup, not before it.

Summary

• For one Spring Boot test class, the cleanest solution is usually a property-driven autoStartup on @KafkaListener.
• Use @SpringBootTest(properties = "...") to disable one listener or all listeners in that test context.
• 'spring.kafka.listener.auto-startup=false is convenient when you want every listener off for that test.'
• 'KafkaListenerEndpointRegistry is useful for manual lifecycle control, but it does not prevent initial startup.'
• Give listeners explicit id values if you need to inspect, stop, or start them in tests.