测试开发规范

测试分层策略

层次 测试类型 启动 Spring 执行速度

单元测试 工具类/枚举/POJO 否 < 1s

集成测试 Service/Controller/Mapper 是（@SpringBootTest ） 5-10s

测试文件位置

src/test/java/org/dromara/test/ # 通用测试 src/test/java/org/dromara/{模块}/ # 模块测试（与源码包路径一致）

重要：@SpringBootTest 只能在 SpringBoot 主包下使用（需包含 main 方法和 yml 配置）。

1. 单元测试（纯 JUnit5，无 Spring）

package org.dromara.test;

import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test;

@DisplayName("StringUtils 测试") public class StringUtilsTest {

@Test
@DisplayName("测试 isBlank 方法")
public void testIsBlank() {
    Assertions.assertTrue(StringUtils.isBlank(null));
    Assertions.assertTrue(StringUtils.isBlank(""));
    Assertions.assertFalse(StringUtils.isBlank("hello"));
}

@Test
@DisplayName("测试异常抛出")
public void testThrowsException() {
    Assertions.assertThrows(NullPointerException.class, () -> {
        String str = null;
        str.length();
    });
}

}

2. Service 集成测试

@SpringBootTest @Transactional // 测试后自动回滚，不污染数据库 @DisplayName("TestDemo Service 测试") public class TestDemoServiceTest {

@Autowired
private ITestDemoService testDemoService;

@Test
@DisplayName("测试添加数据")
public void testAdd() {
    // Arrange
    TestDemoBo bo = new TestDemoBo();
    bo.setDeptId(103L);
    bo.setUserId(1L);
    bo.setTestKey("测试数据");
    bo.setValue("test_value");

    // Act
    Boolean result = testDemoService.insertByBo(bo);

    // Assert
    Assertions.assertTrue(result);
}

@Test
@DisplayName("测试查询详情")
public void testGetById() {
    TestDemoBo bo = new TestDemoBo();
    bo.setTestKey("测试查询");
    bo.setValue("test_query");
    testDemoService.insertByBo(bo);

    TestDemoVo vo = testDemoService.queryById(bo.getId());
    Assertions.assertNotNull(vo);
    Assertions.assertEquals("测试查询", vo.getTestKey());
}

}

Mock 外部依赖

@SpringBootTest @DisplayName("订单服务测试") public class OrderServiceTest {

@Autowired
private IOrderService orderService;

@MockBean
private IPaymentService paymentService;

@Test
@DisplayName("测试订单支付（Mock 支付服务）")
public void testPayOrder() {
    Long orderId = 123L;
    Mockito.when(paymentService.pay(orderId)).thenReturn(true);

    Boolean success = orderService.payOrder(orderId);

    Assertions.assertTrue(success);
    Mockito.verify(paymentService, Mockito.times(1)).pay(orderId);
}

}

3. Controller 测试

@SpringBootTest @AutoConfigureMockMvc @DisplayName("TestDemo Controller 测试") public class TestDemoControllerTest {

@Autowired
private MockMvc mockMvc;

@Test
@DisplayName("测试分页查询")
public void testPageList() throws Exception {
    mockMvc.perform(get("/demo/demo/list")
            .param("pageNum", "1")
            .param("pageSize", "10"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.code").value(200));
}

@Test
@DisplayName("测试添加数据")
public void testAdd() throws Exception {
    String requestBody = """
        {
            "deptId": 103,
            "userId": 1,
            "testKey": "测试数据",
            "value": "test_value"
        }
        """;

    mockMvc.perform(post("/demo/demo")
            .contentType(MediaType.APPLICATION_JSON)
            .content(requestBody))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.code").value(200));
}

}

4. 参数化测试

@DisplayName("参数化测试") public class ParamUnitTest {

@ParameterizedTest
@ValueSource(strings = {"t1", "t2", "t3"})
public void testValueSource(String str) {
    Assertions.assertNotNull(str);
}

@ParameterizedTest
@EnumSource(UserType.class)
public void testEnumSource(UserType type) {
    Assertions.assertNotNull(type);
}

@ParameterizedTest
@CsvSource({"1, Banner, 横幅广告", "2, Popup, 弹窗广告"})
public void testCsvData(String code, String name, String desc) {
    Assertions.assertNotNull(code);
}

@ParameterizedTest
@MethodSource("getParam")
public void testMethodSource(String str) {
    Assertions.assertNotNull(str);
}

public static Stream<String> getParam() {
    return Stream.of("t1", "t2", "t3");
}

}

更多参数化测试示例详见 references/parameterized-examples.md

5. 异常测试

@Test @DisplayName("测试 key 为空抛出异常") public void testAdd_ThrowsException() { TestDemoBo bo = new TestDemoBo(); // 不设置必填字段

ServiceException exception = Assertions.assertThrows(
    ServiceException.class,
    () -> testDemoService.insertByBo(bo)
);
Assertions.assertTrue(exception.getMessage().contains("key键不能为空"));

}

6. 测试标签（@Tag）

@Test @Tag("dev") public void testDev() { } @Test @Tag("prod") public void testProd() { }

mvn test -Dgroups=dev # 运行 dev 标签 mvn test -DexcludedGroups=prod # 排除 prod 标签

运行测试

mvn test # 运行所有测试 mvn test -Dtest=AdServiceTest # 运行单个测试类 mvn test -Dtest=AdServiceTest#testAddAd # 运行单个方法 mvn clean install -DskipTests # 跳过测试

开发检查清单

命名规范

• 测试类：{被测试类名}Test

• 测试方法：test{功能}

• 使用 @DisplayName 添加中文描述

• 位于 src/test/java ，包路径与源码一致

注解选择

场景 注解组合

工具类/枚举/POJO 不加 @SpringBootTest

Service 测试 @SpringBootTest

• @Transactional

Controller 测试 @SpringBootTest

• @AutoConfigureMockMvc

Mock Spring Bean @MockBean

Mock（纯单元测试） @Mock

• @InjectMocks

常见错误

错误 正确做法

测试在 src/main/java

放到 src/test/java

缺少 @DisplayName

必须添加描述

需要注入但没加 @SpringBootTest

加上注解

@SpringBootTest 在非主包下 确保在主类同包或子包

Mock 后不验证调用 Mockito.verify()

测试方法相互依赖 每个测试独立

Service 测试不加 @Transactional

加上防止污染数据库