Spring Boot auto-configuration: register imports and let a user bean win

The downloadable Spring source kit pins Java 21 and Spring Boot 4.0.8 with its managed dependencies. Run mvn test to check the named fixture.

Registration is part of the artifact

ReceiptLabelAutoConfiguration supplies a ReceiptLabel bean with a default Receipt prefix. Its class name appears in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. The source kit includes that resource so registration can be checked instead of relying on a class that happens to be reached by component scanning.

ApplicationContextRunner tests the configuration in a small context. One test sees the default label, another supplies an Invoice label and checks that exactly one label bean remains. A third loads Boot import candidates and checks that the class is registered in the kit resource. These are distinct assertions.

A default must have a replacement boundary

ConditionalOnMissingBean makes the default back off when the user supplies the relevant type. That behavior is useful only if the library documents which bean can be replaced and what contract the replacement must satisfy. Broad scanning of library packages can register the same default through an unintended path.

This fixture has one configuration and one type. Real libraries with optional dependencies need classpath conditions, ordering rules and tests for absent dependencies. Condition basics introduces those decisions; Typed properties is a separate input boundary. The kit has not been published as a separately versioned starter.

Checked source

package in.aitrove.contracts;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
@AutoConfiguration
public class ReceiptLabelAutoConfiguration {
    public record ReceiptLabel(String prefix) {public String render(long id){return prefix+":"+id;}}
    @Bean @ConditionalOnMissingBean
    public ReceiptLabel receiptLabel(){return new ReceiptLabel("Receipt");}
}

Test the boundary

AutoConfigurationContractTest.defaultBeanRendersLabel, userBeanMakesDefaultBackOff and importsResourceRegistersTheConfiguration checks this contract in the source kit. Excerpts belong to the named classes; use the downloadable files for imports, configuration and assertions.

Costs and boundaries

The context tests establish registration, default selection and back-off for the pinned Boot version. They do not test every competing library, classpath combination or packaged starter release. The bean retains one short prefix string; business work and dependency initialization are outside this fixture.

Common Mistakes

• Include the import resource in the packaged artifact.
• Test user-bean back-off rather than only default creation.
• Keep auto-configuration out of broad component scanning.

Read next

Spring Boot auto-configuration: conditions and user-defined beans, Spring ApplicationContext: construct and close an object graph, Spring Boot configuration properties: bind values and reject bad startup input, Java ServiceLoader: provider configuration and lazy discovery.