JUnit与JUnit Platform Console Launcher：命令行执行测试的过滤与报告生成

很多开发者在写单元测试时，习惯依赖IDE的图形界面，比如点击运行按钮就能执行所有测试，但当需要集成到自动化流程、或者想快速批量执行部分测试时，IDE就显得有些繁琐了。今天要聊的就是JUnit家族里的关键工具——JUnit Platform Console Launcher，它能让你在命令行轻松执行JUnit测试，还能灵活过滤测试用例、生成专业报告，完全适配不同基础的开发者。

一、为什么要在命令行用JUnit测试

平时用IDE跑测试时，需要打开整个项目、加载依赖，稍微大一点的项目光启动IDE就要花好几分钟。而命令行测试完全不用这么麻烦，只要有JVM环境，敲几行命令就能跑，特别适合两种场景：一是团队的自动构建流程（比如提交代码后自动跑测试的环节），不能打开IDE就只能用命令行；二是本地快速验证，改了某一小块代码，不用开整个IDE，直接针对修改的功能跑对应的测试，节省时间又不占内存。

二、环境准备

我们用最常用的Maven来管理依赖，只需要配置两个核心依赖就行，一个是JUnit的核心框架，一个是用来在命令行启动测试的控制台工具，具体的pom.xml配置如下，注释里标了每个部分的作用，新手直接复制替换自己项目的groupId、artifactId就行：

<!-- 这是Maven的核心配置文件，用来管理项目依赖和构建规则 -->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId> <!-- 换成你自己的项目组织名 -->
    <artifactId>junit-command-demo</artifactId> <!-- 换成项目名 -->
    <version>1.0-SNAPSHOT</version>
    <!-- 统一管理JUnit的版本，避免不同模块版本冲突 -->
    <properties>
        <junit.jupiter.version>5.9.2</junit.jupiter.version>
    </properties>
    <dependencies>
        <!-- JUnit 5 核心API，写测试用例必须引入 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit.jupiter.version}</version>
            <scope>test</scope>
        </dependency>
        <!-- JUnit 测试执行引擎，负责真正跑测试 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>${junit.jupiter.version}</version>
            <scope>test</scope>
        </dependency>
        <!-- 核心：JUnit Platform Console Launcher，命令行执行测试的工具，会自动从Maven仓库下载 -->
        <dependency>
            <groupId>org.junit.platform</groupId>
            <artifactId>junit-platform-console-standalone</artifactId>
            <version>1.9.2</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <!-- Maven插件，方便后续打包和执行测试 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.0.0-M7</version>
            </plugin>
        </plugins>
    </build>
</project>

配置好pom.xml后，执行mvn clean install就能把依赖下载到本地，接下来就可以写测试用例和执行命令了。

三、命令行执行测试的基础操作

首先得找到JUnit Platform Console Launcher的jar包，它会被下载到Maven的本地仓库，一般路径是~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/，找到里面的jar包后，就能执行测试了。比如先写一个简单的测试用例，放在src/test/java/com/example/test/UserServiceTest.java里，内容如下：

package com.example.test;

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

// 给整个测试类打标签，方便后面过滤
@Tag("smoke")
@Tag("slow")
public class UserServiceTest {

    // 这个测试是快速的，只验证登录逻辑是否正常
    @Test
    @Tag("fast")
    public void testUserLoginSuccess() {
        String username = "test_user";
        assertNotNull(username); // 断言用户名不为空
        assertEquals("test_user", username); // 断言用户名正确
    }

    // 这个测试需要连接数据库，耗时久一点，标为慢测试
    @Test
    @Tag("slow")
    public void testUserRegistration() {
        boolean isRegistered = registerUser("test_user", "123456");
        assertTrue(isRegistered); // 断言注册成功
    }

    // 模拟数据库注册的方法，实际项目里会有真实的数据库操作
    private boolean registerUser(String username, String password) {
        return true;
    }
}

现在执行全量测试，也就是跑项目里所有的测试类，命令如下，把~/.m2/...换成你自己本地的jar包路径：

# 执行所有测试类，--all-classes参数会自动找项目里的测试类
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/junit-platform-console-standalone-1.9.2.jar --all-classes

执行后会打印所有测试的结果，包括成功、失败的数量，新手可以先跑这个命令看看是否配置正确。

四、测试用例的灵活过滤（核心功能）

命令行测试的最大好处就是能灵活过滤不需要跑的测试，不用每次都全量跑，节省时间。这里讲三种最常用的过滤方式，都是经过实际项目验证的：

4.1 按类或方法名过滤

如果只想跑和用户相关的测试，不用跑其他模块的，可以用--include-classname参数，支持正则表达式。比如只跑类名里带User的测试，命令如下：

# 只执行类名中包含"User"的测试，正则表达式.*代表任意字符
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/junit-platform-console-standalone-1.9.2.jar --include-classname ".*User.*" --all-classes

如果只想跑某个特定方法的测试，可以加--include-methodname参数，比如只跑testUserLoginSuccess这个方法：

# 只执行testUserLoginSuccess这个测试方法
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/junit-platform-console-standalone-1.9.2.jar --include-methodname "testUserLoginSuccess" --all-classes

4.2 按标签（Tag）过滤

刚才的测试类里用了@Tag注解打了标签，比如fast、slow、smoke，这种过滤方式最常用，因为标签可以按业务逻辑分组，比如冒烟测试组、性能测试组。比如只想跑fast标签的测试（本地快速验证用），命令如下：

# 只执行标记为fast的测试用例，忽略slow的
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/junit-platform-console-standalone-1.9.2.jar --include-tag fast --all-classes

这个功能特别适合开发时快速验证修改，不用等慢测试跑完，比如改了登录逻辑，直接跑fast标签的测试，几秒钟就能出结果。

4.3 排除不需要的测试

有时候全量跑但只想排除某一部分，比如全量跑测试但排除slow标签的（提交代码前做快速检查），用--exclude-tag参数：

# 执行所有测试，但排除标记为slow的用例，适合提交前的快速校验
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/junit-platform-console-standalone-1.9.2.jar --exclude-tag slow --all-classes

这种组合使用特别灵活，既能保证核心功能正常，又能节省时间。

五、生成测试报告

测试结果除了在命令行看，还可以生成报告，方便CI工具解析或者后续查看，常用的有两种报告格式：

5.1 基础文本报告

直接把结果输出到文本文件，适合快速查看，命令如下，把报告存在当前目录的test-result.txt：

# 把测试结果导出到文本文件，方便后续查看
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/junit-platform-console-standalone-1.9.2.jar --all-classes > test-result.txt

5.2 CI兼容的XML报告

如果要集成到Jenkins、Github Actions这类CI工具，需要生成JUnit XML格式的报告，命令如下，把报告存在test-reports目录：

# 生成JUnit格式的XML报告，CI工具可以直接解析，生成可视化的测试统计
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console-standalone/1.9.2/junit-platform-console-standalone-1.9.2.jar --all-classes --reports-dir ./test-reports

执行后会在test-reports目录生成多个xml文件，CI工具会把这些文件汇总，生成测试用例的通过率、耗时等数据，非常适合团队协作。

六、应用场景

这个工具的应用场景覆盖了开发的各个阶段，主要有四种： 一是持续集成（CI）：提交代码后，CI脚本会自动调用命令行执行测试，过滤掉慢测试，只跑核心用例，每次构建前都能保证代码的核心逻辑正常，不会因为全量测试耗时太久拖慢流程； 二是本地快速开发：改了某一小块功能，直接用标签或类名过滤对应的测试，不用开IDE，几分钟就能验证修改是否正确，适合笔记本性能不足或者项目大的开发者； 三是冒烟测试：上线前，跑所有标记为smoke的测试，快速检查订单、支付等核心流程是否正常，避免全量测试耗时太久影响上线节奏； 四是性能优化排查：单独跑标记为slow的测试，记录执行时间，找到耗时久的用例，针对性优化，提升系统的响应速度。

七、技术优缺点

优点非常明显：首先是轻量，不用依赖IDE，只要JVM就能跑，启动快、下载快；其次是灵活，过滤方式多，类名、方法名、标签都能组合使用，适配各种场景；第三是易集成，生成的报告兼容所有主流CI工具，能融入现有的开发流程，不用换工具。 缺点也有：一是参数多，比如--include-classname、--include-tag这些参数容易记错，需要经常查文档；二是调试不便，没有IDE的断点、单步调试功能，只适合自动化执行，不适合本地复杂的调试；三是新手门槛，第一次用需要找jar包路径，配置依赖时如果版本不匹配会报错，需要花点时间排查。

八、注意事项

使用这个工具时，有几个容易踩坑的点要注意： 一是依赖版本必须匹配，JUnit Platform Console Launcher的版本要和JUnit Jupiter的版本一致，比如Jupiter是5.9.2，启动器也要是1.9.2，不然会出现找不到测试引擎的错误； 二是标签名大小写敏感，代码里写@Tag("Smoke")，命令行里写--include-tag smoke是匹配不到的，必须完全一致，这个是JUnit的特性，要特别注意； 三是报告目录要有写入权限，如果指定的是系统目录，普通用户可能没有权限，改成项目自己的目录就不会有问题； 四是命令路径要正确，如果不想每次都找jar包，可以用Maven的exec插件，命令改成mvn exec:java -Dexec.mainClass="org.junit.platform.console.ConsoleLauncher" -Dexec.args="--include-tag fast --all-classes"，不用手动找jar包，更方便。

九、总结

JUnit Platform Console Launcher是一款非常实用的命令行测试工具，它把测试从IDE的束缚里解放出来，既能用于自动化流程，也能用于本地快速开发，灵活的过滤功能和易集成的报告，让测试变得更轻便高效。不管是刚接触Java测试的新手，还是需要优化CI流程的后端工程师，都能通过它提升测试效率，减少重复操作，让开发过程更流畅。