「译」JUnit 5 系列：条件测试

时间 2019-11-07

标签 junit 系列条件测试栏目 Java 繁體版

原文原文链接

原文地址：http://blog.codefx.org/libraries/junit-5-conditions/
原文日期：08, May, 2016
译文首发：Linesh 的博客：「译」JUnit 5 系列：条件测试
个人 Github：http://github.com/linesh-simplicityjava

上一节咱们了解了 JUnit 新的扩展模型，了解了它是如何支持咱们向引擎定制一些行为的。而后我还预告会为你们讲解条件测试，这一节主题就是它了。react

条件测试，指的是容许咱们自定义灵活的标准，来决定一个测试是否应该执行。条件（condition）官方的叫法是条件测试执行。git

概述

（若是不喜欢看文章，你能够戳这里看个人演讲，或者看一下最近的 vJUG 讲座，或者我在 DevoxxPL 上的 PPT。github

本系列文章都基于 Junit 5发布的先行版 Milestone 2。它可能会有变化。若是有新的里程碑（milestone）版本发布，或者试用版正式发行时，我会再来更新这篇文章。api

这里要介绍的多数知识你均可以在 JUnit 5 用户指南中找到（这个连接指向的是先行版 Milestone 2，想看的最新版本文档的话请戳这里），而且指南还有更多的内容等待你发掘。下面的全部代码均可以在个人 Github 上找到。架构

动手实现一个@Disabled 注解

最简单的“条件”就是判断都没有，直接禁用测试。若是在方法上发现了 @Disabled 注解，咱们就直接禁用该测试。

让咱们来写一个这样的 @Disabled 注解吧：

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(@DisabledCondition.class)
public @interface Disabled { }

对应的扩展以下：

public class DisabledCondition
        implements ContainerExecutionCondition, TestExecutionCondition {
 
    private static final ConditionEvaluationResult ENABLED =
            ConditionEvaluationResult.enabled("@Disabled is not present");
 
    @Override
    public ConditionEvaluationResult evaluate(
            ContainerExtensionContext context) {
        return evaluateIfAnnotated(context.getElement());
    }
 
    @Override
    public ConditionEvaluationResult evaluate(
            TestExtensionContext context) {
        return evaluateIfAnnotated(context.getElement());
    }
 
    private ConditionEvaluationResult evaluateIfAnnotated(
            Optional<AnnotatedElement> element) {
        Optional<Disabled> disabled = AnnotationUtils
                .findAnnotation(element, Disabled.class);
 
        if (disabled.isPresent())
            return ConditionEvaluationResult
                    .disabled(element + " is @Disabled");
 
        return ENABLED;
    }

}

写起来小菜一碟吧？在 JUnit 真实的产品代码中，@Disabled 也是这么实现的。不过，有两个地方有一些细微的差异：

官方 @Disabled 注解不须要再使用 @ExtendWith 注册扩展，由于它是默认注册了的
官方 @Disabled 注解能够接收一个参数，解释测试被忽略的理由。它会在测试被忽略时被记录下来

使用时请注意，AnnotationUtils 是个内部 API。不过，官方可能很快就会将它提供的功能给开放出来。

接下来让咱们写点更有意思的东西吧。

@DisabledOnOs

若是有些测试咱们只想让它在特定的操做系统上面运行，这个要怎么实现呢？

一种简单的实现方式

固然，咱们仍是从注解开始咯：

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(OsCondition.class)
public @interface DisabledOnOs {
 
    OS[] value() default {};
 
}

这回注解须要接收一个或多个参数值，你须要告诉它想禁用测试的操做系统有哪些。 OS 是个枚举类，定义了全部操做系统的名字。同时，它还提供了一个静态的 static OS determine() 方法，你可能已经从名字猜到了，它会推断并返回你当前所用的操做系统。

如今咱们能够着手实现 OsCondition 扩展类了。它必须检查两点：注解是否存在，以及当前操做系统是否在注解声明的禁用列表中。

public class OsCondition 
        implements ContainerExecutionCondition, TestExecutionCondition {
 
    // both `evaluate` methods forward to `evaluateIfAnnotated` as above
 
    private ConditionEvaluationResult evaluateIfAnnotated(
            Optional<AnnotatedElement> element) {
        Optional<DisabledOnOs> disabled = AnnotationUtils
                .findAnnotation(element, DisabledOnOs.class);
 
        if (disabled.isPresent())
            return disabledIfOn(disabled.get().value());
 
        return ENABLED;
    }
 
    private ConditionEvaluationResult disabledIfOn(OS[] disabledOnOs) {
        OS os = OS.determine();
        if (Arrays.asList(disabledOnOs).contains(os))
            return ConditionEvaluationResult
                    .disabled("Test is disabled on " + os + ".");
        else
            return ConditionEvaluationResult
                    .enabled("Test is not disabled on " + os + ".");
    }

}

而后使用的时候就能够像这样：

@Test
@DisabledOnOs(OS.WINDOWS)
void doesNotRunOnWindows() {
    assertTrue(false);
}

棒。

更简洁的API

但代码还能够写得更好！JUnit 的注解是可组合的，基于此咱们可让这个条件注解更简洁：

@TestExceptOnOs(OS.WINDOWS)
void doesNotRunOnWindowsEither() {
    assertTrue(false);
}

@TestExceptionOnOs完美的实现方案是这样的：

@Retention(RetentionPolicy.RUNTIME)
@Test
@DisabledOnOs(/* 经过某种方式取得注解下的 `value` 值 */)
public @interface TestExceptOnOs {
 
    OS[] value() default {};
 
}

测试实际运行时， OsCondition::evaluateIfAnnotated 方法会扫描 @DisabledOnOs 注解，而后咱们发现它又是对 @TestExceptOnOs 的注解，前面写的代码就能够如期工做了。但我不知道如何在 @DisabledOnOs 注解中获取 @TestExceptOnOs 中的value()值。:(（你能作到吗？）

次佳的选择是，简单地在 @TestExceptOnOs 注解上直接声明应用的扩展就能够了：

@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(OsCondition.class)
@Test
public @interface TestExceptOnOs {
 
    OS[] value() default {};
 
}

而后直接把 OsCondition:evaluateIfAnnotated 方法拉过来改改便可：

private ConditionEvaluationResult evaluateIfAnnotated(
        Optional<Annotatedelement> element) {
    Optional<DisabledOnOs> disabled = AnnotationUtils
        .findAnnotation(element, DisabledOnOs.class);
    if (disabled.isPresent()) 
        return disabledIfOn(disabled.get().value());
        
    Optional<TestExceptOnOs> testExcept = AnnotationUtils
        .findAnnotation(element, TestExceptOnOs.class);
    if (testExcept.isPresent()) 
        return disabledIfOn(testExcept.get().value());
            
    return ConditionEvaluationResult.enabled("");
}

收工。如今咱们能够如期使用这个注解了。

代码重构

咱们还须要建立一个意义恰好相反的注解（即如今变为，当前操做系统不在提供列表时，才禁用测试），工做是相似的，可是注解名会更表意，再加入静态导入后，咱们的代码最终能够整理成这样：

@TestOn(WINDOWS)
void doesNotRunOnWindoesEither() {
    assertTrue(false);
}

还挺好看的，是不？

「译者注：英文中condition有多个意思：“条件；空调”。做者这里配图取双关」

@DisabledIfTestFails

咱们再考虑一种场景——我保证此次能够接触更有意思的东西！假设如今有许多（集成）测试，若是其中有一个抛出了特定的异常而失败，那么其余测试也必须会挂。为了节省时间，咱们但愿在这种状况下直接禁用掉其余的测试。

那么咱们须要作些什么工做呢？首先第一反应不难想到，咱们必须先能收集测试执行过程抛出的异常。这确定须要在单个测试类级别的生命周期中进行处理，不然就可能由于其余测试类中抛出的异常而影响到本测试类的运行。其次，咱们须要一个实现一个条件：它会检查某个特定的异常是否已被抛出过，如果，禁用当前测试。

异常收集

翻阅一下文档中提供的扩展点列表，不难发现有一项“异常处理”，看起来就是咱们想要的东西：

/**
 * TestExecutionExceptionHandler defines the API for Extensions that wish to react to thrown exceptions in tests.
 * 
 * [ ... ]
 */
public interface TestExecutionExceptionHandler extends ExtensionPoint { 
    /**
     * Handle the supplied throwable.
     * 
     * Implementors must perform one of the following.
     * 
     * - Swallow the supplied throwable, thereby preventing propagation
     * - Rethrow the incoming throwable as is 
     * - Throw a new exception, potenially wrapping the supplied throwable 
     *  
     * [ ... ]
     */
    void handleTestExecutionException(
        TestExtensionContext context, Throwable throwable) 
        throws Throwable;    
}

读完发现，咱们的任务就是实现 handleException 方法，存储起接收到的异常并从新抛出。

你可能还记得我提过的关于扩展点和无状态的一些结论：

引擎对扩展实例的初始化时间、实例的生存时间未做出任何规约和保证，所以，扩展必须是无状态的。若是一个扩展须要维持任何状态信息，那么它必须使用 JUnit 提供的一个仓库（store）来进行信息读取和写入。

看来咱们是必须使用这个 store 了。store 其实就是存放咱们但愿保存的一些东西，一个可索引的资源集合。它能够在扩展上下文对象中取得，后者会被传给大多数扩展点接口方法做为参数。不过须要注意的是，每一个不一样的上下文对象都有本身一个独立的 store，因此咱们还必须决定使用哪一个 store。

每一个测试方法有一个本身的上下文对象（TestExtensionContext），同时，测试类也有一个本身的上下文对象（ContainerExtensionContext）。还记得咱们的需求吗？保存测试类中任何测试方法可能抛出的异常，仅此而已。也即，咱们不会保存其余测试类中抛出的异常。这样一来，容器级别的上下文 ContainerExtensionContext 恰好就是咱们须要的了。

接下来，咱们可使用这个容器上下文，经过它来存储全部测试过程抛出的异常：

private static final Namespece NAMESPACE = Namespace
    .of("org", "codefx", "CollectExceptions");
private static final String THROWN_EXCEPTIONS_KEY = "THROWN_EXCEPTION_KEY";

@SuppressWarnings("unchecked")
private static Set<Exception> getThrown(ExtensionContext context) {
    ExtensionContext containerContext = getAncestorContainerContext(context)
        .orElseThrow(IllegalStateException::new);
    retrun (Set<Exception>) containerContext
        .getStore(NAMESPACE)
        .getOrComputeIfAbsent(
            THROWN_EXCEPTIONS_KEY,
            ignoredKey -> new HashSet<>());
}

private static Optional<ExtensionContext> getAncestorContainerContext(
        ExtensionContext context) {
    Optional<ExtensionContext> containerContext = Optional.of(context);
    while (containerContext.isPresent()) 
            && !(containerContext.get() instanceof ContainerExtenstionContext)) 
        containerContext = containerContext.get().getParent();
    return containerContext;
}

如今存储一个异常就很是简单了：

@Override
public void handleException(TestExtensionContext context, Throwable throwable) 
        throws Throwable {
    if (throwable instanceof Exception) {
        getThrown(context).add((Exception) throwable);
    throw throwable;

有意思的是，这个扩展仍是自扩展的，没准还能够用来作数据统计呢「译者注：这句不太理解，原文 This is actually an interesting extension of its own. Maybe it could be used for analytics as well.」。无论怎样，咱们须要一个public方法来拿到已抛出的异常列表：

public static Stream<Exception> getThrownExceptions(
        ExtensionContext context) {
    return getThrown(context).stream();
}

有了这个方法，其余的扩展就能够检查至今为止所抛出的异常列表了。

禁用测试

禁用测试的部分与前节所述十分相似，咱们能够很快写出代码：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(DisabledIfTestFailedCondition.class)
public @interface DisabledIfTestFailedWith {

    Class <? extends Exception>[] value() default {};

}

注意，如今仅容许该注解被用在测试方法上。应用在测试类上也说得过去，不过咱们如今先不把它复杂化。所以咱们只须要实现接口TestExecutionCondition便可。咱们先检查注解是否存在，如果，再拿到用户提供的异常类做为参数，调用 disableIfExceptionWasThrown。

private ConditionEvaluationResult disableIfExceptionWasThrown(
        TestExtensionContext context,
        Class<? extends Exception>[] exceptions) {
    return Arrays.stream(exceptions)
            .filter(ex -> wasThrown(context, ex))
            .findAny().
            .map(thrown -> ConditionEvaluationResult.disabled(
                    thrown.getSimpleName() + "was thrown."))
            .orElseGet(() -> ConditionEvaluationResult.enabled(""));
}

private static boolean wasThrown(
        TestExtensionContext context, Class<? extends Exception> exception) {
    return CollectExceptionExtension.getThrownExceptions(context)
            .map(Object::getClass)
            .anyMatch(exception::isAssignableFrom);
}

集成

至此为止需求完成。如今咱们可使用这个注解，在某个特定类型的异常抛出时禁用测试了：

@CollectExceptions
class DisabledIfFailsTest {
    
    private static boolean failedFirst = false;
    
    @Test
    void throwException() {
        System.out.println("I failed!");
        failedFirst = true;
        throw new RuntimeException();
    }
    
    @Test
    @DisabledIfTestFailedWith(RuntimeException.class)
    void disableIfOtherFailedFirst() {
        System.out.println("Nobody failed yet! (Right?)");
        assertFalse(failedFirst);
    }
    
}

回顾总结

哇哦，本篇的代码还挺多的！不过相信到此你已经能彻底理解怎么在 JUnit 5 中实现条件测试了：

建立一个注解，并使用 @ExtendWith 注解它，而后提供你本身实现的条件类
实现 ContainerExecutionCondition 或/和 TestExecutionCondition
检查测试类上是否应用了你新建立的注解
检查特定条件是否实现，并返回结果

除此之外，咱们还看到注解之间能够组合，学到如何使用 JUnit 提供的 store 来保存数据，以及一个扩展的实现，如何经过自定义注解的加入变得更加优雅。

更多关于旗帜扩展点的故事「译者注：原文为more fun with ~~flag~~ extension points，more fun with flags 是生活大爆炸中谢耳朵讲国旗的故事一部」，请参考下篇文章，咱们会探讨关于参数注入的问题。