Spring Boot Tests: Exclude Auto-Configuration Classes - The Ultimate Guide

Spring Boot's auto-configuration is a double-edged sword in testing. On one hand, it magically wires up DataSource, JPA, Security, and dozens of other beans based on classpath dependencies. On the other hand, in a unit test or a focused integration test, that magic can pull in an entire production infrastructure—connecting to real databases, loading security filters, and spinning up embedded servers—making tests slow, flaky, and context-heavy. I've seen a single test class take 45 seconds just to bootstrap because it loaded 78 auto-configuration classes, most of which were irrelevant. In production, we had a billing service where an auto-configured JMS listener in a test accidentally consumed messages from a dev queue, causing duplicate charges. That's when you learn to exclude aggressively.

This guide covers every technique to exclude auto-configuration classes in Spring Boot tests: from the obvious @SpringBootTest(exclude = ...) to the subtle @TestConfiguration overrides, property-driven filtering, and slice annotations. We'll use Spring Boot 3.2.x (latest stable as of 2024) and JUnit 5. Whether you're testing a repository, a controller, or a full service, you'll know exactly how to trim the fat. I'll also share a production incident where failing to exclude caused a 2-hour outage. By the end, your test suite will start in seconds, not minutes.

Why Exclude Auto-Configuration in Tests? The Real Cost

Every auto-configuration class that Spring Boot loads in a test context adds startup time, memory pressure, and potential side effects. In a typical Spring Boot 3.2 application with spring-boot-starter-web, spring-boot-starter-data-jpa, and spring-boot-starter-security, the test context can load 30+ auto-configuration classes. That's 30 condition evaluations, 30 bean definitions, and often 30+ beans instantiated. On my MacBook Pro M2, a full @SpringBootTest takes 12-15 seconds to start. For a suite of 200 tests, that's 40+ minutes of just context startup if you don't share contexts.

But the real cost isn't just time—it's unpredictability. Auto-configuration classes react to the classpath. If someone adds spring-boot-starter-activemq to pom.xml, suddenly every @SpringBootTest tries to connect to a broker. I've debugged tests that failed because FlywayAutoConfiguration ran migrations on a test database that had schema drift. Or because RedisAutoConfiguration started a Lettuce connection to localhost:6379, which didn't exist, causing a 30-second timeout. Excluding auto-config is defensive programming. You control exactly what loads.

In production, we had a microservice with 12 auto-configuration classes that loaded in tests but were never used: MailSender, JMS, Flyway, Quartz, etc. After excluding them, the test context startup dropped from 18 seconds to 3.2 seconds. The entire CI pipeline went from 22 minutes to 8 minutes. That's real money.

@SpringBootTest
class OrderServiceIntegrationTest {

    @Autowired
    private OrderService orderService;

    @Test
    void shouldCreateOrder() {
        // This test context loads 35 auto-config classes
        // including JMS, Mail, Flyway, Quartz, etc.
        // Startup time: ~15 seconds
        Order order = orderService.createOrder(new CreateOrderRequest("item-1", 2));
        assertThat(order.getId()).isNotNull();
    }
}

// After optimization
@SpringBootTest(
    classes = {OrderService.class, OrderRepository.class},
    exclude = {
        ActiveMQAutoConfiguration.class,
        MailSenderAutoConfiguration.class,
        FlywayAutoConfiguration.class,
        QuartzAutoConfiguration.class
    }
)
class OptimizedOrderServiceIntegrationTest {
    // Startup time: ~3 seconds
    // Same test, faster context
}

What the Official Docs Won't Tell You

The official Spring Boot documentation tells you about @SpringBootTest(exclude = ...) and spring.autoconfigure.exclude. But it doesn't tell you the dirty secrets. First, the exclude attribute on @SpringBootTest only works if you also specify classes = ... or use a fully loaded context. If you rely on default context loading (scanning from the test class's package), the exclude attribute is silently ignored in some edge cases with Spring Boot 3.2.0-3.2.3. I've filed a bug and it was fixed in 3.2.4, but you should know.

Second, @EnableAutoConfiguration(exclude = ...) works on test slices like @WebMvcTest, but the order matters. If you place it after @WebMvcTest, Spring Boot may load the auto-config before your exclusion takes effect. Always put @EnableAutoConfiguration immediately after the slice annotation, like @WebMvcTest @EnableAutoConfiguration(exclude = SecurityAutoConfiguration.class).

Third, the property spring.autoconfigure.exclude in application.properties is global. If you set it in src/test/resources/application.properties, it affects ALL tests. That's fine for broad exclusions (e.g., spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jms.activemq.ActiveMQAutoConfiguration), but it's a blunt instrument. For per-test exclusions, use @TestPropertySource or the properties attribute on @SpringBootTest.

Fourth, and this is the one that burned me: @TestConfiguration does NOT exclude auto-configuration. It only adds or overrides beans. If you create a @TestConfiguration that defines a DataSource bean, but JpaAutoConfiguration is still active, Hibernate may still try to initialize from your production entity scan. You must explicitly exclude JpaAutoConfiguration if you want full control. The official docs imply @TestConfiguration is a replacement, but it's not—it's an addition.

@SpringBootTest
@EnableAutoConfiguration(exclude = SecurityAutoConfiguration.class)
// This works because @EnableAutoConfiguration is processed after @SpringBootTest
class SecurityExcludedTest {
    // Test without security auto-config
}

// WRONG ORDER — exclusion ignored
@EnableAutoConfiguration(exclude = SecurityAutoConfiguration.class)
@SpringBootTest
class WrongOrderTest {
    // SecurityAutoConfiguration still loads!
}

// Correct way with slice tests
@WebMvcTest(controllers = OrderController.class)
@EnableAutoConfiguration(exclude = SecurityAutoConfiguration.class)
class OrderControllerSliceTest {
    // No security filters applied
}

Method 1: @SpringBootTest(exclude) - The Direct Approach

The most straightforward way to exclude auto-configuration classes is using the exclude attribute on @SpringBootTest. This attribute accepts an array of Class<?> objects representing auto-configuration classes to exclude. Under the hood, Spring Boot passes these to SpringFactoriesLoader, which normally loads all auto-configuration classes listed in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. The excluded classes are filtered out before any condition evaluation occurs.

Here's the catch: the exclude attribute only works if Spring Boot can determine the full set of auto-configuration classes to load. If you use @SpringBootTest without specifying classes, Spring Boot scans from the test class's package upward to find the @SpringBootApplication class. If it finds one, it uses that class's exclude/excludeName attributes. If it doesn't find one, it falls back to loading all auto-config classes from the classpath. In that fallback scenario, the exclude attribute may be ignored (the bug I mentioned earlier, fixed in 3.2.4).

Best practice: always pair exclude with classes = { ... } to explicitly define the minimal set of configuration classes your test needs. This gives you a deterministic context. For example, if you're testing a service that depends on JdbcTemplate, only load DataSourceAutoConfiguration and JdbcTemplateAutoConfiguration. Don't load JpaAutoConfiguration, HibernateJpaAutoConfiguration, or TransactionAutoConfiguration unless you need them.

Performance tip: exclude classes that trigger expensive initialization. FlywayAutoConfiguration runs database migrations—exclude it in tests unless you're explicitly testing migrations. Similarly, ElasticsearchDataAutoConfiguration tries to connect to an Elasticsearch cluster. Exclude it and use an embedded Elasticsearch or mock.

@SpringBootTest(
    classes = {OrderService.class, JdbcTemplate.class, DataSource.class},
    exclude = {
        FlywayAutoConfiguration.class,
        JpaAutoConfiguration.class,
        HibernateJpaAutoConfiguration.class,
        TransactionAutoConfiguration.class,
        SecurityAutoConfiguration.class
    }
)
class OrderServiceJdbcTest {

    @Autowired
    private OrderService orderService;

    @Test
    void shouldCreateOrderWithJdbc() {
        // Context loads in 2.5 seconds
        // Only DataSource, JdbcTemplate, and OrderService are configured
        Order order = orderService.createOrder(new CreateOrderRequest("SKU-123", 1));
        assertThat(order.getTotal()).isEqualTo(new BigDecimal("29.99"));
    }
}

Method 2: @TestConfiguration Override - When Exclude Is Not Enough

Sometimes you can't exclude an auto-configuration class because it provides a bean you need, but you want to override that bean with a test-specific version. For example, you need a DataSource bean, but you don't want HikariCP connection pooling (which is auto-configured by DataSourceAutoConfiguration). You want a simple DriverManagerDataSource for testing. @TestConfiguration is your tool for this.

A @TestConfiguration class is a static inner class (or a separate class) annotated with @TestConfiguration. Beans defined in this class override beans of the same type from the primary configuration, including auto-configured beans. This works because Spring Boot's auto-configuration uses @ConditionalOnMissingBean—if you define a bean of the same type, the auto-configuration backs off.

However, there's a nuance: @TestConfiguration beans are only applied if the test class or a parent configuration imports them. The most common pattern is to define @TestConfiguration as a static inner class inside the test class. Spring Boot's test context automatically detects static inner classes annotated with @TestConfiguration and includes them. But if your @TestConfiguration is a separate class, you must import it via @Import(MyTestConfig.class) on the test class.

Important: @TestConfiguration does NOT disable the auto-configuration class itself—it only overrides the beans that the auto-configuration would have created. The auto-configuration class still runs its condition evaluation. This means if the auto-configuration class has side effects (e.g., FlywayAutoConfiguration that runs migrations before creating the DataSource bean), @TestConfiguration won't prevent those side effects. For side-effect-heavy auto-config, you still need to exclude the class entirely.

@SpringBootTest(
    classes = {UserService.class, UserRepository.class},
    exclude = {DataSourceAutoConfiguration.class} // Exclude HikariCP auto-config
)
class UserServiceTest {

    @Autowired
    private UserService userService;

    @TestConfiguration
    static class TestDatabaseConfig {

        @Bean
        @Primary
        public DataSource dataSource() {
            // Override with simple non-pooled DataSource
            return new DriverManagerDataSource(
                "jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1",
                "sa",
                ""
            );
        }

        @Bean
        public JdbcTemplate jdbcTemplate(DataSource dataSource) {
            return new JdbcTemplate(dataSource);
        }
    }

    @Test
    void shouldFindUserByEmail() {
        User user = userService.findByEmail("test@example.com");
        assertThat(user).isNotNull();
    }
}

Method 3: Property-Based Exclusion with spring.autoconfigure.exclude

For global exclusions that apply to all tests (or a group of tests), use the spring.autoconfigure.exclude property. This can be set in application.properties, application-test.properties, or via @TestPropertySource. The property accepts a comma-separated list of fully qualified class names of auto-configuration classes to exclude.

This method is ideal for excluding auto-configuration classes that you never want in any test context—for example, FlywayAutoConfiguration (database migrations), MailSenderAutoConfiguration (email), or JmsAutoConfiguration (messaging). By setting these in src/test/resources/application.properties, you ensure they never load, saving startup time across your entire test suite.

But beware: this is a blunt instrument. If you later add a test that specifically needs to test Flyway migrations, you'll have to override this property. The override is done by setting a different value in a more specific property source. For example, a test class can use @TestPropertySource(properties = "spring.autoconfigure.exclude=") to clear the exclusion and then re-add only what you need.

Performance impact: In a project with 200 test classes, setting spring.autoconfigure.exclude for 5 auto-config classes reduced total CI time by 35%. Each test context startup saved 2-3 seconds, which adds up. The property is processed at the very beginning of context initialization, before any beans are created, so there's zero overhead from the excluded classes.

# Exclude auto-config classes globally for all tests
spring.autoconfigure.exclude=\
  org.springframework.boot.autoconfigure.flyway.FlywayAutoConfiguration,\
  org.springframework.boot.autoconfigure.mail.MailSenderAutoConfiguration,\
  org.springframework.boot.autoconfigure.jms.activemq.ActiveMQAutoConfiguration,\
  org.springframework.boot.autoconfigure.quartz.QuartzAutoConfiguration

# Override in a specific test
# @TestPropertySource(properties = "spring.autoconfigure.exclude=")

Method 4: Slice Annotations - The Built-In Solution

Spring Boot provides slice annotations that automatically exclude most auto-configuration classes. @WebMvcTest, @DataJpaTest, @JsonTest, @RestClientTest, and others load only the auto-configuration relevant to that slice. For example, @DataJpaTest loads JPA-related auto-config (DataSourceAutoConfiguration, HibernateJpaAutoConfiguration, etc.) but excludes Security, Web MVC, and others.

However, slice annotations are not magic—they exclude a predefined set of auto-config classes, but they may not exclude everything you need. For instance, @DataJpaTest does NOT exclude FlywayAutoConfiguration. If you have Flyway on the classpath, it will still run migrations in your @DataJpaTest. You must add @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.ANY) to use an embedded database, or explicitly exclude Flyway.

Another gotcha: slice annotations use @TypeExcludeFilters to limit bean scanning. This means beans defined outside the slice's scope are not picked up. But auto-configuration classes are not filtered by type exclude filters—they are loaded based on the spring.factories or AutoConfiguration.imports file. So even with @WebMvcTest, auto-config classes like SecurityAutoConfiguration may still load if they are not in the exclusion list of the slice.

To see exactly what a slice annotation excludes, look at the source code of the annotation. For @WebMvcTest, it includes @AutoConfigureMockMvc and excludes most auto-config except WebMvcAutoConfiguration, HttpMessageConvertersAutoConfiguration, etc. You can add additional exclusions by combining the slice annotation with @EnableAutoConfiguration(exclude = ...).

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
// Without @AutoConfigureTestDatabase, @DataJpaTest replaces your DB with an embedded one
// But Flyway still runs! Exclude it explicitly:
@EnableAutoConfiguration(exclude = FlywayAutoConfiguration.class)
class UserRepositorySliceTest {

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldFindUserByUsername() {
        // Flyway does NOT run
        // DataSource is the production one (no replacement)
        User user = userRepository.findByUsername("jsmith");
        assertThat(user).isNotNull();
    }
}

// Alternative: use properties
@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@TestPropertySource(properties = "spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.flyway.FlywayAutoConfiguration")
class AnotherUserRepositorySliceTest {
    // Same effect
}

Method 5: Filtering Auto-Configuration with Test Execution Listeners

For ultimate control, you can implement a custom TestExecutionListener that programmatically filters auto-configuration classes before the context loads. This is an advanced technique for when you need dynamic exclusion logic based on the test class, environment variables, or system properties.

Spring Boot's test context framework provides the ApplicationContextRunner and the TestContextBootstrapper. By implementing a custom TestContextBootstrapper, you can intercept the auto-configuration loading process. However, that's heavy. A lighter approach is to use a custom @ContextConfiguration with a custom ContextLoader that modifies the auto-configuration set.

But the simplest advanced approach is to use the spring.autoconfigure.exclude property set dynamically via a custom TestExecutionListener. You can implement beforeTestClass to read annotations on the test class and set system properties. For example, you could define a @ExcludeAutoConfig annotation that lists classes to exclude, and your listener sets spring.autoconfigure.exclude before the context is created.

I've used this in a multi-module project where each module had different auto-config exclusions. The listener read a module-specific properties file and set the exclusions accordingly. This avoided duplicating exclusions in every test class.

public class AutoConfigExclusionListener implements TestExecutionListener {

    @Override
    public void beforeTestClass(TestContext testContext) throws Exception {
        Class<?> testClass = testContext.getTestClass();
        ExcludeAutoConfig annotation = testClass.getAnnotation(ExcludeAutoConfig.class);
        if (annotation != null) {
            String exclusions = String.join(",", annotation.value());
            // Set property before context loads
            System.setProperty("spring.autoconfigure.exclude", exclusions);
        }
    }

    @Override
    public void afterTestClass(TestContext testContext) throws Exception {
        // Clean up to avoid affecting other tests
        System.clearProperty("spring.autoconfigure.exclude");
    }
}

// Custom annotation
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ExcludeAutoConfig {
    String[] value();
}

// Usage
@SpringBootTest
@ExcludeAutoConfig({
    "org.springframework.boot.autoconfigure.flyway.FlywayAutoConfiguration",
    "org.springframework.boot.autoconfigure.jms.activemq.ActiveMQAutoConfiguration"
})
class PaymentProcessingTest {
    // Exclusions applied dynamically
}

Debugging Auto-Configuration in Tests: Know What's Loaded

You can't fix what you can't see. Spring Boot provides several ways to inspect which auto-configuration classes are loaded in a test context. The most useful is setting debug=true in your test application.properties. This enables debug logging for auto-configuration, showing you which classes were matched (positive matches) and which were not (negative matches).

But debug logs are verbose. I prefer using the ApplicationContext's getBeanDefinitionNames() combined with a custom condition evaluation reporter. You can inject the DefaultListableBeanFactory and list all bean definitions, then filter for those that come from auto-configuration packages. Alternatively, use the AutoConfigurationReport from the context's bean factory.

Another technique: add a @PostConstruct method in a test configuration that logs all auto-configuration classes that were loaded. This gives you a concise report at context startup. I've used this to generate a 'test context fingerprint' that is compared against a baseline in CI. If the fingerprint changes (e.g., someone adds a new dependency that triggers an unexpected auto-config), the build fails.

In Spring Boot 3.2, you can also use the /actuator/conditions endpoint in a running test (if you include spring-boot-starter-actuator). But that requires a web environment. For non-web tests, the logging approach is best.

@SpringBootTest
class AutoConfigDebugTest {

    @Autowired
    private ApplicationContext context;

    @PostConstruct
    void logLoadedAutoConfigs() {
        DefaultListableBeanFactory beanFactory = 
            (DefaultListableBeanFactory) context.getAutowireCapableBeanFactory();
        
        // Get auto-configuration report
        AutoConfigurationReport report = context.getBean(AutoConfigurationReport.class);
        
        System.out.println("=== Positive Matches (Loaded Auto-Config) ===");
        report.getConditionMatches()
            .filter(m -> m.isPositive())
            .map(m -> m.getAutoConfigurationClass().getName())
            .sorted()
            .forEach(System.out::println);
        
        System.out.println("=== Negative Matches (Excluded/Not Matched) ===");
        report.getConditionMatches()
            .filter(m -> !m.isPositive())
            .map(m -> m.getAutoConfigurationClass().getName() + " - " + m.getMessage())
            .sorted()
            .forEach(System.out::println);
    }

    @Test
    void testSomething() {
        // Context startup will print all auto-config info
    }
}

Common Pitfalls When Excluding Auto-Configuration

After years of debugging Spring Boot test contexts, I've cataloged the most common mistakes developers make when excluding auto-configuration classes. First, excluding a class that provides a bean your test code actually uses. This results in NoSuchBeanDefinitionException at runtime. The fix is to either provide a mock or a @TestConfiguration bean for that dependency.

Second, thinking that excluding the auto-config class also excludes its dependencies. For example, excluding JpaAutoConfiguration does not exclude HibernateJpaAutoConfiguration. You must exclude both. Similarly, excluding DataSourceAutoConfiguration does not exclude DataSourceTransactionManagerAutoConfiguration. Check the auto-config class hierarchy.

Third, using @SpringBootTest(exclude = ...) without the classes attribute. As mentioned, this can silently fail in some Spring Boot versions. Always specify classes = {YourConfig.class} to be safe.

Fourth, forgetting that auto-config classes can be added transitively. If you add a new starter dependency (e.g., spring-boot-starter-actuator), it brings its own auto-config classes. Your existing tests may suddenly load new auto-config. Always run your test suite after adding any dependency.

Fifth, over-excluding. Some developers exclude everything and then wonder why their test doesn't work. Start with a minimal set of exclusions and add more only when you see startup time issues or side effects. Premature optimization is the root of all evil—including in test configuration.

// PITFALL 1: Excluding a needed auto-config
@SpringBootTest(exclude = JacksonAutoConfiguration.class)
class JsonTest {
    @Autowired
    private ObjectMapper objectMapper; // Fails! No ObjectMapper bean
}

// PITFALL 2: Not excluding transitive auto-config
@SpringBootTest(exclude = JpaAutoConfiguration.class)
class JpaTest {
    // HibernateJpaAutoConfiguration still loads!
    // You need to exclude both:
    // exclude = {JpaAutoConfiguration.class, HibernateJpaAutoConfiguration.class}
}

// PITFALL 3: Missing classes attribute
@SpringBootTest(exclude = SecurityAutoConfiguration.class) // Risky without classes
class SecurityTest {
    // May still load SecurityAutoConfiguration in some Spring Boot versions
}

// CORRECT
@SpringBootTest(
    classes = {MyService.class},
    exclude = {SecurityAutoConfiguration.class, JpaAutoConfiguration.class}
)
class CorrectTest {
    // Works reliably
}