本文详解如何在 Maven 中正确配置 Surefire 插件，通过 JUnit 5 的 @Tag 注解（如 @Tag("one")）精准执行标记测试，重点解决因测试类命名不匹配默认规则导致“0 个测试运行”的常见问题。
本文详解如何在 maven 中正确配置 surefire 插件，通过 junit 5 的 `@tag` 注解（如 `@tag("one")`）精准执行标记测试，重点解决因测试类命名不匹配默认规则导致“0 个测试运行”的常见问题。
在 Maven + JUnit 5 项目中，仅靠 <groups>one</groups> 配置或 -Dgroups=one 命令参数不足以触发标签化测试执行——前提是你的测试类未遵循 Surefire 默认的命名约定（如 *Test.java、Test*.java 等）。这是绝大多数开发者遇到 mvn test 执行 0 个测试的根本原因。
Surefire 插件默认仅扫描符合以下通配符模式的 Java 类文件：
- **/Test*.java
- **/*Test.java
- **/*Tests.java
- **/*TestCase.java
而你的测试类名为 BubblegumApiIT.java（以 IT 结尾，属集成测试常见命名），不满足任一默认模式，因此 Surefire 根本不会加载该类，更不会解析其中的 @Tag("one") ——自然无法执行。
✅ 正确解决方案是显式告知 Surefire 哪些类需要被包含，有以下两种推荐方式：
方式一：在 pom.xml 中配置 <includes>（推荐）
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.0.0</version> <!-- 建议使用稳定版，M5 存在已知兼容性问题 -->
<configuration>
<groups>one</groups>
<includes>
<include>**/*IT.java</include> <!-- 匹配所有集成测试类 -->
<!-- 或更精确地： -->
<!-- <include>**/BubblegumApiIT.java</include> -->
</includes>
</configuration>
</plugin>
</plugins>
</build>方式二：使用命令行动态指定（适合临时调试）
mvn -Dgroups=one -Dsurefire.includes="**/*IT.java" test
⚠️ 注意：-Dsurefire.includes 是 Surefire 3.0+ 引入的系统属性，等价于 <includes> 配置；旧版本需用 -Dincludes=（但不推荐降级）。
补充说明与最佳实践
- ✅ @Tag 是 JUnit 5 原生支持的语义化分组机制，完全替代旧版 @Category；
- ✅ 可组合使用多标签：@Tag("one") @Tag("integration")，并通过逗号分隔运行：<groups>one,integration</groups>；
- ⚠️ 确保测试类位于 src/test/java 下，且 maven-compiler-plugin 已正确配置 Java 版本（JUnit 5 要求 ≥ Java 8）；
- ? 验证是否生效：添加 -X 参数查看 Surefire 日志，搜索 Running [.*] 和 Tests run: 行确认实际执行类名；
- ? 若同时存在单元测试（*Test.java）和集成测试（*IT.java），建议分离执行生命周期（如用 maven-failsafe-plugin 运行 *IT.java），避免混淆。
只要确保测试类被 Surefire 发现并加载，<groups> 或 -Dgroups 才能真正生效。命名规范不是约束，而是约定——而 <includes> 是你掌控这一约定的明确契约。
