Package org.junit.jupiter.api.condition

Annotation Type DisabledIf

  • @Target({TYPE,METHOD})
@Retention(RUNTIME)
@Documented
@API(status=EXPERIMENTAL,
     since="5.1")
public @interface DisabledIf
    @DisabledIf is used to determine whether the annotated test class or test method is disabled by evaluating a script.

    The decision is made by interpreting the return value of the supplied script, according to the following table.

    Return Type Evaluation Result
    boolean The annotated element will be disabled if the value is true.
    java.lang.Boolean The annotated element will be disabled if the value is Boolean.TRUE.
    ConditionEvaluationResult An instance of ConditionEvaluationResult will be handled directly by JUnit Jupiter as if the script were an implementation of ExecutionCondition.
    null A return value of null is considered to be an error and will result in a ScriptEvaluationException.
    * The value of any other return type will be converted to its String representation by String.valueOf(Object) and then interpreted as a boolean by passing the String representation to Boolean.parseBoolean(String).

    If a test class is disabled via the evaluation of @DisabledIf, all test methods within that class are automatically disabled as well.

    If a test method is disabled via this annotation, that does not prevent the test class from being instantiated. Rather, it prevents the execution of the test method and method-level lifecycle callbacks such as @BeforeEach methods, @AfterEach methods, and corresponding extension APIs.

    Script Engines

    The default script engine is Oracle Nashorn; however, the engine() attribute may be used to override the default script engine name.

    Bindings

    An accessor provides access to a map-like structure via a simple String get(String name) method. The following property accessors are automatically available within scripts.

    • systemEnvironment: Operating system environment variable accessor
    • systemProperty: JVM system property accessor

    The following bindings are available for accessing information from the JUnit Jupiter ExtensionContext.

    • junitTags: All tags as a Set<String>
    • junitDisplayName: Display name as a String
    • junitUniqueId: Unique ID as a String
    • junitConfigurationParameter: Configuration parameter accessor

    Scripts must not declare variables using names that start with junit, since they might clash with bindings provided by JUnit.

    This annotation may be used as a meta-annotation in order to create a custom composed annotation that inherits the semantics of this annotation.

    Warning

    As of JUnit Jupiter 5.1, this annotation can only be declared once on an AnnotatedElement (i.e., test interface, test class, or test method). If this annotation is directly present, indirectly present, or meta-present multiple times on a given element, only the first such annotation discovered by JUnit will be used; any additional declarations will be silently ignored. Note, however, that this annotation may be used in conjunction with other @Enabled* or @Disabled* annotations in this package.

    Since:
    5.1
    See Also:
    EnabledIf, EnabledIfEnvironmentVariable, DisabledIfEnvironmentVariable, EnabledIfSystemProperty, DisabledIfSystemProperty, EnabledOnJre, DisabledOnJre, EnabledOnOs, DisabledOnOs, Disabled, ExecutionCondition, ScriptEngine

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      String[] value
      The lines of the script to evaluate.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      String engine
      Short name of the ScriptEngine to use.
      String reason
      The reason this annotated test class or test method is enabled or disabled.

    • Element Detail

      • value

        String[] value
        The lines of the script to evaluate.

      • reason

        String reason
        The reason this annotated test class or test method is enabled or disabled.

        Defaults to: "Script `{script}` evaluated to: {result}".

        Supported placeholders
        • {annotation}: the String representation of the @DisabledIf annotation instance
        • {script}: the script text that was evaluated
        • {result}: the String representation of the return value of the evaluated script
        Returns:
        the reason the element is enabled or disabled
        See Also:
        ConditionEvaluationResult.getReason()
        Default:
        "Script `{source}` evaluated to: {result}"

      • engine

        String engine
        Short name of the ScriptEngine to use.

        Oracle Nashorn is used by default, providing support for evaluating JavaScript scripts.

        Until Java SE 7, JDKs shipped with a JavaScript scripting engine based on Mozilla Rhino. Java SE 8 instead ships with the new engine called Oracle Nashorn, which is based on JSR 292 and invokedynamic.

        Returns:
        script engine name
        See Also:
        ScriptEngineManager.getEngineByName(String), Oracle Nashorn
        Default:
        "Nashorn"