Spring Boot Test Annotations

Testing is a crucial part of software development. In Spring Boot, annotations make testing simple, fast, and reliable. Understanding these test annotations helps you write robust unit, integration, and web tests efficiently.

---

What is Spring Boot Test Annotations?

Spring Boot Test Annotations are special Java annotations provided by Spring Boot that make testing your application easier, faster, and more organized.

In Spring Boot, testing can involve unit tests, integration tests, web layer tests, database tests, and security tests. Each of these tests may need a slightly different setup, and Spring Boot test annotations help you:

• Load only the parts of your application needed for a specific test
• Mock dependencies so your tests don’t affect real data or services
• Write clean and maintainable tests without too much boilerplate code

Spring Boot Test Annotations are tools that tell Spring Boot how to run your tests efficiently and correctly.

---

List of Spring Boot Test Annotations

Spring Boot provides several test annotations to help developers write unit tests, integration tests, web tests, database tests, and security tests easily. Using the right annotation ensures faster tests, better maintainability, and realistic testing.

1. @SpringBootTest

@SpringBootTest is the go-to annotation for full integration testing in Spring Boot. It loads the complete Spring application context, allowing you to test all layers of your application together.

Key Points:

• Loads Controller → Service → Repository → Database
• Useful for integration tests and end-to-end scenarios
• Works with TestRestTemplate for web endpoints
• Can simulate random ports for web apps

Example:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
classUserApiE2ETest {

@Autowired
private TestRestTemplate restTemplate;

@Test
voidtestCreateUser() {
        ResponseEntity<User> response = restTemplate.postForEntity("/users",newUser("Alice"), User.class);
        Assertions.assertEquals(HttpStatus.OK, response.getStatusCode());
    }
}

---

2. @WebMvcTest

@WebMvcTest is used for testing the web layer only. It does not load the full application context, making your tests fast and focused on controllers and REST endpoints.

Key Points:

• Tests request mappings, HTTP status, and response structure
• Automatically configures MockMvc for HTTP request simulation
• Use @MockBean to mock service dependencies

Example:

@WebMvcTest(UserController.class)
classUserControllerTest {

@Autowired
private MockMvc mockMvc;

@MockBean
private UserService userService;

@Test
voidtestGetUser()throws Exception {
        Mockito.when(userService.getUserById(1L)).thenReturn(newUser("Alice"));
        mockMvc.perform(get("/users/1"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.name").value("Alice"));
    }
}

---

3. @DataJpaTest

@DataJpaTest is designed for repository testing. It loads only the JPA components and configures an in-memory database, allowing you to test CRUD operations and queries efficiently.

Key Points:

• Tests repositories and database interactions
• Uses H2 in-memory database by default
• Helps verify entity mappings and JPQL / SQL queries

Example:

@DataJpaTest
classUserRepositoryTest {

@Autowired
private UserRepository userRepository;

@Test
voidtestFindByName() {
        userRepository.save(newUser("Alice"));
Userfound= userRepository.findByName("Alice");
        Assertions.assertNotNull(found);
    }
}

---

4. @MockBean

@MockBean is used to mock Spring beans in your test context. It allows you to replace real components with mock implementations for isolated testing.

Key Points:

• Used with unit tests and web layer tests
• Helps avoid calling real services or databases
• Works with Mockito for behavior verification

Example:

@MockBean
private UserService userService;

---

5. @SpyBean

@SpyBean wraps an existing Spring bean with a Mockito spy, allowing you to monitor interactions while still using the real implementation.

Key Points:

• Useful when you want to track method calls on a real bean
• Works well with integration tests
• Can replace or wrap existing beans

Example:

@SpyBean
private UserService userService;

---

6. @TestConfiguration

@TestConfiguration allows you to define beans specifically for testing. Unlike a regular @Configuration, these beans are only loaded during tests.

Key Points:

• Overrides existing beans if needed
• Keeps test context isolated
• Useful for mock services or repositories

Example:

@TestConfiguration
staticclassTestConfig {
@Bean
public UserServiceuserService() {
returnnewUserService();
    }
}

---

7. @TestPropertySource

@TestPropertySource allows you to override or add properties in the Spring Environment specifically for tests.

Example:

@TestPropertySource(properties = "app.feature.enabled=true")
@SpringBootTest
classFeatureTest {}

---

8. @ExtendWith(MockitoExtension.class)

Integrates Mockito into JUnit 5 tests for mocking dependencies without loading the Spring context.

Key Points:

• Supports @Mock and @InjectMocks
• Keeps unit tests fast and lightweight
• Ideal for service and component testing

Example:

@ExtendWith(MockitoExtension.class)
classUserServiceTest {

@Mock
private UserRepository userRepository;

@InjectMocks
private UserService userService;

@Test
voidtestGetUserById() {
        Mockito.when(userRepository.findById(1L)).thenReturn(Optional.of(newUser("Alice")));
Userresult= userService.getUserById(1L);
        Assertions.assertEquals("Alice", result.getName());
    }
}

---

9. @AutoConfigureMockMvc

Used with @SpringBootTest to auto-configure MockMvc for testing controllers in a fully loaded Spring context.

Key Points:

• Simulates HTTP requests realistically
• Works with JSON request/response validation
• Useful for web integration tests

Example:

@SpringBootTest
@AutoConfigureMockMvc
classUserControllerIntegrationTest {

@Autowired
private MockMvc mockMvc;

@Test
voidtestGetUsers()throws Exception {
        mockMvc.perform(get("/users"))
               .andExpect(status().isOk());
    }
}

---

10. @WithMockUser

Used for Spring Security testing by simulating a logged-in user.

Key Points:

• Test secured endpoints without real login
• Supports roles and authorities
• Can be combined with @SpringBootTest or @WebMvcTest

Example:

@WithMockUser(username = "admin", roles = "ADMIN")
@Test
voidadminAccessTest()throws Exception {
    mockMvc.perform(get("/admin/dashboard"))
           .andExpect(status().isOk());
}

---

11. @Testcontainers

Runs integration tests with real Docker containers for databases, message brokers, or other services.

Key Points:

• Provides realistic testing environment
• Ensures behavior matches production
• Works well with @SpringBootTest

Example:

@Testcontainers
@SpringBootTest
classUserServiceTest {

@Container
static PostgreSQLContainer<?> postgres =newPostgreSQLContainer<>("postgres:15");

@Autowired
private UserRepository userRepository;

@Test
voidtestSaveUser() {
Useruser=newUser("Alice");
        userRepository.save(user);
        Assertions.assertEquals(1, userRepository.count());
    }
}

---

12. @AutoConfigureWireMock

Mocks external HTTP APIs to prevent calling real services.

Key Points:

• Spins up a WireMock server for tests
• Useful for testing API responses, errors, and edge cases
• Works with @SpringBootTest for integration testing

Example:

@AutoConfigureWireMock(port = 0)
@SpringBootTest
classPaymentClientTest {

@Autowired
private PaymentService paymentService;

@Test
voidtestPaymentProcessing() {
        stubFor(post(urlEqualTo("/payments"))
                .willReturn(aResponse()
                .withStatus(200)
                .withBody("{\\"status\\":\\"success\\"}")));

PaymentResponseresponse= paymentService.processPayment(100);
        Assertions.assertEquals("success", response.getStatus());
    }
}

---

Difference: @SpringBootTest vs @WebMvcTest vs @DataJpaTest

Feature	@SpringBootTest	@WebMvcTest	@DataJpaTest
Layers Loaded	All layers: Controller, Service, Repository, DB	Only Web layer: Controller, Filter	Only Repository / JPA / Database layer
Database	Real DB or in-memory DB	No DB (mock dependencies with @MockBean)	In-memory DB by default (H2)
Speed	Slow	Fast	Fast
Use Case	Full integration / end-to-end tests	Controller / REST API testing	Repository / database testing
Dependencies	Loads all beans	Only web beans loaded; other dependencies mocked	Only JPA beans loaded; services not included

---

Other Useful Spring Testing Annotations

The Spring Framework provides a set of annotations beyond Spring Boot’s core test annotations. These help control the application context, manage transactions, run SQL scripts, and monitor test lifecycle events. They are essential for integration tests, complex application contexts, and transactional scenarios.

1. @BootstrapWith

Customizes how the Spring test context is bootstrapped for a test class.

Key Points:

• Allows custom initialization of the Spring TestContext.
• Rarely needed in everyday tests, mainly used in advanced testing scenarios.

Example:

@BootstrapWith(CustomTestContextBootstrapper.class)
classCustomBootstrapTest {
@Test
voidtestSomething() {
// Custom context setup applied
    }
}

---

2. @ContextConfiguration

Loads specific configuration classes or XML files for tests.

Key Points:

• Can load multiple configurations.
• Useful for testing subsets of the application or legacy XML-based beans.

Example:

@ContextConfiguration(classes = {AppConfig.class, TestConfig.class})
classAppServiceTest {
@Autowired
private UserService userService;

@Test
voidtestUserCreation() {
        assertNotNull(userService);
    }
}

---

3. @WebAppConfiguration

Marks a test as a web application test and sets the root directory for web resources.

Key Points:

• Required for testing Spring MVC controllers with WebApplicationContext.
• Often combined with MockMvc for controller tests.

Example:

@WebAppConfiguration
@ContextConfiguration(classes = WebAppConfig.class)
classWebControllerTest {
@Autowired
private WebApplicationContext wac;

@Test
voidtestController() {
MockMvcmockMvc= MockMvcBuilders.webAppContextSetup(wac).build();
        mockMvc.perform(get("/users"))
               .andExpect(status().isOk());
    }
}

---

4. @ActiveProfiles

Activates specific Spring profiles for tests.

Key Points:

• Useful for environment-specific testing (dev, test, prod).
• Switches beans and configurations without changing main code.

Example:

@ActiveProfiles("test")
@SpringBootTest
classProfileBasedTest {
@Autowired
private UserRepository userRepository;

@Test
voidtestProfileBeans() {
        assertTrue(userRepositoryinstanceof TestUserRepository);
    }
}

---

5. @TestExecutionListeners

Registers custom listeners for test lifecycle events.

Key Points:

• Can run logic before/after context initialization or test methods.
• Useful for transaction management, mock processing, or event recording.

Example:

@TestExecutionListeners(listeners = MyCustomTestListener.class)
@SpringBootTest
classTestListenerExample {
@Test
voidtestSomething() {
// Listener logic runs automatically
    }
}

---

6. @Sql / @SqlConfig

Run SQL scripts before or after tests to prepare or clean database state.

Key Points:

• Can initialize database with test data and clean up afterward.
• @SqlConfig allows custom data source, encoding, or transaction behavior.

Example:

@Sql(scripts = "/test-data.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_METHOD)
@Sql(scripts = "/cleanup.sql", executionPhase = Sql.ExecutionPhase.AFTER_TEST_METHOD)
@DataJpaTest
classUserRepositoryTest {
@Autowired
private UserRepository userRepository;

@Test
voidtestInsertUser() {
        userRepository.save(newUser("Alice"));
        assertEquals(1, userRepository.count());
    }
}

---

7. @Commit / @Rollback

Control transaction behavior in tests.

Key Points:

• By default, Spring rolls back transactions after each test.
• Use @Commit to persist changes or @Rollback to explicitly roll back.

Example:

@SpringBootTest
@Transactional
classTransactionTest {

@Test
@Commit
voidtestCommitTransaction() {
        userRepository.save(newUser("Bob"));
    }

@Test
@Rollback
voidtestRollbackTransaction() {
        userRepository.save(newUser("Charlie"));
    }
}

---

8. @DirtiesContext

Marks the Spring context as dirty, forcing it to reload for subsequent tests.

Key Points:

• Ensures changes in one test do not affect others.
• Can be applied at method or class level.

Example:

@SpringBootTest
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
classDirtyContextTest {
@Test
voidmodifyBean() {
        myService.setValue(42);
    }
}

---

9. @RecordApplicationEvents

Records Spring events published during a test.

Key Points:

• Allows verification of ApplicationEvent, ContextRefreshedEvent, or custom events.
• Useful for testing event-driven applications.

Example:

@SpringBootTest
@RecordApplicationEvents
classEventTest {

@Autowired
private ApplicationEventPublisher publisher;

@Autowired
private ApplicationEvents events;

@Test
voidtestEventPublishing() {
        publisher.publishEvent(newCustomEvent(this,"Hello"));
        assertThat(events.stream(CustomEvent.class))
            .anyMatch(e -> e.getMessage().equals("Hello"));
    }
}

---

Conclusion

Understanding Spring Boot Test Annotations is essential for writing reliable and maintainable tests.

• Use @SpringBootTest for full application tests
• Use @WebMvcTest for controller testing
• Use @DataJpaTest for repository/database tests
• Use @MockBean and Mockito for isolated unit tests
• Use @AutoConfigureMockMvc for realistic web layer testing

By combining these annotations effectively, you can build a robust test suite that ensures your application works correctly, reduces bugs, and speeds up development.