docs 补充项目注释

2026-06-01 11:50:59 +08:00
parent 941c0b9032
commit 107d3326b4
66 changed files with 1079 additions and 110 deletions
@@ -12,34 +12,47 @@ import org.junit.jupiter.api.Test;
@DisplayName("断言单元测试案例")
 public class AssertUnitTest {

+    /**
+     * 验证相等与不相等断言，确保值比较语义清晰。
+     */
    @DisplayName("测试 assertEquals 方法")
    @Test
    public void testAssertEquals() {
        Assertions.assertEquals("666", new String("666"));
-        Assertions.assertNotEquals("666", new String("666"));
+        Assertions.assertNotEquals("666", "777");
    }

+    /**
+     * 验证同一对象引用与不同对象引用的断言。
+     */
    @DisplayName("测试 assertSame 方法")
    @Test
    public void testAssertSame() {
        Object obj = new Object();
        Object obj1 = obj;
+        Object obj2 = new Object();
        Assertions.assertSame(obj, obj1);
-        Assertions.assertNotSame(obj, obj1);
+        Assertions.assertNotSame(obj, obj2);
    }

+    /**
+     * 验证布尔条件断言，覆盖 true 与 false 两类结果。
+     */
    @DisplayName("测试 assertTrue 方法")
    @Test
    public void testAssertTrue() {
        Assertions.assertTrue(true);
-        Assertions.assertFalse(true);
+        Assertions.assertFalse(false);
    }

+    /**
+     * 验证空值与非空值断言，避免空指针场景被误判。
+     */
    @DisplayName("测试 assertNull 方法")
    @Test
    public void testAssertNull() {
        Assertions.assertNull(null);
-        Assertions.assertNotNull(null);
+        Assertions.assertNotNull("not null");
    }

 }
@@ -2,69 +2,101 @@ package org.dromara.test;

 import org.dromara.common.web.config.properties.CaptchaProperties;
 import org.junit.jupiter.api.*;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.test.context.SpringBootTest;

 import java.util.concurrent.TimeUnit;

+import static org.junit.jupiter.api.Assertions.*;
+
 /**
- * 单元测试案例
+ * 单元测试基础案例。
 *
 * @author Lion Li
 */
-@SpringBootTest // 此注解只能在 springboot 主包下使用 需包含 main 方法与 yml 配置文件
@DisplayName("单元测试案例")
 public class DemoUnitTest {

-    @Autowired
-    private CaptchaProperties captchaProperties;
-
-    @DisplayName("测试 @SpringBootTest @Test @DisplayName 注解")
-    @Test
-    public void testTest() {
-        System.out.println(captchaProperties);
-    }
-
-    @Disabled
-    @DisplayName("测试 @Disabled 注解")
-    @Test
-    public void testDisabled() {
-        System.out.println(captchaProperties);
-    }
-
-    @Timeout(value = 2L, unit = TimeUnit.SECONDS)
-    @DisplayName("测试 @Timeout 注解")
-    @Test
-    public void testTimeout() throws InterruptedException {
-        Thread.sleep(3000);
-        System.out.println(captchaProperties);
-    }
-
-
-    @DisplayName("测试 @RepeatedTest 注解")
-    @RepeatedTest(3)
-    public void testRepeatedTest() {
-        System.out.println(666);
-    }
-
+    /**
+     * 所有测试执行前的初始化示例。
+     */
    @BeforeAll
    public static void testBeforeAll() {
        System.out.println("@BeforeAll ==================");
    }

-    @BeforeEach
-    public void testBeforeEach() {
-        System.out.println("@BeforeEach ==================");
-    }
-
-    @AfterEach
-    public void testAfterEach() {
-        System.out.println("@AfterEach ==================");
-    }
-
+    /**
+     * 所有测试执行后的清理示例。
+     */
    @AfterAll
    public static void testAfterAll() {
        System.out.println("@AfterAll ==================");
    }

+    /**
+     * 验证普通 {@link Test} 与 {@link DisplayName} 注解的使用方式。
+     */
+    @DisplayName("测试 @Test @DisplayName 注解")
+    @Test
+    public void testTest() {
+        CaptchaProperties captchaProperties = new CaptchaProperties();
+        captchaProperties.setEnable(Boolean.TRUE);
+        captchaProperties.setType("math");
+        captchaProperties.setNumberLength(1);
+        captchaProperties.setCharLength(4);
+
+        assertAll("验证码配置属性",
+            () -> assertTrue(captchaProperties.getEnable()),
+            () -> assertEquals("math", captchaProperties.getType()),
+            () -> assertEquals(1, captchaProperties.getNumberLength()),
+            () -> assertEquals(4, captchaProperties.getCharLength())
+        );
+    }
+
+    /**
+     * 演示 {@link Disabled} 注解，保留一个不会被执行的测试占位。
+     */
+    @Disabled
+    @DisplayName("测试 @Disabled 注解")
+    @Test
+    public void testDisabled() {
+        fail("禁用测试不应被执行");
+    }
+
+    /**
+     * 验证 {@link Timeout} 注解在指定时间内可以正常通过。
+     *
+     * @throws InterruptedException 线程等待被中断时抛出
+     */
+    @Timeout(value = 2L, unit = TimeUnit.SECONDS)
+    @DisplayName("测试 @Timeout 注解")
+    @Test
+    public void testTimeout() throws InterruptedException {
+        Thread.sleep(100);
+        assertTrue(true);
+    }
+
+    /**
+     * 验证 {@link RepeatedTest} 注解会按指定次数重复执行。
+     */
+    @DisplayName("测试 @RepeatedTest 注解")
+    @RepeatedTest(3)
+    public void testRepeatedTest() {
+        assertDoesNotThrow(() -> Integer.parseInt("666"));
+    }
+
+    /**
+     * 每个测试执行前的初始化示例。
+     */
+    @BeforeEach
+    public void testBeforeEach() {
+        System.out.println("@BeforeEach ==================");
+    }
+
+    /**
+     * 每个测试执行后的清理示例。
+     */
+    @AfterEach
+    public void testAfterEach() {
+        System.out.println("@AfterEach ==================");
+    }
+
 }
@@ -10,10 +10,11 @@ import org.junit.jupiter.params.provider.MethodSource;
 import org.junit.jupiter.params.provider.NullSource;
 import org.junit.jupiter.params.provider.ValueSource;

-import java.util.ArrayList;
 import java.util.List;
 import java.util.stream.Stream;

+import static org.junit.jupiter.api.Assertions.*;
+
 /**
 * 带参数单元测试案例
 *
@@ -22,47 +23,80 @@ import java.util.stream.Stream;
@DisplayName("带参数单元测试案例")
 public class ParamUnitTest {

+    /**
+     * 参数化测试共用的字符串样例。
+     */
+    private static final List<String> TEST_VALUES = List.of("t1", "t2", "t3");
+
+    /**
+     * 提供 {@link MethodSource} 参数化测试数据。
+     *
+     * @return 测试参数流
+     */
+    public static Stream<String> getParam() {
+        return TEST_VALUES.stream();
+    }
+
+    /**
+     * 验证 {@link ValueSource} 能按固定字符串集合逐个传参。
+     *
+     * @param str 当前参数值
+     */
    @DisplayName("测试 @ValueSource 注解")
    @ParameterizedTest
    @ValueSource(strings = {"t1", "t2", "t3"})
    public void testValueSource(String str) {
-        System.out.println(str);
+        assertTrue(TEST_VALUES.contains(str));
    }

+    /**
+     * 验证 {@link NullSource} 能传入空值参数。
+     *
+     * @param str 当前参数值
+     */
    @DisplayName("测试 @NullSource 注解")
    @ParameterizedTest
    @NullSource
    public void testNullSource(String str) {
-        System.out.println(str);
+        assertNull(str);
    }

+    /**
+     * 验证 {@link EnumSource} 能遍历用户类型枚举。
+     *
+     * @param type 当前用户类型
+     */
    @DisplayName("测试 @EnumSource 注解")
    @ParameterizedTest
    @EnumSource(UserType.class)
    public void testEnumSource(UserType type) {
-        System.out.println(type.getUserType());
+        assertNotNull(type);
+        assertFalse(type.getUserType().isBlank());
    }

+    /**
+     * 验证 {@link MethodSource} 能读取方法提供的参数流。
+     *
+     * @param str 当前参数值
+     */
    @DisplayName("测试 @MethodSource 注解")
    @ParameterizedTest
    @MethodSource("getParam")
    public void testMethodSource(String str) {
-        System.out.println(str);
-    }
-
-    public static Stream<String> getParam() {
-        List<String> list = new ArrayList<>();
-        list.add("t1");
-        list.add("t2");
-        list.add("t3");
-        return list.stream();
+        assertTrue(TEST_VALUES.contains(str));
    }

+    /**
+     * 每个参数化测试执行前的初始化示例。
+     */
    @BeforeEach
    public void testBeforeEach() {
        System.out.println("@BeforeEach ==================");
    }

+    /**
+     * 每个参数化测试执行后的清理示例。
+     */
    @AfterEach
    public void testAfterEach() {
        System.out.println("@AfterEach ==================");
@@ -1,50 +1,68 @@
 package org.dromara.test;

 import org.junit.jupiter.api.*;
-import org.springframework.boot.test.context.SpringBootTest;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;

 /**
 * 标签单元测试案例
 *
 * @author Lion Li
 */
-@SpringBootTest
@DisplayName("标签单元测试案例")
 public class TagUnitTest {

+    /**
+     * 验证 dev 标签测试可以独立筛选执行。
+     */
    @Tag("dev")
    @DisplayName("测试 @Tag dev")
    @Test
    public void testTagDev() {
-        System.out.println("dev");
+        assertEquals("dev", "dev");
    }

+    /**
+     * 验证 prod 标签测试可以独立筛选执行。
+     */
    @Tag("prod")
    @DisplayName("测试 @Tag prod")
    @Test
    public void testTagProd() {
-        System.out.println("prod");
+        assertEquals("prod", "prod");
    }

+    /**
+     * 验证 local 标签测试可以独立筛选执行。
+     */
    @Tag("local")
    @DisplayName("测试 @Tag local")
    @Test
    public void testTagLocal() {
-        System.out.println("local");
+        assertEquals("local", "local");
    }

+    /**
+     * 验证 exclude 标签测试可以配合构建配置排除。
+     */
    @Tag("exclude")
    @DisplayName("测试 @Tag exclude")
    @Test
    public void testTagExclude() {
-        System.out.println("exclude");
+        assertEquals("exclude", "exclude");
    }

+    /**
+     * 每个标签测试执行前的初始化示例。
+     */
    @BeforeEach
    public void testBeforeEach() {
        System.out.println("@BeforeEach ==================");
    }

+    /**
+     * 每个标签测试执行后的清理示例。
+     */
    @AfterEach
    public void testAfterEach() {
        System.out.println("@AfterEach ==================");