Gradle中test.include与test.filter.includeTestsMatching的核心差异

网上很多示例用test.include做测试过滤：

test {
    useJUnitPlatform()
    include("**/*IT*")
}

官方说明：includes - 测试执行的包含模式（基于文件路径）

而Gradle Java测试官方文档更推荐用test.filter.includeTestsMatching：

test {
    useJUnitPlatform()
    filter {
        includeTestsMatching("*IT*")
    }
}

官方说明：includeTestsMatching - 向包含过滤器追加测试名称模式

除了后者支持方法级过滤之外，两者还有这些核心差异：

• 过滤维度本质不同
  test.include是文件系统路径层面的过滤，它根据类文件的路径/文件名来筛选，比如**/*IT*会匹配所有路径中包含IT的.class文件，不管这个类是不是测试类。而test.filter.includeTestsMatching是测试元素层面的过滤，直接针对测试框架识别出的测试类、测试方法的名称（支持简单名或完全限定名）进行匹配，只作用于真正的测试元素。

• 匹配精度与安全性不同
  用test.include可能会误匹配到非测试类——比如某个普通业务类的路径或文件名刚好包含IT，也会被纳入测试执行范围，导致不必要的执行错误。而includeTestsMatching只会匹配测试框架标记为测试的类/方法，不会出现这种误判。

• 与测试框架的集成深度不同
  test.filter是Gradle专为测试任务设计的过滤API，和JUnit Platform等测试框架的集成更紧密，能直接利用测试框架提供的测试元数据。而test.include是更底层的文件筛选逻辑，相当于先把符合路径规则的文件挑出来，再丢给测试框架去识别哪些是测试类，属于“先筛选文件再识别测试”的流程。

• 组合过滤的灵活性不同
  test.filter支持多种过滤规则的组合使用，比如可以同时指定includeTestsMatching、excludeTestsMatching，还能结合includeTags（JUnit 5标签过滤）等规则，实现更复杂的测试筛选逻辑。而test.include只能做文件路径层面的包含/排除，和filter的规则混合使用时逻辑会更混乱，灵活性远不如前者。

内容的提问来源于stack exchange，提问作者Alterant