解决JUnit Vintage与自定义JUnit引擎的测试重复执行冲突问题

安全阿岳

2026-9-2

问题场景

开发需同时兼容JUnit 4、JUnit 5的深度定制测试框架，已实现自定义JUnit 4运行器（Runner）、自定义JUnit 5测试引擎（TestEngine），两者均可基于测试类/方法上的自定义注解完成测试用例发现。
单独使用JUnit 4执行测试、或JUnit 5环境下仅引入自定义引擎执行时，所有功能运行正常。
当同时引入自定义引擎与JUnit Vintage组件时，同一测试会被两个引擎同时识别，导致测试重复执行两次。
约束：无法调整现有实现架构，必须同时保留自定义Runner+自定义JUnit 5引擎的方案。
预期实现逻辑：在自定义TestEngine的discover阶段，判断本次执行实际生效的测试引擎中是否包含JUnitVintageEngine，如果包含则跳过JUnit 4测试类的识别，交由Vintage引擎处理。判断逻辑需要覆盖所有运行场景：包括引擎自动检测开关状态、已生效的引擎过滤规则、Launcher上额外注册的测试引擎等。
兜底方案说明：已知可直接无条件跳过所有带@RunWith的测试类，强制用户通过Vintage运行JUnit 4用例，但仅将该方案作为最终兜底选项。

最优解决方案

你预期的someJUnitApi.getDetectedEngines()没有直接提供公共API，但是可以通过JUnit Platform自带的SPI机制零侵入实现，完全覆盖所有场景，不需要调整现有核心架构：

首先给自定义TestEngine添加@Order(Integer.MAX_VALUE)注解，标记它为最后一个执行发现流程的引擎，保证其他引擎的发现动作都在它之前完成。

实现LauncherDiscoveryListenerSPI，通过Java SPI机制注册到JUnit Platform，在监听器内维护一个线程级的生效引擎ID集合：

public class EngineRegistryListener implements LauncherDiscoveryListener {
    private static final ThreadLocal<Set<String>> ACTIVE_ENGINES = ThreadLocal.withInitial(HashSet::new);

    @Override
    public void engineDiscoveryStarted(UniqueId engineId) {
        // 引擎ID格式为[engine:xxx]，提取引擎名部分
        String engineName = engineId.getSegments().get(0).getValue();
        ACTIVE_ENGINES.get().add(engineName);
    }

    @Override
    public void launcherDiscoveryFinished(LauncherDiscoveryRequest request) {
        // 整个发现流程结束后清空缓存，避免污染下一次执行
        ACTIVE_ENGINES.remove();
    }

    public static boolean isEngineActive(String engineName) {
        return ACTIVE_ENGINES.get().contains(engineName);
    }
}

在META-INF/services/org.junit.platform.launcher.LauncherDiscoveryListener文件中添加上述监听器的全类名，完成SPI注册。

修改自定义TestEngine的discover方法逻辑：

public final class CustomTestEngine extends HierarchicalTestEngine<CustomEngineExecutionContext> {
    private static final String VINTAGE_ENGINE_ID = "junit-vintage";

    @Override
    public TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {
        boolean vintageActive = EngineRegistryListener.isEngineActive(VINTAGE_ENGINE_ID);
        // 原有扫描测试类的逻辑
        Set<Class<?>> matchedTestClasses = scanMatchedTestClasses(discoveryRequest);
        for (Class<?> testClass : matchedTestClasses) {
            if (vintageActive && isJUnit4TestClass(testClass)) {
                // 跳过JUnit4测试类，交由Vintage引擎调用你的自定义Runner执行
                continue;
            }
            // 原有注册TestDescriptor的逻辑
            registerTestDescriptorForClass(testClass, uniqueId);
        }
        // 其余原有逻辑
    }

    private boolean isJUnit4TestClass(Class<?> clazz) {
        // 可根据自身需求调整判断规则，例如判断是否带@RunWith注解、是否包含org.junit.Test标记的方法
        return clazz.isAnnotationPresent(RunWith.class);
    }
}

这个方案的适配性：

如果用户关闭了引擎自动检测、通过引擎过滤规则排除了Vintage、或没有手动注册Vintage引擎，Vintage就不会触发engineDiscoveryStarted回调，监听器不会记录Vintage的ID，自定义引擎会正常执行全量测试发现，不会漏执行用例。
如果Vintage在本次执行中生效，自定义引擎会自动跳过所有JUnit 4测试类，完全避免重复执行。
不需要修改现有自定义Runner、自定义引擎的核心逻辑，侵入性极低。

如果你不想额外实现SPI监听器，也可以退而求其次使用类路径判断+系统属性判断的组合逻辑：先判断类路径下是否存在Vintage引擎类，再判断是否存在junit.platform.excludeengines等配置属性排除了Vintage，这种方案实现更简单，但无法覆盖用户手动通过Launcher API注册/移除引擎的场景，适合作为轻量实现选项。

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