Skip to content

Commit

Permalink
Document predefined @disabled*/@enabled* in User Guide
Browse files Browse the repository at this point in the history 
Issue: #219
  • Loading branch information
@sbrannen
sbrannen committed Feb 3, 2018
1 parent 5a16675 commit 65c8640
Show file tree
Hide file tree
Showing 4 changed files with 199 additions and 12 deletions.
8 changes: 8 additions & 0 deletions documentation/src/docs/asciidoc/link-attributes.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,15 @@
:BeforeTestExecutionCallback: {javadoc-root}/org/junit/jupiter/api/extension/BeforeTestExecutionCallback.html[BeforeTestExecutionCallback]
:Disabled: {javadoc-root}/org/junit/jupiter/api/Disabled.html[@Disabled]
:DisabledIf: {javadoc-root}/org/junit/jupiter/api/DisabledIf.html[@DisabledIf]
:DisabledIfEnvironmentVariable: {javadoc-root}/org/junit/jupiter/api/condition/DisabledIfEnvironmentVariable.html[@DisabledIfEnvironmentVariable]
:DisabledIfSystemProperty: {javadoc-root}/org/junit/jupiter/api/condition/DisabledIfSystemProperty.html[@DisabledIfSystemProperty]
:DisabledOnJre: {javadoc-root}/org/junit/jupiter/api/condition/DisabledOnJre.html[@DisabledOnJre]
:DisabledOnOs: {javadoc-root}/org/junit/jupiter/api/condition/DisabledOnOs.html[@DisabledOnOs]
:EnabledIf: {javadoc-root}/org/junit/jupiter/api/EnabledIf.html[@EnabledIf]
:EnabledIfEnvironmentVariable: {javadoc-root}/org/junit/jupiter/api/condition/EnabledIfEnvironmentVariable.html[@EnabledIfEnvironmentVariable]
:EnabledIfSystemProperty: {javadoc-root}/org/junit/jupiter/api/condition/EnabledIfSystemProperty.html[@EnabledIfSystemProperty]
:EnabledOnJre: {javadoc-root}/org/junit/jupiter/api/condition/EnabledOnJre.html[@EnabledOnJre]
:EnabledOnOs: {javadoc-root}/org/junit/jupiter/api/condition/EnabledOnOs.html[@EnabledOnOs]
:ExecutionCondition: {javadoc-root}/org/junit/jupiter/api/extension/ExecutionCondition.html[ExecutionCondition]
:ExtendWith: {javadoc-root}/org/junit/jupiter/api/extension/ExtendWith.html[@ExtendWith]
:ExtensionContext_Store: {javadoc-root}/org/junit/jupiter/api/extension/ExtensionContext.Store.html[Store]
Expand Down
13 changes: 11 additions & 2 deletions documentation/src/docs/asciidoc/release-notes/release-notes-5.1.0-RC1.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,19 @@ on GitHub.
`@ParameterizedTest` method will be used as the factory method by convention.
** See <<../user-guide/index.adoc#writing-tests-parameterized-tests-sources-MethodSource,
@MethodSource>> in the User Guide for details.
* New predefined `@Enabled*` and `@Disabled*` annotations for declarative _conditional
test execution_. See the following sections of the User Guide for details.
** <<../user-guide/index.adoc#writing-tests-conditional-execution-os, Operating Systems>>
** <<../user-guide/index.adoc#writing-tests-conditional-execution-jre, Java Runtime
Environment Versions>>
** <<../user-guide/index.adoc#writing-tests-conditional-execution-system-properties,
System Properties>>
** <<../user-guide/index.adoc#writing-tests-conditional-execution-environment-variables,
Environment Variables>>
* New `@DisabledIf` annotation that is used to control whether the annotated test class or
test method is _enabled_ or _disabled_. It inverts the logic applied by `@EnabledIf`.
** See <<../user-guide/index.adoc#writing-tests-conditional-execution-scripts, Conditional
Test Execution via Scripts>> in the User Guide for details.
** See <<../user-guide/index.adoc#writing-tests-conditional-execution-scripts,
Script-based Conditions>> in the User Guide for details.


[[release-notes-5.1.0-RC1-junit-vintage]]
Expand Down
92 changes: 82 additions & 10 deletions documentation/src/docs/asciidoc/user-guide/writing-tests.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -150,34 +150,100 @@ include::{testDir}/example/AssumptionsDemo.java[tags=user_guide]
[[writing-tests-disabling]]
=== Disabling Tests

Here's a disabled test case.
Entire test classes or individual test methods may be _disabled_ via the `{Disabled}`
annotation, via one of the annotations discussed in
<<writing-tests-conditional-execution>>, or via a custom <<extensions-conditions,
`ExecutionCondition`>>.

Here's a `@Disabled` test class.

[source,java,indent=0]
----
include::{testDir}/example/DisabledClassDemo.java[tags=user_guide]
----

And here's a test case with a disabled test method.
And here's a test class that contains a `@Disabled` test method.

[source,java,indent=0]
----
include::{testDir}/example/DisabledTestsDemo.java[tags=user_guide]
----

[[writing-tests-conditional-execution]]
=== Conditional Test Execution via Annotations
=== Conditional Test Execution

The <<extensions-conditions, ExecutionCondition>> extension API in JUnit Jupiter allows
The <<extensions-conditions, `ExecutionCondition`>> extension API in JUnit Jupiter allows
developers to either _enable_ or _disable_ a container or test based on certain
conditions. The simplest example of such a condition is the built-in `DisabledCondition`
which supports the `{Disabled}` annotation. In addition to `@Disabled`, JUnit Jupiter
also supports several annotation-based conditions in the
`org.junit.jupiter.api.condition` package. See the following sections for details.
conditions _programmatically_. The simplest example of such a condition is the built-in
`{DisabledCondition}` which supports the `{Disabled}` annotation (see
<<writing-tests-disabling>>). In addition to `@Disabled`, JUnit Jupiter also supports
several other annotation-based conditions in the `org.junit.jupiter.api.condition`
package that allow developers to enable or disable containers and tests _declaratively_.
See the following sections for details.

[TIP]
.Composed Annotations
====
Note that any of the _conditional_ annotations listed in the following sections may also
be used as a meta-annotation in order to create a custom _composed annotation_. For
example, the `@TestOnMac` annotation in the
<<writing-tests-conditional-execution-os-demo, @EnabledOnOs demo>> shows how you can
combine `@Test` and `@EnabledOnOs` in a single, reusable annotation.
====

[[writing-tests-conditional-execution-os]]
==== Operating System Conditions

A container or test may be enabled or disabled on a particular operating system via the
`{EnabledOnOs}` and `{DisabledOnOs}` annotations.

[[writing-tests-conditional-execution-os-demo]]
[source,java,indent=0]
----
include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_os]
----

[[writing-tests-conditional-execution-jre]]
==== Java Runtime Environment Conditions

A container or test may be enabled or disabled on a particular version of the Java
Runtime Environment (JRE) via the `{EnabledOnJre}` and `{DisabledOnJre}` annotations.

[source,java,indent=0]
----
include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_jre]
----

[[writing-tests-conditional-execution-system-properties]]
==== System Property Conditions

A container or test may be enabled or disabled based on the value of the `named` JVM
system property via the `{EnabledIfSystemProperty}` and `{DisabledIfSystemProperty}`
annotations. The value supplied via the `matches` attribute will be interpreted as a
regular expression.

[source,java,indent=0]
----
include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_system_property]
----

[[writing-tests-conditional-execution-environment-variables]]
==== Environment Variable Conditions

A container or test may be enabled or disabled based on the value of the `named`
environment variable from the underlying operating system via the
`{EnabledIfEnvironmentVariable}` and `{DisabledIfEnvironmentVariable}` annotations. The
value supplied via the `matches` attribute will be interpreted as a regular expression.

[source,java,indent=0]
----
include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_environment_variable]
----

[[writing-tests-conditional-execution-scripts]]
==== Conditional Test Execution via Scripts
==== Script-based Conditions

JUnit Jupiter comes with the ability to either _enable_ or _disable_ a container or test
JUnit Jupiter provides the ability to either _enable_ or _disable_ a container or test
depending on the evaluation of a script configured via the `{EnabledIf}` or
`{DisabledIf}` annotation. Scripts can be written in JavaScript, Groovy, or any other
scripting language for which there is support for the Java Scripting API, defined by JSR
Expand All @@ -187,6 +253,12 @@ WARNING: Conditional test execution via `{EnabledIf}` and `{DisabledIf}` is curr
_experimental_ feature. Consult the table in <<api-evolution-experimental-apis>> for
details.

TIP: If the logic of your script depends only on the current operating system, the
current Java Runtime Environment version, a particular JVM system property, or a
particular environment variable, you should consider using one of the built-in
annotations dedicated to that purpose. See the previous sections of this chapter for
further details.

NOTE: If you find yourself using the same script-based condition many times, consider
writing a dedicated <<extensions-conditions, ExecutionCondition>> extension in order to
implement the condition in a faster, type-safe, and more maintainable manner.
Expand Down
98 changes: 98 additions & 0 deletions documentation/src/test/java/example/ConditionalTestExecutionDemo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,16 +12,114 @@

import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.condition.JRE.JAVA_10;
import static org.junit.jupiter.api.condition.JRE.JAVA_8;
import static org.junit.jupiter.api.condition.JRE.JAVA_9;
import static org.junit.jupiter.api.condition.OS.LINUX;
import static org.junit.jupiter.api.condition.OS.MAC;
import static org.junit.jupiter.api.condition.OS.WINDOWS;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.time.LocalDate;

import org.junit.jupiter.api.DisabledIf;
import org.junit.jupiter.api.EnabledIf;
import org.junit.jupiter.api.RepeatedTest;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.DisabledIfEnvironmentVariable;
import org.junit.jupiter.api.condition.DisabledIfSystemProperty;
import org.junit.jupiter.api.condition.DisabledOnJre;
import org.junit.jupiter.api.condition.DisabledOnOs;
import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import org.junit.jupiter.api.condition.EnabledOnJre;
import org.junit.jupiter.api.condition.EnabledOnOs;

class ConditionalTestExecutionDemo {

// tag::user_guide_os[]
@Test
@EnabledOnOs(MAC)
void onlyOnMacOs() {
// ...
}

@TestOnMac
void testOnMac() {
// ...
}

@Test
@EnabledOnOs({ LINUX, MAC })
void onLinuxOrMac() {
// ...
}

@Test
@DisabledOnOs(WINDOWS)
void notOnWindows() {
// ...
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Test
@EnabledOnOs(MAC)
@interface TestOnMac {
}
// end::user_guide_os[]

// tag::user_guide_jre[]
@Test
@EnabledOnJre(JAVA_8)
void onlyOnJava8() {
// ...
}

@Test
@EnabledOnJre({ JAVA_9, JAVA_10 })
void onJava9Or10() {
// ...
}

@Test
@DisabledOnJre(JAVA_9)
void notOnJava9() {
// ...
}
// end::user_guide_jre[]

// tag::user_guide_system_property[]
@Test
@EnabledIfSystemProperty(named = "os.arch", matches = ".*64.*")
void onlyOn64BitArchitectures() {
// ...
}

@Test
@DisabledIfSystemProperty(named = "ci-server", matches = "true")
void notOnCiServer() {
// ...
}
// end::user_guide_system_property[]

// tag::user_guide_environment_variable[]
@Test
@EnabledIfEnvironmentVariable(named = "ENV", matches = "staging-server")
void onlyOnStagingServer() {
// ...
}

@Test
@DisabledIfEnvironmentVariable(named = "ENV", matches = ".*development.*")
void notOnDeveloperWorkstation() {
// ...
}
// end::user_guide_environment_variable[]

// tag::user_guide_scripts[]
@Test // Static JavaScript expression.
@EnabledIf("2 * 3 == 6")
Expand Down

0 comments on commit 65c8640

Please sign in to comment.