Package org.junit.jupiter.api

Annotation Type EnabledIf

@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Documented
@API(status=EXPERIMENTAL,
     since="5.1")
public @interface EnabledIf

@EnabledIf is used to control whether the annotated test class or test method is enabled or 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 enabled if the value is true.
java.lang.Boolean	The annotated element will be enabled 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.
*	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 @EnabledIf, all test methods within that class are automatically disabled as well.

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. They might clash with new bindings introduced in the future.

Since:

5.1

See Also:

Disabled, ScriptEngine, ExecutionCondition, ConditionEvaluationResult.enabled(String), ConditionEvaluationResult.disabled(String)

Required Element Summary

Required Elements

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

Optional Element Summary

Optional Elements

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

Element Detail

value

java.lang.String[] value

The lines of the script to evaluate.

reason

java.lang.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 @EnabledIf 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 `{script}` evaluated to: {result}"

engine

java.lang.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"