The following example provides a glimpse at the minimum requirements for writing a test in JUnit Jupiter. Subsequent sections of this chapter will provide further details on all available features.
link:{testDir}/example/MyFirstJUnitJupiterTests.java[role=include]
JUnit Jupiter supports the following annotations for configuring tests and extending the framework.
Unless otherwise stated, all core annotations are located in the {api-package}
package
in the junit-jupiter-api
module.
Annotation | Description |
---|---|
|
Denotes that a method is a test method. Unlike JUnit 4’s |
|
Denotes that a method is a parameterized test. Such methods are inherited unless they are overridden. |
|
Denotes that a method is a test template for a repeated test. Such methods are inherited unless they are overridden. |
|
Denotes that a method is a test factory for dynamic tests. Such methods are inherited unless they are overridden. |
|
Denotes that a method is a template for test cases designed to be invoked multiple times depending on the number of invocation contexts returned by the registered providers. Such methods are inherited unless they are overridden. |
|
Used to configure the test class execution order for |
|
Used to configure the test method execution order for the annotated test class; similar to JUnit 4’s |
|
Used to configure the test instance lifecycle for the annotated test class. Such annotations are inherited. |
|
Declares a custom display name for the test class or test method. Such annotations are not inherited. |
|
Declares a custom display name generator for the test class. Such annotations are inherited. |
|
Denotes that the annotated method should be executed before each |
|
Denotes that the annotated method should be executed after each |
|
Denotes that the annotated method should be executed before all |
|
Denotes that the annotated method should be executed after all |
|
Denotes that the annotated class is a non-static nested test class. On Java 8 through Java 15, |
|
Used to declare tags for filtering tests, either at the class or method level; analogous to test groups in TestNG or Categories in JUnit 4. Such annotations are inherited at the class level but not at the method level. |
|
Used to disable a test class or test method; analogous to JUnit 4’s |
|
Denotes that the annotated field represents a resource that will be automatically closed after test execution. |
|
Used to fail a test, test factory, test template, or lifecycle method if its execution exceeds a given duration. Such annotations are inherited. |
|
Used to supply a temporary directory via field injection or parameter injection in a lifecycle method or test method; located in the |
|
Used to register extensions declaratively. Such annotations are inherited. |
|
Used to register extensions programmatically via fields. Such fields are inherited. |
Warning
|
Some annotations may currently be experimental. Consult the table in [api-evolution-experimental-apis] for details. |
JUnit Jupiter annotations can be used as meta-annotations. That means that you can define your own composed annotation that will automatically inherit the semantics of its meta-annotations.
For example, instead of copying and pasting @Tag("fast")
throughout your code base (see
Tagging and Filtering), you can create a custom composed annotation
named @Fast
as follows. @Fast
can then be used as a drop-in replacement for
@Tag("fast")
.
link:{testDir}/example/Fast.java[role=include]
The following @Test
method demonstrates usage of the @Fast
annotation.
@Fast
@Test
void myFastTest() {
// ...
}
You can even take that one step further by introducing a custom @FastTest
annotation
that can be used as a drop-in replacement for @Tag("fast")
and @Test
.
link:{testDir}/example/FastTest.java[role=include]
JUnit automatically recognizes the following as a @Test
method that is tagged with
"fast".
@FastTest
void myFastTest() {
// ...
}
- Container
-
a node in the test tree that contains other containers or tests as its children (e.g. a test class).
- Test
-
a node in the test tree that verifies expected behavior when executed (e.g. a
@Test
method).
- Lifecycle Method
-
any method that is directly annotated or meta-annotated with
@BeforeAll
,@AfterAll
,@BeforeEach
, or@AfterEach
. - Test Class
-
any top-level class,
static
member class, or@Nested
class that contains at least one test method, i.e. a container. Test classes must not beabstract
and must have a single constructor. - Test Method
-
any instance method that is directly annotated or meta-annotated with
@Test
,@RepeatedTest
,@ParameterizedTest
,@TestFactory
, or@TestTemplate
. With the exception of@Test
, these create a container in the test tree that groups tests or, potentially (for@TestFactory
), other containers.
Test methods and lifecycle methods may be declared locally within the current test class,
inherited from superclasses, or inherited from interfaces (see
Test Interfaces and Default Methods). In addition, test methods and
lifecycle methods must not be abstract
and must not return a value (except @TestFactory
methods which are required to return a value).
Note
|
Class and method visibility
Test classes, test methods, and lifecycle methods are not required to be It is generally recommended to omit the |
Note
|
Field and method inheritance
Fields in test classes are inherited. For example, a Test methods and lifecycle methods are inherited unless they are overridden according to
the visibility rules of the Java language. For example, a |
The following test class demonstrates the use of @Test
methods and all supported
lifecycle methods. For further information on runtime semantics, see
Test Execution Order and
[extensions-execution-order-wrapping-behavior].
link:{testDir}/example/StandardTests.java[role=include]
Test classes and test methods can declare custom display names via @DisplayName
— with
spaces, special characters, and even emojis — that will be displayed in test reports and
by test runners and IDEs.
link:{testDir}/example/DisplayNameDemo.java[role=include]
JUnit Jupiter supports custom display name generators that can be configured via the
@DisplayNameGeneration
annotation. Values provided via @DisplayName
annotations
always take precedence over display names generated by a DisplayNameGenerator
.
Generators can be created by implementing DisplayNameGenerator
. Here are some default
ones available in Jupiter:
DisplayNameGenerator | Behavior |
---|---|
|
Matches the standard display name generation behavior in place since JUnit Jupiter 5.0 was released. |
|
Removes trailing parentheses for methods with no parameters. |
|
Replaces underscores with spaces. |
|
Generates complete sentences by concatenating the names of the test and the enclosing classes. |
Note that for IndicativeSentences
, you can customize the separator and the
underlying generator by using @IndicativeSentencesGeneration
as shown in the
following example.
link:{testDir}/example/DisplayNameGeneratorDemo.java[role=include]
+-- DisplayNameGeneratorDemo [OK]
+-- A year is not supported [OK]
| +-- A negative value for year is not supported by the leap year computation. [OK]
| | +-- For example, year -1 is not supported. [OK]
| | '-- For example, year -4 is not supported. [OK]
| '-- if it is zero() [OK]
'-- A year is a leap year [OK]
+-- A year is a leap year -> if it is divisible by 4 but not by 100. [OK]
'-- A year is a leap year -> if it is one of the following years. [OK]
+-- Year 2016 is a leap year. [OK]
+-- Year 2020 is a leap year. [OK]
'-- Year 2048 is a leap year. [OK]
You can use the junit.jupiter.displayname.generator.default
configuration parameter to specify the fully qualified
class name of the DisplayNameGenerator
you would like to use by default. Just like for
display name generators configured via the @DisplayNameGeneration
annotation, the
supplied class has to implement the DisplayNameGenerator
interface. The default display
name generator will be used for all tests unless the @DisplayNameGeneration
annotation
is present on an enclosing test class or test interface. Values provided via
@DisplayName
annotations always take precedence over display names generated by a
DisplayNameGenerator
.
For example, to use the ReplaceUnderscores
display name generator by default, you should
set the configuration parameter to the corresponding fully qualified class name (e.g., in
src/test/resources/junit-platform.properties
):
junit.jupiter.displayname.generator.default = \
org.junit.jupiter.api.DisplayNameGenerator$ReplaceUnderscores
Similarly, you can specify the fully qualified name of any custom class that implements
DisplayNameGenerator
.
In summary, the display name for a test class or method is determined according to the following precedence rules:
-
value of the
@DisplayName
annotation, if present -
by calling the
DisplayNameGenerator
specified in the@DisplayNameGeneration
annotation, if present -
by calling the default
DisplayNameGenerator
configured via the configuration parameter, if present -
by calling
org.junit.jupiter.api.DisplayNameGenerator.Standard
JUnit Jupiter comes with many of the assertion methods that JUnit 4 has and adds a few
that lend themselves well to being used with Java 8 lambdas. All JUnit Jupiter assertions
are static
methods in the {Assertions}
class.
link:{testDir}/example/AssertionsDemo.java[role=include]
Warning
|
Preemptive Timeouts with
assertTimeoutPreemptively() The various One common example of this is the transactional testing support in the Spring Framework.
Specifically, Spring’s testing support binds transaction state to the current thread (via
a Similar side effects may be encountered with other frameworks that rely on
|
JUnit Jupiter also comes with a few assertion methods that lend themselves well to being
used in Kotlin. All JUnit Jupiter Kotlin assertions are top-level
functions in the org.junit.jupiter.api
package.
link:{kotlinTestDir}/example/KotlinAssertionsDemo.kt[role=include]
Even though the assertion facilities provided by JUnit Jupiter are sufficient for many testing scenarios, there are times when more power and additional functionality such as matchers are desired or required. In such cases, the JUnit team recommends the use of third-party assertion libraries such as {AssertJ}, {Hamcrest}, {Truth}, etc. Developers are therefore free to use the assertion library of their choice.
For example, the combination of matchers and a fluent API can be used to make
assertions more descriptive and readable. However, JUnit Jupiter’s {Assertions}
class
does not provide an
assertThat()
method like the one found in JUnit 4’s org.junit.Assert
class which accepts a Hamcrest
Matcher
. Instead,
developers are encouraged to use the built-in support for matchers provided by third-party
assertion libraries.
The following example demonstrates how to use the assertThat()
support from Hamcrest in
a JUnit Jupiter test. As long as the Hamcrest library has been added to the classpath,
you can statically import methods such as assertThat()
, is()
, and equalTo()
and
then use them in tests like in the assertWithHamcrestMatcher()
method below.
link:{testDir}/example/HamcrestAssertionsDemo.java[role=include]
Naturally, legacy tests based on the JUnit 4 programming model can continue using
org.junit.Assert#assertThat
.
Assumptions are typically used whenever it does not make sense to continue execution of a given test — for example, if the test depends on something that does not exist in the current runtime environment.
-
When an assumption is valid, the assumption method does not throw an exception, and execution of the test continues as usual.
-
When an assumption is invalid, the assumption method throws an exception of type
org.opentest4j.TestAbortedException
to signal that the test should be aborted instead of marked as a failure.
JUnit Jupiter comes with a subset of the assumption methods that JUnit 4 provides and adds a few that lend themselves well to being used with Java 8 lambda expressions and method references.
All JUnit Jupiter assumptions are static methods in the {Assumptions}
class.
link:{testDir}/example/AssumptionsDemo.java[role=include]
Note
|
It is also possible to use methods from JUnit 4’s org.junit.Assume class for
assumptions. Specifically, JUnit Jupiter supports JUnit 4’s AssumptionViolatedException
to signal that a test should be aborted instead of marked as a failure.
|
JUnit Jupiter provides robust support for handling test exceptions. This includes the built-in mechanisms for managing test failures due to exceptions, the role of exceptions in implementing assertions and assumptions, and how to specifically assert non-throwing conditions in code.
In JUnit Jupiter, if an exception is thrown from a test method, a lifecycle method, or an extension and not caught within that test method, lifecycle method, or extension, the framework will mark the test or test class as failed.
Tip
|
Failed assumptions deviate from this general rule. In contrast to failed assertions, failed assumptions do not result in a test failure; rather, a failed assumption results in a test being aborted. See Assumptions for further details and examples. |
In the following example, the failsDueToUncaughtException()
method throws an
ArithmeticException
. Since the exception is not caught within the test method, JUnit
Jupiter will mark the test as failed.
link:{testDir}/example/exception/UncaughtExceptionHandlingDemo.java[role=include]
Note
|
It’s important to note that specifying a throws clause in the test method has
no effect on the outcome of the test. JUnit Jupiter does not interpret a throws clause
as an expectation or assertion about what exceptions the test method should throw. A test
fails only if an exception is thrown unexpectedly or if an assertion fails.
|
Assertions in JUnit Jupiter are implemented using exceptions. The framework provides a set
of assertion methods in the org.junit.jupiter.api.Assertions
class, which throw
AssertionError
when an assertion fails. This mechanism is a core aspect of how JUnit
handles assertion failures as exceptions. See the Assertions section for
further information about JUnit Jupiter’s assertion support.
Note
|
Third-party assertion libraries may choose to throw an AssertionError to signal a
failed assertion; however, they may also choose to throw different types of exceptions to
signal failures. See also: Third-party Assertion Libraries.
|
Tip
|
JUnit Jupiter itself does not differentiate between failed assertions
(AssertionError ) and other types of exceptions. All uncaught exceptions lead to a test
failure. However, Integrated Development Environments (IDEs) and other tools may
distinguish between these two types of failures by checking whether the thrown exception
is an instance of AssertionError .
|
In the following example, the failsDueToUncaughtAssertionError()
method throws an
AssertionError
. Since the exception is not caught within the test method, JUnit Jupiter
will mark the test as failed.
link:{testDir}/example/exception/FailedAssertionDemo.java[role=include]
JUnit Jupiter offers specialized assertions for testing that specific exceptions are
thrown under expected conditions. The assertThrows()
and assertThrowsExactly()
assertions are critical tools for validating that your code responds correctly to error
conditions by throwing the appropriate exceptions.
The assertThrows()
method is used to verify that a particular type of exception is
thrown during the execution of a provided executable block. It not only checks for the
type of the thrown exception but also its subclasses, making it suitable for more
generalized exception handling tests. The assertThrows()
assertion method returns the
thrown exception object to allow performing additional assertions on it.
link:{testDir}/example/exception/ExceptionAssertionDemo.java[role=include]
The assertThrowsExactly()
method is used when you need to assert that the exception
thrown is exactly of a specific type, not allowing for subclasses of the expected
exception type. This is useful when precise exception handling behavior needs to be
validated. Similar to assertThrows()
, the assertThrowsExactly()
assertion method also
returns the thrown exception object to allow performing additional assertions on it.
link:{testDir}/example/exception/ExceptionAssertionExactDemo.java[role=include]
Although any exception thrown from a test method will cause the test to fail, there are
certain use cases where it can be beneficial to explicitly assert that an exception is
not thrown for a given code block within a test method. The assertDoesNotThrow()
assertion can be used when you want to verify that a particular piece of code does not
throw any exceptions.
link:{testDir}/example/exception/AssertDoesNotThrowExceptionDemo.java[role=include]
Note
|
Third-party assertion libraries often provide similar support. For example, AssertJ
has assertThatNoException().isThrownBy(() → …) . See also:
Third-party Assertion Libraries.
|
Entire test classes or individual test methods may be disabled via the {Disabled}
annotation, via one of the annotations discussed in
Conditional Test Execution, or via a custom ExecutionCondition
.
When @Disabled
is applied at the class level, all test methods within that class are
automatically disabled as well.
If a test method is disabled via @Disabled
, that prevents execution of the test method
and method-level lifecycle callbacks such as @BeforeEach
methods, @AfterEach
methods,
and corresponding extension APIs. However, that does not prevent the test class from being
instantiated, and it does not prevent the execution of class-level lifecycle callbacks
such as @BeforeAll
methods, @AfterAll
methods, and corresponding extension APIs.
Here’s a @Disabled
test class.
link:{testDir}/example/DisabledClassDemo.java[role=include]
And here’s a test class that contains a @Disabled
test method.
link:{testDir}/example/DisabledTestsDemo.java[role=include]
Tip
|
|
Note
|
|
The ExecutionCondition
extension API in JUnit Jupiter allows
developers to either enable or disable a test class or test method based on certain
conditions programmatically. The simplest example of such a condition is the built-in
{DisabledCondition}
which supports the {Disabled}
annotation (see
Disabling Tests).
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 test classes and test methods declaratively. If you wish to provide
details about why they might be disabled, every annotation associated with these built-in
conditions has a disabledReason
attribute available for that purpose.
When multiple ExecutionCondition
extensions are registered, a test class or test method
is disabled as soon as one of the conditions returns disabled. If a test class is
disabled, all test methods within that class are automatically disabled as well. If a test
method is disabled, that prevents execution of the test method and method-level lifecycle
callbacks such as @BeforeEach
methods, @AfterEach
methods, and corresponding extension
APIs. However, that does not prevent the test class from being instantiated, and it does
not prevent the execution of class-level lifecycle callbacks such as @BeforeAll
methods,
@AfterAll
methods, and corresponding extension APIs.
See ExecutionCondition
and 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 |
Note
|
Conditional annotations in JUnit Jupiter are not |
Warning
|
Unless otherwise stated, each of the conditional annotations listed in the following
sections can only be declared once on a given test interface, test class, or test method.
If a conditional 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 each
conditional annotation may be used in conjunction with other conditional annotations in
the |
A container or test may be enabled or disabled on a particular operating system,
architecture, or combination of both via the {EnabledOnOs}
and {DisabledOnOs}
annotations.
link:{testDir}/example/ConditionalTestExecutionDemo.java[role=include]
link:{testDir}/example/ConditionalTestExecutionDemo.java[role=include]
A container or test may be enabled or disabled on particular versions of the Java
Runtime Environment (JRE) via the {EnabledOnJre}
and {DisabledOnJre}
annotations
or on a particular range of versions of the JRE via the {EnabledForJreRange}
and
{DisabledForJreRange}
annotations. The range defaults to {JRE}.JAVA_8
as the lower
border (min
) and {JRE}.OTHER
as the higher border (max
), which allows usage of
half open ranges.
link:{testDir}/example/ConditionalTestExecutionDemo.java[role=include]
A container or test may be enabled or disabled within a
GraalVM native image via the
{EnabledInNativeImage}
and {DisabledInNativeImage}
annotations. These annotations are
typically used when running tests within a native image using the Gradle and Maven
plug-ins from the GraalVM Native
Build Tools project.
link:{testDir}/example/ConditionalTestExecutionDemo.java[role=include]
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.
link:{testDir}/example/ConditionalTestExecutionDemo.java[role=include]
Tip
|
As of JUnit Jupiter 5.6, |
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.
link:{testDir}/example/ConditionalTestExecutionDemo.java[role=include]
Tip
|
As of JUnit Jupiter 5.6, |
As an alternative to implementing an ExecutionCondition
, a
container or test may be enabled or disabled based on a condition method configured via
the {EnabledIf}
and {DisabledIf}
annotations. A condition method must have a boolean
return type and may accept either no arguments or a single ExtensionContext
argument.
The following test class demonstrates how to configure a local method named
customCondition
via @EnabledIf
and @DisabledIf
.
link:{testDir}/example/ConditionalTestExecutionDemo.java[role=include]
Alternatively, the condition method can be located outside the test class. In this case, it must be referenced by its fully qualified name as demonstrated in the following example.
package example;
link:{testDir}/example/ExternalCustomConditionDemo.java[role=include]
Note
|
There are several cases where a condition method would need to be
In any other case, you can use either static methods or instance methods as condition methods. |
Tip
|
It is often the case that you can use an existing static method in a utility class as a custom condition. For example, @DisabledIf(value = "java.awt.GraphicsEnvironment#isHeadless",
disabledReason = "headless environment") |
Test classes and methods can be tagged via the @Tag
annotation. Those tags can later be
used to filter test discovery and execution. Please refer to the
[running-tests-tags] section for more information about tag support in the JUnit
Platform.
link:{testDir}/example/TaggingDemo.java[role=include]
Tip
|
See Meta-Annotations and Composed Annotations for examples demonstrating how to create custom annotations for tags. |
By default, test classes and methods will be ordered using an algorithm that is deterministic but intentionally nonobvious. This ensures that subsequent runs of a test suite execute test classes and test methods in the same order, thereby allowing for repeatable builds.
Note
|
See Definitions for a definition of test method and test class. |
Although true unit tests typically should not rely on the order in which they are
executed, there are times when it is necessary to enforce a specific test method execution
order — for example, when writing integration tests or functional tests where the
sequence of the tests is important, especially in conjunction with
@TestInstance(Lifecycle.PER_CLASS)
.
To control the order in which test methods are executed, annotate your test class or test
interface with {TestMethodOrder}
and specify the desired {MethodOrderer}
implementation. You can implement your own custom MethodOrderer
or use one of the
following built-in MethodOrderer
implementations.
-
{MethodOrderer_DisplayName}
: sorts test methods alphanumerically based on their display names (see display name generation precedence rules) -
{MethodOrderer_MethodName}
: sorts test methods alphanumerically based on their names and formal parameter lists -
{MethodOrderer_OrderAnnotation}
: sorts test methods numerically based on values specified via the{Order}
annotation -
{MethodOrderer_Random}
: orders test methods pseudo-randomly and supports configuration of a custom seed -
{MethodOrderer_Alphanumeric}
: sorts test methods alphanumerically based on their names and formal parameter lists; deprecated in favor of{MethodOrderer_MethodName}
, to be removed in 6.0
Note
|
See also: [extensions-execution-order-wrapping-behavior] |
The following example demonstrates how to guarantee that test methods are executed in the
order specified via the @Order
annotation.
link:{testDir}/example/OrderedTestsDemo.java[role=include]
You can use the junit.jupiter.testmethod.order.default
configuration parameter to specify the fully qualified class name of the
{MethodOrderer}
you would like to use by default. Just like for the orderer configured
via the {TestMethodOrder}
annotation, the supplied class has to implement the
MethodOrderer
interface. The default orderer will be used for all tests unless the
@TestMethodOrder
annotation is present on an enclosing test class or test interface.
For example, to use the {MethodOrderer_OrderAnnotation}
method orderer by default, you
should set the configuration parameter to the corresponding fully qualified class name
(e.g., in src/test/resources/junit-platform.properties
):
junit.jupiter.testmethod.order.default = \
org.junit.jupiter.api.MethodOrderer$OrderAnnotation
Similarly, you can specify the fully qualified name of any custom class that implements
MethodOrderer
.
Although test classes typically should not rely on the order in which they are executed, there are times when it is desirable to enforce a specific test class execution order. You may wish to execute test classes in a random order to ensure there are no accidental dependencies between test classes, or you may wish to order test classes to optimize build time as outlined in the following scenarios.
-
Run previously failing tests and faster tests first: "fail fast" mode
-
With parallel execution enabled, schedule longer tests first: "shortest test plan execution duration" mode
-
Various other use cases
To configure test class execution order globally for the entire test suite, use the
junit.jupiter.testclass.order.default
configuration
parameter to specify the fully qualified class name of the {ClassOrderer}
you would
like to use. The supplied class must implement the ClassOrderer
interface.
You can implement your own custom ClassOrderer
or use one of the following built-in
ClassOrderer
implementations.
-
{ClassOrderer_ClassName}
: sorts test classes alphanumerically based on their fully qualified class names -
{ClassOrderer_DisplayName}
: sorts test classes alphanumerically based on their display names (see display name generation precedence rules) -
{ClassOrderer_OrderAnnotation}
: sorts test classes numerically based on values specified via the{Order}
annotation -
{ClassOrderer_Random}
: orders test classes pseudo-randomly and supports configuration of a custom seed
For example, for the @Order
annotation to be honored on test classes, you should
configure the {ClassOrderer_OrderAnnotation}
class orderer using the configuration
parameter with the corresponding fully qualified class name (e.g., in
src/test/resources/junit-platform.properties
):
junit.jupiter.testclass.order.default = \
org.junit.jupiter.api.ClassOrderer$OrderAnnotation
The configured ClassOrderer
will be applied to all top-level test classes (including
static
nested test classes) and @Nested
test classes.
Note
|
Top-level test classes will be ordered relative to each other; whereas, @Nested
test classes will be ordered relative to other @Nested test classes sharing the same
enclosing class.
|
To configure test class execution order locally for @Nested
test classes, declare the
{TestClassOrder}
annotation on the enclosing class for the @Nested
test classes you
want to order, and supply a class reference to the ClassOrderer
implementation you would
like to use directly in the @TestClassOrder
annotation. The configured ClassOrderer
will be applied recursively to @Nested
test classes and their @Nested
test classes.
Note that a local @TestClassOrder
declaration always overrides an inherited
@TestClassOrder
declaration or a ClassOrderer
configured globally via the
junit.jupiter.testclass.order.default
configuration parameter.
The following example demonstrates how to guarantee that @Nested
test classes are
executed in the order specified via the @Order
annotation.
link:{testDir}/example/OrderedNestedTestClassesDemo.java[role=include]
In order to allow individual test methods to be executed in isolation and to avoid unexpected side effects due to mutable test instance state, JUnit creates a new instance of each test class before executing each test method (see Definitions). This "per-method" test instance lifecycle is the default behavior in JUnit Jupiter and is analogous to all previous versions of JUnit.
Note
|
Please note that the test class will still be instantiated if a given test method
is disabled via a condition (e.g., @Disabled ,
@DisabledOnOs , etc.) even when the "per-method" test instance lifecycle mode is active.
|
If you would prefer that JUnit Jupiter execute all test methods on the same test
instance, annotate your test class with @TestInstance(Lifecycle.PER_CLASS)
. When using
this mode, a new test instance will be created once per test class. Thus, if your test
methods rely on state stored in instance variables, you may need to reset that state in
@BeforeEach
or @AfterEach
methods.
The "per-class" mode has some additional benefits over the default "per-method" mode.
Specifically, with the "per-class" mode it becomes possible to declare @BeforeAll
and
@AfterAll
on non-static methods as well as on interface default
methods. The
"per-class" mode therefore also makes it possible to use @BeforeAll
and @AfterAll
methods in @Nested
test classes.
Note
|
Beginning with Java 16, @BeforeAll and @AfterAll methods can be declared as
static in @Nested test classes.
|
If you are authoring tests using the Kotlin programming language, you may also find it
easier to implement non-static @BeforeAll
and @AfterAll
lifecycle methods as well as
@MethodSource
factory methods by switching to the "per-class" test instance lifecycle
mode.
If a test class or test interface is not annotated with @TestInstance
, JUnit Jupiter
will use a default lifecycle mode. The standard default mode is PER_METHOD
;
however, it is possible to change the default for the execution of an entire test plan.
To change the default test instance lifecycle mode, set the
junit.jupiter.testinstance.lifecycle.default
configuration parameter to the name of
an enum constant defined in TestInstance.Lifecycle
, ignoring case. This can be supplied
as a JVM system property, as a configuration parameter in the
LauncherDiscoveryRequest
that is passed to the Launcher
, or via the JUnit Platform
configuration file (see [running-tests-config-params] for details).
For example, to set the default test instance lifecycle mode to Lifecycle.PER_CLASS
,
you can start your JVM with the following system property.
-Djunit.jupiter.testinstance.lifecycle.default=per_class
Note, however, that setting the default test instance lifecycle mode via the JUnit Platform configuration file is a more robust solution since the configuration file can be checked into a version control system along with your project and can therefore be used within IDEs and your build software.
To set the default test instance lifecycle mode to Lifecycle.PER_CLASS
via the JUnit
Platform configuration file, create a file named junit-platform.properties
in the root
of the class path (e.g., src/test/resources
) with the following content.
junit.jupiter.testinstance.lifecycle.default = per_class
Warning
|
Changing the default test instance lifecycle mode can lead to unpredictable results and fragile builds if not applied consistently. For example, if the build configures "per-class" semantics as the default but tests in the IDE are executed using "per-method" semantics, that can make it difficult to debug errors that occur on the build server. It is therefore recommended to change the default in the JUnit Platform configuration file instead of via a JVM system property. |
@Nested
tests give the test writer more capabilities to express the relationship among
several groups of tests. Such nested tests make use of Java’s nested classes and
facilitate hierarchical thinking about the test structure. Here’s an elaborate example,
both as source code and as a screenshot of the execution within an IDE.
link:{testDir}/example/TestingAStackDemo.java[role=include]
When executing this example in an IDE, the test execution tree in the GUI will look similar to the following image.
In this example, preconditions from outer tests are used in inner tests by defining
hierarchical lifecycle methods for the setup code. For example, createNewStack()
is a
@BeforeEach
lifecycle method that is used in the test class in which it is defined and
in all levels in the nesting tree below the class in which it is defined.
The fact that setup code from outer tests is run before inner tests are executed gives you the ability to run all tests independently. You can even run inner tests alone without running the outer tests, because the setup code from the outer tests is always executed.
Note
|
Only non-static nested classes (i.e. inner classes) can serve as @Nested test
classes. Nesting can be arbitrarily deep, and those inner classes are subject to full
lifecycle support with one exception: @BeforeAll and @AfterAll methods do not work by
default. The reason is that Java does not allow static members in inner classes prior
to Java 16. However, this restriction can be circumvented by annotating a @Nested test
class with @TestInstance(Lifecycle.PER_CLASS) (see
Test Instance Lifecycle). If you are using Java 16 or higher,
@BeforeAll and @AfterAll methods can be declared as static in @Nested test
classes, and this restriction no longer applies.
|
In all prior JUnit versions, test constructors or methods were not allowed to have
parameters (at least not with the standard Runner
implementations). As one of the major
changes in JUnit Jupiter, both test constructors and methods are now permitted to have
parameters. This allows for greater flexibility and enables Dependency Injection for
constructors and methods.
{ParameterResolver}
defines the API for test extensions that wish to dynamically
resolve parameters at runtime. If a test class constructor, a test method, or a
lifecycle method (see Definitions) accepts a parameter, the parameter
must be resolved at runtime by a registered ParameterResolver
.
There are currently three built-in resolvers that are registered automatically.
-
{TestInfoParameterResolver}
: if a constructor or method parameter is of type{TestInfo}
, theTestInfoParameterResolver
will supply an instance ofTestInfo
corresponding to the current container or test as the value for the parameter. TheTestInfo
can then be used to retrieve information about the current container or test such as the display name, the test class, the test method, and associated tags. The display name is either a technical name, such as the name of the test class or test method, or a custom name configured via@DisplayName
.{TestInfo}
acts as a drop-in replacement for theTestName
rule from JUnit 4. The following demonstrates how to haveTestInfo
injected into a test constructor,@BeforeEach
method, and@Test
method.
link:{testDir}/example/TestInfoDemo.java[role=include]
-
{RepetitionExtension}
: if a method parameter in a@RepeatedTest
,@BeforeEach
, or@AfterEach
method is of type{RepetitionInfo}
, theRepetitionExtension
will supply an instance ofRepetitionInfo
.RepetitionInfo
can then be used to retrieve information about the current repetition, the total number of repetitions, the number of repetitions that have failed, and the failure threshold for the corresponding@RepeatedTest
. Note, however, thatRepetitionExtension
is not registered outside the context of a@RepeatedTest
. See Repeated Test Examples. -
{TestReporterParameterResolver}
: if a constructor or method parameter is of type{TestReporter}
, theTestReporterParameterResolver
will supply an instance ofTestReporter
. TheTestReporter
can be used to publish additional data about the current test run. The data can be consumed via thereportingEntryPublished()
method in a{TestExecutionListener}
, allowing it to be viewed in IDEs or included in reports.In JUnit Jupiter you should use
TestReporter
where you used to print information tostdout
orstderr
in JUnit 4. Using@RunWith(JUnitPlatform.class)
will output all reported entries tostdout
. In addition, some IDEs print report entries tostdout
or display them in the user interface for test results.
link:{testDir}/example/TestReporterDemo.java[role=include]
Note
|
Other parameter resolvers must be explicitly enabled by registering appropriate
extensions via @ExtendWith .
|
Check out the {RandomParametersExtension}
for an example of a custom
{ParameterResolver}
. While not intended to be production-ready, it demonstrates the
simplicity and expressiveness of both the extension model and the parameter resolution
process. MyRandomParametersTest
demonstrates how to inject random values into @Test
methods.
@ExtendWith(RandomParametersExtension.class)
class MyRandomParametersTest {
@Test
void injectsInteger(@Random int i, @Random int j) {
assertNotEquals(i, j);
}
@Test
void injectsDouble(@Random double d) {
assertEquals(0.0, d, 1.0);
}
}
For real-world use cases, check out the source code for the {MockitoExtension}
and the
{SpringExtension}
.
When the type of the parameter to inject is the only condition for your
{ParameterResolver}
, you can use the generic {TypeBasedParameterResolver}
base class.
The supportsParameters
method is implemented behind the scenes and supports
parameterized types.
JUnit Jupiter allows @Test
, @RepeatedTest
, @ParameterizedTest
, @TestFactory
,
@TestTemplate
, @BeforeEach
, and @AfterEach
to be declared on interface default
methods. @BeforeAll
and @AfterAll
can either be declared on static
methods in a
test interface or on interface default
methods if the test interface or test class is
annotated with @TestInstance(Lifecycle.PER_CLASS)
(see
Test Instance Lifecycle). Here are some examples.
link:{testDir}/example/testinterface/TestLifecycleLogger.java[role=include]
link:{testDir}/example/testinterface/TestInterfaceDynamicTestsDemo.java[role=include]
@ExtendWith
and @Tag
can be declared on a test interface so that classes that
implement the interface automatically inherit its tags and extensions. See
[extensions-lifecycle-callbacks-before-after-execution] for the source code of the
TimingExtension.
link:{testDir}/example/testinterface/TimeExecutionLogger.java[role=include]
In your test class you can then implement these test interfaces to have them applied.
link:{testDir}/example/testinterface/TestInterfaceDemo.java[role=include]
Running the TestInterfaceDemo
results in output similar to the following:
INFO example.TestLifecycleLogger - Before all tests INFO example.TestLifecycleLogger - About to execute [dynamicTestsForPalindromes()] INFO example.TimingExtension - Method [dynamicTestsForPalindromes] took 19 ms. INFO example.TestLifecycleLogger - Finished executing [dynamicTestsForPalindromes()] INFO example.TestLifecycleLogger - About to execute [isEqualValue()] INFO example.TimingExtension - Method [isEqualValue] took 1 ms. INFO example.TestLifecycleLogger - Finished executing [isEqualValue()] INFO example.TestLifecycleLogger - After all tests
Another possible application of this feature is to write tests for interface contracts.
For example, you can write tests for how implementations of Object.equals
or
Comparable.compareTo
should behave as follows.
link:{testDir}/example/defaultmethods/Testable.java[role=include]
link:{testDir}/example/defaultmethods/EqualsContract.java[role=include]
link:{testDir}/example/defaultmethods/ComparableContract.java[role=include]
In your test class you can then implement both contract interfaces thereby inheriting the corresponding tests. Of course you’ll have to implement the abstract methods.
link:{testDir}/example/defaultmethods/StringTests.java[role=include]
Note
|
The above tests are merely meant as examples and therefore not complete. |
JUnit Jupiter provides the ability to repeat a test a specified number of times by
annotating a method with @RepeatedTest
and specifying the total number of repetitions
desired. Each invocation of a repeated test behaves like the execution of a regular
@Test
method with full support for the same lifecycle callbacks and extensions.
The following example demonstrates how to declare a test named repeatedTest()
that
will be automatically repeated 10 times.
@RepeatedTest(10)
void repeatedTest() {
// ...
}
Since JUnit Jupiter 5.10, @RepeatedTest
can be configured with a failure threshold which
signifies the number of failures after which remaining repetitions will be automatically
skipped. Set the failureThreshold
attribute to a positive number less than the total
number of repetitions in order to skip the invocations of remaining repetitions after the
specified number of failures has been encountered.
For example, if you are using @RepeatedTest
to repeatedly invoke a test that you suspect
to be flaky, a single failure is sufficient to demonstrate that the test is flaky, and
there is no need to invoke the remaining repetitions. To support that specific use case,
set failureThreshold = 1
. You can alternatively set the threshold to a number greater
than 1 depending on your use case.
By default, the failureThreshold
attribute is set to Integer.MAX_VALUE
, signaling that
no failure threshold will be applied, which effectively means that the specified number of
repetitions will be invoked regardless of whether any repetitions fail.
Warning
|
If the repetitions of a @RepeatedTest method are executed in parallel, no
guarantees can be made regarding the failure threshold. It is therefore recommended that a
@RepeatedTest method be annotated with @Execution(SAME_THREAD) when parallel execution
is configured. See Parallel Execution for further details.
|
In addition to specifying the number of repetitions and failure threshold, a custom
display name can be configured for each repetition via the name
attribute of the
@RepeatedTest
annotation. Furthermore, the display name can be a pattern composed of a
combination of static text and dynamic placeholders. The following placeholders are
currently supported.
-
{displayName}
: display name of the@RepeatedTest
method -
{currentRepetition}
: the current repetition count -
{totalRepetitions}
: the total number of repetitions
The default display name for a given repetition is generated based on the following
pattern: "repetition {currentRepetition} of {totalRepetitions}"
. Thus, the display
names for individual repetitions of the previous repeatedTest()
example would be:
repetition 1 of 10
, repetition 2 of 10
, etc. If you would like the display name of
the @RepeatedTest
method included in the name of each repetition, you can define your
own custom pattern or use the predefined RepeatedTest.LONG_DISPLAY_NAME
pattern. The
latter is equal to "{displayName} :: repetition {currentRepetition} of
{totalRepetitions}"
which results in display names for individual repetitions like
repeatedTest() :: repetition 1 of 10
, repeatedTest() :: repetition 2 of 10
, etc.
In order to retrieve information about the current repetition, the total number of
repetitions, the number of repetitions that have failed, and the failure threshold, a
developer can choose to have an instance of {RepetitionInfo}
injected into a
@RepeatedTest
, @BeforeEach
, or @AfterEach
method.
The RepeatedTestsDemo
class at the end of this section demonstrates several examples of
repeated tests.
The repeatedTest()
method is identical to the example from the previous section; whereas,
repeatedTestWithRepetitionInfo()
demonstrates how to have an instance of
RepetitionInfo
injected into a test to access the total number of repetitions for the
current repeated test.
repeatedTestWithFailureThreshold()
demonstrates how to set a failure threshold and
simulates an unexpected failure for every second repetition. The resulting behavior can be
viewed in the ConsoleLauncher
output at the end of this section.
The next two methods demonstrate how to include a custom @DisplayName
for the
@RepeatedTest
method in the display name of each repetition. customDisplayName()
combines a custom display name with a custom pattern and then uses TestInfo
to verify
the format of the generated display name. Repeat!
is the {displayName}
which comes
from the @DisplayName
declaration, and 1/1
comes from
{currentRepetition}/{totalRepetitions}
. In contrast,
customDisplayNameWithLongPattern()
uses the aforementioned predefined
RepeatedTest.LONG_DISPLAY_NAME
pattern.
repeatedTestInGerman()
demonstrates the ability to translate display names of repeated
tests into foreign languages — in this case German, resulting in names for individual
repetitions such as: Wiederholung 1 von 5
, Wiederholung 2 von 5
, etc.
Since the beforeEach()
method is annotated with @BeforeEach
it will get executed
before each repetition of each repeated test. By having the TestInfo
and
RepetitionInfo
injected into the method, we see that it’s possible to obtain
information about the currently executing repeated test. Executing RepeatedTestsDemo
with the INFO
log level enabled results in the following output.
INFO: About to execute repetition 1 of 10 for repeatedTest INFO: About to execute repetition 2 of 10 for repeatedTest INFO: About to execute repetition 3 of 10 for repeatedTest INFO: About to execute repetition 4 of 10 for repeatedTest INFO: About to execute repetition 5 of 10 for repeatedTest INFO: About to execute repetition 6 of 10 for repeatedTest INFO: About to execute repetition 7 of 10 for repeatedTest INFO: About to execute repetition 8 of 10 for repeatedTest INFO: About to execute repetition 9 of 10 for repeatedTest INFO: About to execute repetition 10 of 10 for repeatedTest INFO: About to execute repetition 1 of 5 for repeatedTestWithRepetitionInfo INFO: About to execute repetition 2 of 5 for repeatedTestWithRepetitionInfo INFO: About to execute repetition 3 of 5 for repeatedTestWithRepetitionInfo INFO: About to execute repetition 4 of 5 for repeatedTestWithRepetitionInfo INFO: About to execute repetition 5 of 5 for repeatedTestWithRepetitionInfo INFO: About to execute repetition 1 of 8 for repeatedTestWithFailureThreshold INFO: About to execute repetition 2 of 8 for repeatedTestWithFailureThreshold INFO: About to execute repetition 3 of 8 for repeatedTestWithFailureThreshold INFO: About to execute repetition 4 of 8 for repeatedTestWithFailureThreshold INFO: About to execute repetition 1 of 1 for customDisplayName INFO: About to execute repetition 1 of 1 for customDisplayNameWithLongPattern INFO: About to execute repetition 1 of 5 for repeatedTestInGerman INFO: About to execute repetition 2 of 5 for repeatedTestInGerman INFO: About to execute repetition 3 of 5 for repeatedTestInGerman INFO: About to execute repetition 4 of 5 for repeatedTestInGerman INFO: About to execute repetition 5 of 5 for repeatedTestInGerman
link:{testDir}/example/RepeatedTestsDemo.java[role=include]
When using the ConsoleLauncher
with the unicode theme enabled, execution of
RepeatedTestsDemo
results in the following output to the console.
├─ RepeatedTestsDemo ✔ │ ├─ repeatedTest() ✔ │ │ ├─ repetition 1 of 10 ✔ │ │ ├─ repetition 2 of 10 ✔ │ │ ├─ repetition 3 of 10 ✔ │ │ ├─ repetition 4 of 10 ✔ │ │ ├─ repetition 5 of 10 ✔ │ │ ├─ repetition 6 of 10 ✔ │ │ ├─ repetition 7 of 10 ✔ │ │ ├─ repetition 8 of 10 ✔ │ │ ├─ repetition 9 of 10 ✔ │ │ └─ repetition 10 of 10 ✔ │ ├─ repeatedTestWithRepetitionInfo(RepetitionInfo) ✔ │ │ ├─ repetition 1 of 5 ✔ │ │ ├─ repetition 2 of 5 ✔ │ │ ├─ repetition 3 of 5 ✔ │ │ ├─ repetition 4 of 5 ✔ │ │ └─ repetition 5 of 5 ✔ │ ├─ repeatedTestWithFailureThreshold(RepetitionInfo) ✔ │ │ ├─ repetition 1 of 8 ✔ │ │ ├─ repetition 2 of 8 ✘ Boom! │ │ ├─ repetition 3 of 8 ✔ │ │ ├─ repetition 4 of 8 ✘ Boom! │ │ ├─ repetition 5 of 8 ↷ Failure threshold [2] exceeded │ │ ├─ repetition 6 of 8 ↷ Failure threshold [2] exceeded │ │ ├─ repetition 7 of 8 ↷ Failure threshold [2] exceeded │ │ └─ repetition 8 of 8 ↷ Failure threshold [2] exceeded │ ├─ Repeat! ✔ │ │ └─ Repeat! 1/1 ✔ │ ├─ Details... ✔ │ │ └─ Details... :: repetition 1 of 1 ✔ │ └─ repeatedTestInGerman() ✔ │ ├─ Wiederholung 1 von 5 ✔ │ ├─ Wiederholung 2 von 5 ✔ │ ├─ Wiederholung 3 von 5 ✔ │ ├─ Wiederholung 4 von 5 ✔ │ └─ Wiederholung 5 von 5 ✔
Parameterized tests make it possible to run a test multiple times with different
arguments. They are declared just like regular @Test
methods but use the
{ParameterizedTest}
annotation instead. In addition, you must declare at least one
source that will provide the arguments for each invocation and then consume the
arguments in the test method.
The following example demonstrates a parameterized test that uses the @ValueSource
annotation to specify a String
array as the source of arguments.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
When executing the above parameterized test method, each invocation will be reported
separately. For instance, the ConsoleLauncher
will print output similar to the
following.
palindromes(String) ✔ ├─ [1] candidate=racecar ✔ ├─ [2] candidate=radar ✔ └─ [3] candidate=able was I ere I saw elba ✔
In order to use parameterized tests you need to add a dependency on the
junit-jupiter-params
artifact. Please refer to [dependency-metadata] for details.
Parameterized test methods typically consume arguments directly from the configured
source (see Sources of Arguments) following a one-to-one
correlation between argument source index and method parameter index (see examples in
@CsvSource). However, a parameterized test
method may also choose to aggregate arguments from the source into a single object
passed to the method (see Argument Aggregation).
Additional arguments may also be provided by a ParameterResolver
(e.g., to obtain an
instance of TestInfo
, TestReporter
, etc.). Specifically, a parameterized test method
must declare formal parameters according to the following rules.
-
Zero or more indexed arguments must be declared first.
-
Zero or more aggregators must be declared next.
-
Zero or more arguments supplied by a
ParameterResolver
must be declared last.
In this context, an indexed argument is an argument for a given index in the
Arguments
provided by an ArgumentsProvider
that is passed as an argument to the
parameterized method at the same index in the method’s formal parameter list. An
aggregator is any parameter of type ArgumentsAccessor
or any parameter annotated with
@AggregateWith
.
Note
|
AutoCloseable arguments
Arguments that implement To prevent this from happening, set the |
Out of the box, JUnit Jupiter provides quite a few source annotations. Each of the
following subsections provides a brief overview and an example for each of them. Please
refer to the Javadoc in the {params-provider-package}
package for additional
information.
@ValueSource
is one of the simplest possible sources. It lets you specify a single
array of literal values and can only be used for providing a single argument per
parameterized test invocation.
The following types of literal values are supported by @ValueSource
.
-
short
-
byte
-
int
-
long
-
float
-
double
-
char
-
boolean
-
java.lang.String
-
java.lang.Class
For example, the following @ParameterizedTest
method will be invoked three times, with
the values 1
, 2
, and 3
respectively.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
In order to check corner cases and verify proper behavior of our software when it is
supplied bad input, it can be useful to have null
and empty values supplied to our
parameterized tests. The following annotations serve as sources of null
and empty values
for parameterized tests that accept a single argument.
-
{NullSource}
: provides a singlenull
argument to the annotated@ParameterizedTest
method.-
@NullSource
cannot be used for a parameter that has a primitive type.
-
-
{EmptySource}
: provides a single empty argument to the annotated@ParameterizedTest
method for parameters of the following types:java.lang.String
,java.util.Collection
(and concrete subtypes with apublic
no-arg constructor),java.util.List
,java.util.Set
,java.util.SortedSet
,java.util.NavigableSet
,java.util.Map
(and concrete subtypes with apublic
no-arg constructor),java.util.SortedMap
,java.util.NavigableMap
, primitive arrays (e.g.,int[]
,char[][]
, etc.), object arrays (e.g.,String[]
,Integer[][]
, etc.). -
{NullAndEmptySource}
: a composed annotation that combines the functionality of@NullSource
and@EmptySource
.
If you need to supply multiple varying types of blank strings to a parameterized test,
you can achieve that using @ValueSource — for example, @ValueSource(strings = {" ", " ", "\t", "\n"})
.
You can also combine @NullSource
, @EmptySource
, and @ValueSource
to test a wider
range of null
, empty, and blank input. The following example demonstrates how to
achieve this for strings.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Making use of the composed @NullAndEmptySource
annotation simplifies the above as
follows.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Note
|
Both variants of the nullEmptyAndBlankStrings(String) parameterized test method
result in six invocations: 1 for null , 1 for the empty string, and 4 for the explicit
blank strings supplied via @ValueSource .
|
@EnumSource
provides a convenient way to use Enum
constants.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
The annotation’s value
attribute is optional. When omitted, the declared type of the
first method parameter is used. The test will fail if it does not reference an enum type.
Thus, the value
attribute is required in the above example because the method parameter
is declared as TemporalUnit
, i.e. the interface implemented by ChronoUnit
, which isn’t
an enum type. Changing the method parameter type to ChronoUnit
allows you to omit the
explicit enum type from the annotation as follows.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
The annotation provides an optional names
attribute that lets you specify which
constants shall be used, like in the following example. If omitted, all constants will be
used.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
The @EnumSource
annotation also provides an optional mode
attribute that enables
fine-grained control over which constants are passed to the test method. For example, you
can exclude names from the enum constant pool or specify regular expressions as in the
following examples.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
{MethodSource}
allows you to refer to one or more factory methods of the test class
or external classes.
Factory methods within the test class must be static
unless the test class is annotated
with @TestInstance(Lifecycle.PER_CLASS)
; whereas, factory methods in external classes
must always be static
.
Each factory method must generate a stream of arguments, and each set of arguments
within the stream will be provided as the physical arguments for individual invocations
of the annotated @ParameterizedTest
method. Generally speaking this translates to a
Stream
of Arguments
(i.e., Stream<Arguments>
); however, the actual concrete return
type can take on many forms. In this context, a "stream" is anything that JUnit can
reliably convert into a Stream
, such as Stream
, DoubleStream
, LongStream
,
IntStream
, Collection
, Iterator
, Iterable
, an array of objects, or an array of
primitives. The "arguments" within the stream can be supplied as an instance of
Arguments
, an array of objects (e.g., Object[]
), or a single value if the
parameterized test method accepts a single argument.
If you only need a single parameter, you can return a Stream
of instances of the
parameter type as demonstrated in the following example.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
If you do not explicitly provide a factory method name via @MethodSource
, JUnit Jupiter
will search for a factory method that has the same name as the current
@ParameterizedTest
method by convention. This is demonstrated in the following example.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Streams for primitive types (DoubleStream
, IntStream
, and LongStream
) are also
supported as demonstrated by the following example.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
If a parameterized test method declares multiple parameters, you need to return a
collection, stream, or array of Arguments
instances or object arrays as shown below
(see the Javadoc for {MethodSource}
for further details on supported return types).
Note that arguments(Object…)
is a static factory method defined in the Arguments
interface. In addition, Arguments.of(Object…)
may be used as an alternative to
arguments(Object…)
.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
An external, static
factory method can be referenced by providing its fully qualified
method name as demonstrated in the following example.
package example;
link:{testDir}/example/ExternalMethodSourceDemo.java[role=include]
Factory methods can declare parameters, which will be provided by registered
implementations of the ParameterResolver
extension API. In the following example, the
factory method is referenced by its name since there is only one such method in the test
class. If there are several local methods with the same name, parameters can also be
provided to differentiate them – for example, @MethodSource("factoryMethod()")
or
@MethodSource("factoryMethod(java.lang.String)")
. Alternatively, the factory method
can be referenced by its fully qualified method name, e.g.
@MethodSource("example.MyTests#factoryMethod(java.lang.String)")
.
link:{testDir}/example/MethodSourceParameterResolutionDemo.java[role=include]
{FieldSource}
allows you to refer to one or more fields of the test class or external
classes.
Fields within the test class must be static
unless the test class is annotated with
@TestInstance(Lifecycle.PER_CLASS)
; whereas, fields in external classes must always be
static
.
Each field must be able to supply a stream of arguments, and each set of "arguments"
within the "stream" will be provided as the physical arguments for individual invocations
of the annotated @ParameterizedTest
method.
In this context, a "stream" is anything that JUnit can reliably convert to a Stream
;
however, the actual concrete field type can take on many forms. Generally speaking this
translates to a Collection
, an Iterable
, a Supplier
of a stream (Stream
,
DoubleStream
, LongStream
, or IntStream
), a Supplier
of an Iterator
, an array of
objects, or an array of primitives. Each set of "arguments" within the "stream" can be
supplied as an instance of Arguments
, an array of objects (for example, Object[]
,
String[]
, etc.), or a single value if the parameterized test method accepts a single
argument.
Warning
|
In contrast to the supported return types for
|
Please note that a one-dimensional array of objects supplied as a set of "arguments" will
be handled differently than other types of arguments. Specifically, all of the elements
of a one-dimensional array of objects will be passed as individual physical arguments to
the @ParameterizedTest
method. See the Javadoc for {FieldSource}
for further details.
If you do not explicitly provide a field name via @FieldSource
, JUnit Jupiter will
search in the test class for a field that has the same name as the current
@ParameterizedTest
method by convention. This is demonstrated in the following example.
This parameterized test method will be invoked twice: with the values "apple"
and
"banana"
.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
The following example demonstrates how to provide a single explicit field name via
@FieldSource
. This parameterized test method will be invoked twice: with the values
"apple"
and "banana"
.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
The following example demonstrates how to provide multiple explicit field names via
@FieldSource
. This example uses the listOfFruits
field from the previous example as
well as the additionalFruits
field. Consequently, this parameterized test method will
be invoked four times: with the values "apple"
, "banana"
, "cherry"
, and
"dewberry"
.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
It is also possible to provide a Stream
, DoubleStream
, IntStream
, LongStream
, or
Iterator
as the source of arguments via a @FieldSource
field as long as the stream or
iterator is wrapped in a java.util.function.Supplier
. The following example demonstrates
how to provide a Supplier
of a Stream
of named arguments. This parameterized test
method will be invoked twice: with the values "apple"
and "banana"
and with display
names Apple
and Banana
, respectively.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Note
|
Note that Similarly, |
If a parameterized test method declares multiple parameters, the corresponding
@FieldSource
field must be able to provide a collection, stream supplier, or array of
Arguments
instances or object arrays as shown below (see the Javadoc for
{FieldSource}
for further details on supported types).
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Note
|
Note that |
An external, static
@FieldSource
field can be referenced by providing its
fully qualified field name as demonstrated in the following example.
link:{testDir}/example/ExternalFieldSourceDemo.java[role=include]
@CsvSource
allows you to express argument lists as comma-separated values (i.e., CSV
String
literals). Each string provided via the value
attribute in @CsvSource
represents a CSV record and results in one invocation of the parameterized test. The first
record may optionally be used to supply CSV headers (see the Javadoc for the
useHeadersInDisplayName
attribute for details and an example).
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
The default delimiter is a comma (,
), but you can use another character by setting the
delimiter
attribute. Alternatively, the delimiterString
attribute allows you to use a
String
delimiter instead of a single character. However, both delimiter attributes
cannot be set simultaneously.
By default, @CsvSource
uses a single quote ('
) as its quote character, but this can be
changed via the quoteCharacter
attribute. See the 'lemon, lime'
value in the example
above and in the table below. An empty, quoted value (''
) results in an empty String
unless the emptyValue
attribute is set; whereas, an entirely empty value is
interpreted as a null
reference. By specifying one or more nullValues
, a custom value
can be interpreted as a null
reference (see the NIL
example in the table below). An
ArgumentConversionException
is thrown if the target type of a null
reference is a
primitive type.
Note
|
An unquoted empty value will always be converted to a null reference regardless
of any custom values configured via the nullValues attribute.
|
Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed
by default. This behavior can be changed by setting the
ignoreLeadingAndTrailingWhitespace
attribute to true
.
Example Input | Resulting Argument List |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
If the programming language you are using supports text blocks — for example, Java SE
15 or higher — you can alternatively use the textBlock
attribute of @CsvSource
. Each
record within a text block represents a CSV record and results in one invocation of the
parameterized test. The first record may optionally be used to supply CSV headers by
setting the useHeadersInDisplayName
attribute to true
as in the example below.
Using a text block, the previous example can be implemented as follows.
@ParameterizedTest(name = "[{index}] {arguments}")
@CsvSource(useHeadersInDisplayName = true, textBlock = """
FRUIT, RANK
apple, 1
banana, 2
'lemon, lime', 0xF1
strawberry, 700_000
""")
void testWithCsvSource(String fruit, int rank) {
// ...
}
The generated display names for the previous example include the CSV header names.
[1] FRUIT = apple, RANK = 1 [2] FRUIT = banana, RANK = 2 [3] FRUIT = lemon, lime, RANK = 0xF1 [4] FRUIT = strawberry, RANK = 700_000
In contrast to CSV records supplied via the value
attribute, a text block can contain
comments. Any line beginning with a #
symbol will be treated as a comment and
ignored. Note, however, that the #
symbol must be the first character on the line
without any leading whitespace. It is therefore recommended that the closing text block
delimiter ("""
) be placed either at the end of the last line of input or on the
following line, left aligned with the rest of the input (as can be seen in the example
below which demonstrates formatting similar to a table).
@ParameterizedTest
@CsvSource(delimiter = '|', quoteCharacter = '"', textBlock = """
#-----------------------------
# FRUIT | RANK
#-----------------------------
apple | 1
#-----------------------------
banana | 2
#-----------------------------
"lemon lime" | 0xF1
#-----------------------------
strawberry | 700_000
#-----------------------------
""")
void testWithCsvSource(String fruit, int rank) {
// ...
}
Note
|
Java’s text block feature automatically removes incidental whitespace when the code is compiled. However other JVM languages such as Groovy and Kotlin do not. Thus, if you are using a programming language other than Java and your text block contains comments or new lines within quoted strings, you will need to ensure that there is no leading whitespace within your text block. |
@CsvFileSource
lets you use comma-separated value (CSV) files from the classpath or the
local file system. Each record from a CSV file results in one invocation of the
parameterized test. The first record may optionally be used to supply CSV headers. You can
instruct JUnit to ignore the headers via the numLinesToSkip
attribute. If you would like
for the headers to be used in the display names, you can set the useHeadersInDisplayName
attribute to true
. The examples below demonstrate the use of numLinesToSkip
and
useHeadersInDisplayName
.
The default delimiter is a comma (,
), but you can use another character by setting the
delimiter
attribute. Alternatively, the delimiterString
attribute allows you to use a
String
delimiter instead of a single character. However, both delimiter attributes
cannot be set simultaneously.
Note
|
Comments in CSV files
Any line beginning with a # symbol will be interpreted as a comment and will
be ignored.
|
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
link:{testResourcesDir}/two-column.csv[role=include]
The following listing shows the generated display names for the first two parameterized test methods above.
[1] country=Sweden, reference=1 [2] country=Poland, reference=2 [3] country=United States of America, reference=3 [4] country=France, reference=700_000
The following listing shows the generated display names for the last parameterized test method above that uses CSV header names.
[1] COUNTRY = Sweden, REFERENCE = 1 [2] COUNTRY = Poland, REFERENCE = 2 [3] COUNTRY = United States of America, REFERENCE = 3 [4] COUNTRY = France, REFERENCE = 700_000
In contrast to the default syntax used in @CsvSource
, @CsvFileSource
uses a double
quote ("
) as the quote character by default, but this can be changed via the
quoteCharacter
attribute. See the "United States of America"
value in the example
above. An empty, quoted value (""
) results in an empty String
unless the
emptyValue
attribute is set; whereas, an entirely empty value is interpreted as a
null
reference. By specifying one or more nullValues
, a custom value can be
interpreted as a null
reference. An ArgumentConversionException
is thrown if the
target type of a null
reference is a primitive type.
Note
|
An unquoted empty value will always be converted to a null reference regardless
of any custom values configured via the nullValues attribute.
|
Except within a quoted string, leading and trailing whitespace in a CSV column is trimmed
by default. This behavior can be changed by setting the
ignoreLeadingAndTrailingWhitespace
attribute to true
.
@ArgumentsSource
can be used to specify a custom, reusable ArgumentsProvider
. Note
that an implementation of ArgumentsProvider
must be declared as either a top-level
class or as a static
nested class.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
If you wish to implement a custom ArgumentsProvider
that also consumes an annotation
(like built-in providers such as {ValueArgumentsProvider}
or {CsvArgumentsProvider}
),
you have the possibility to extend the {AnnotationBasedArgumentsProvider}
class.
Repeatable annotations provide a convenient way to specify multiple sources from different providers.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Following the above parameterized test, a test case will run for each argument:
[1] foo [2] bar
The following annotations are repeatable:
-
@ValueSource
-
@EnumSource
-
@MethodSource
-
@FieldSource
-
@CsvSource
-
@CsvFileSource
-
@ArgumentsSource
JUnit Jupiter supports
Widening Primitive
Conversion for arguments supplied to a @ParameterizedTest
. For example, a
parameterized test annotated with @ValueSource(ints = { 1, 2, 3 })
can be declared to
accept not only an argument of type int
but also an argument of type long
, float
,
or double
.
To support use cases like @CsvSource
, JUnit Jupiter provides a number of built-in
implicit type converters. The conversion process depends on the declared type of each
method parameter.
For example, if a @ParameterizedTest
declares a parameter of type TimeUnit
and the
actual type supplied by the declared source is a String
, the string will be
automatically converted into the corresponding TimeUnit
enum constant.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
String
instances are implicitly converted to the following target types.
Note
|
Decimal, hexadecimal, and octal String literals will be converted to their
integral types: byte , short , int , long , and their boxed counterparts.
|
Target Type | Example |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In addition to implicit conversion from strings to the target types listed in the above
table, JUnit Jupiter also provides a fallback mechanism for automatic conversion from a
String
to a given target type if the target type declares exactly one suitable factory
method or a factory constructor as defined below.
-
factory method: a non-private,
static
method declared in the target type that accepts a singleString
argument and returns an instance of the target type. The name of the method can be arbitrary and need not follow any particular convention. -
factory constructor: a non-private constructor in the target type that accepts a single
String
argument. Note that the target type must be declared as either a top-level class or as astatic
nested class.
Note
|
If multiple factory methods are discovered, they will be ignored. If a factory method and a factory constructor are discovered, the factory method will be used instead of the constructor. |
For example, in the following @ParameterizedTest
method, the Book
argument will be
created by invoking the Book.fromTitle(String)
factory method and passing "42 Cats"
as the title of the book.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Instead of relying on implicit argument conversion you may explicitly specify an
ArgumentConverter
to use for a certain parameter using the @ConvertWith
annotation
like in the following example. Note that an implementation of ArgumentConverter
must be
declared as either a top-level class or as a static
nested class.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
If the converter is only meant to convert one type to another, you can extend
TypedArgumentConverter
to avoid boilerplate type checks.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
Explicit argument converters are meant to be implemented by test and extension authors.
Thus, junit-jupiter-params
only provides a single explicit argument converter that may
also serve as a reference implementation: JavaTimeArgumentConverter
. It is used via the
composed annotation JavaTimeConversionPattern
.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
If you wish to implement a custom ArgumentConverter
that also consumes an annotation
(like JavaTimeArgumentConverter
), you have the possibility to extend the
{AnnotationBasedArgumentConverter}
class.
By default, each argument provided to a @ParameterizedTest
method corresponds to a
single method parameter. Consequently, argument sources which are expected to supply a
large number of arguments can lead to large method signatures.
In such cases, an {ArgumentsAccessor}
can be used instead of multiple parameters. Using
this API, you can access the provided arguments through a single argument passed to your
test method. In addition, type conversion is supported as discussed in
Implicit Conversion.
Besides, you can retrieve the current test invocation index with
ArgumentsAccessor.getInvocationIndex()
.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
An instance of ArgumentsAccessor
is automatically injected into any parameter of type
ArgumentsAccessor
.
Apart from direct access to a @ParameterizedTest
method’s arguments using an
ArgumentsAccessor
, JUnit Jupiter also supports the usage of custom, reusable
aggregators.
To use a custom aggregator, implement the {ArgumentsAggregator}
interface and register
it via the @AggregateWith
annotation on a compatible parameter in the
@ParameterizedTest
method. The result of the aggregation will then be provided as an
argument for the corresponding parameter when the parameterized test is invoked. Note
that an implementation of ArgumentsAggregator
must be declared as either a top-level
class or as a static
nested class.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
If you find yourself repeatedly declaring @AggregateWith(MyTypeAggregator.class)
for
multiple parameterized test methods across your codebase, you may wish to create a custom
composed annotation such as @CsvToMyType
that is meta-annotated with
@AggregateWith(MyTypeAggregator.class)
. The following example demonstrates this in
action with a custom @CsvToPerson
annotation.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
By default, the display name of a parameterized test invocation contains the invocation
index and the String
representation of all arguments for that specific invocation. Each
argument is preceded by its parameter name (unless the argument is only available via an
ArgumentsAccessor
or ArgumentAggregator
), if the parameter name is present in the
bytecode (for Java, test code must be compiled with the -parameters
compiler flag).
However, you can customize invocation display names via the name
attribute of the
@ParameterizedTest
annotation like in the following example.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
When executing the above method using the ConsoleLauncher
you will see output similar to
the following.
Display name of container ✔ ├─ 1 ==> the rank of 'apple' is 1 ✔ ├─ 2 ==> the rank of 'banana' is 2 ✔ └─ 3 ==> the rank of 'lemon, lime' is 3 ✔
Note
|
Please note that |
The following placeholders are supported within custom display names.
Placeholder | Description |
---|---|
|
the display name of the method |
|
the current invocation index (1-based) |
|
the complete, comma-separated arguments list |
|
the complete, comma-separated arguments list with parameter names |
|
the name of the argument set |
|
|
|
an individual argument |
Note
|
When including arguments in display names, their string representations are truncated
if they exceed the configured maximum length. The limit is configurable via the
junit.jupiter.params.displayname.argument.maxlength configuration parameter and defaults
to 512 characters.
|
When using @MethodSource
, @FieldSource
, or @ArgumentsSource
, you can provide custom
names for individual arguments or custom names for entire sets of arguments.
Use the {Named}
API to provide a custom name for an individual argument, and the custom
name will be used if the argument is included in the invocation display name, like in the
example below.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
When executing the above method using the ConsoleLauncher
you will see output similar to
the following.
A parameterized test with named arguments ✔ ├─ 1: An important file ✔ └─ 2: Another file ✔
Note
|
Note that Similarly, |
Use the ArgumentSet
API to provide a custom name for the entire set of arguments, and
the custom name will be used as the display name, like in the example below.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
When executing the above method using the ConsoleLauncher
you will see output similar to
the following.
A parameterized test with named argument sets ✔ ├─ [1] Important files ✔ └─ [2] Other files ✔
Note
|
Note that |
If you’d like to set a default name pattern for all parameterized tests in your project,
you can declare the junit.jupiter.params.displayname.default
configuration parameter in
the junit-platform.properties
file as demonstrated in the following example (see
[running-tests-config-params] for other options).
junit.jupiter.params.displayname.default = {index}
The display name for a parameterized test is determined according to the following precedence rules:
-
name
attribute in@ParameterizedTest
, if present -
value of the
junit.jupiter.params.displayname.default
configuration parameter, if present -
DEFAULT_DISPLAY_NAME
constant defined in@ParameterizedTest
Each invocation of a parameterized test has the same lifecycle as a regular @Test
method. For example, @BeforeEach
methods will be executed before each invocation.
Similar to Dynamic Tests, invocations will appear one by one in the
test tree of an IDE. You may at will mix regular @Test
methods and @ParameterizedTest
methods within the same test class.
You may use ParameterResolver
extensions with @ParameterizedTest
methods. However,
method parameters that are resolved by argument sources need to come first in the
argument list. Since a test class may contain regular tests as well as parameterized
tests with different parameter lists, values from argument sources are not resolved for
lifecycle methods (e.g. @BeforeEach
) and test class constructors.
link:{testDir}/example/ParameterizedTestDemo.java[role=include]
A {TestTemplate}
method is not a regular test case but rather a template for test
cases. As such, it is designed to be invoked multiple times depending on the number of
invocation contexts returned by the registered providers. Thus, it must be used in
conjunction with a registered {TestTemplateInvocationContextProvider}
extension. Each
invocation of a test template method behaves like the execution of a regular @Test
method with full support for the same lifecycle callbacks and extensions. Please refer to
[extensions-test-templates] for usage examples.
Note
|
Repeated Tests and Parameterized Tests are built-in specializations of test templates. |
The standard @Test
annotation in JUnit Jupiter described in
Annotations is very similar to the @Test
annotation in JUnit 4. Both
describe methods that implement test cases. These test cases are static in the sense that
they are fully specified at compile time, and their behavior cannot be changed by
anything happening at runtime. Assumptions provide a basic form of dynamic behavior but
are intentionally rather limited in their expressiveness.
In addition to these standard tests a completely new kind of test programming model has
been introduced in JUnit Jupiter. This new kind of test is a dynamic test which is
generated at runtime by a factory method that is annotated with @TestFactory
.
In contrast to @Test
methods, a @TestFactory
method is not itself a test case but
rather a factory for test cases. Thus, a dynamic test is the product of a factory.
Technically speaking, a @TestFactory
method must return a single DynamicNode
or a
Stream
, Collection
, Iterable
, Iterator
, or array of DynamicNode
instances.
Instantiable subclasses of DynamicNode
are DynamicContainer
and DynamicTest
.
DynamicContainer
instances are composed of a display name and a list of dynamic child
nodes, enabling the creation of arbitrarily nested hierarchies of dynamic nodes.
DynamicTest
instances will be executed lazily, enabling dynamic and even
non-deterministic generation of test cases.
Any Stream
returned by a @TestFactory
will be properly closed by calling
stream.close()
, making it safe to use a resource such as Files.lines()
.
As with @Test
methods, @TestFactory
methods must not be private
or static
and may
optionally declare parameters to be resolved by ParameterResolvers
.
A DynamicTest
is a test case generated at runtime. It is composed of a display name
and an Executable
. Executable
is a @FunctionalInterface
which means that the
implementations of dynamic tests can be provided as lambda expressions or method
references.
Warning
|
Dynamic Test Lifecycle
The execution lifecycle of a dynamic test is quite different than it is for a
standard @Test case. Specifically, there are no lifecycle callbacks for individual
dynamic tests. This means that @BeforeEach and @AfterEach methods and their
corresponding extension callbacks are executed for the @TestFactory method but not for
each dynamic test. In other words, if you access fields from the test instance within a
lambda expression for a dynamic test, those fields will not be reset by callback methods
or extensions between the execution of individual dynamic tests generated by the same
@TestFactory method.
|
As of JUnit Jupiter {jupiter-version}, dynamic tests must always be created by factory methods; however, this might be complemented by a registration facility in a later release.
The following DynamicTestsDemo
class demonstrates several examples of test factories
and dynamic tests.
The first method returns an invalid return type. Since an invalid return type cannot be
detected at compile time, a JUnitException
is thrown when it is detected at runtime.
The next six methods demonstrate the generation of a Collection
, Iterable
, Iterator
,
array, or Stream
of DynamicTest
instances. Most of these examples do not really
exhibit dynamic behavior but merely demonstrate the supported return types in principle.
However, dynamicTestsFromStream()
and dynamicTestsFromIntStream()
demonstrate how to
generate dynamic tests for a given set of strings or a range of input numbers.
The next method is truly dynamic in nature. generateRandomNumberOfTests()
implements an
Iterator
that generates random numbers, a display name generator, and a test executor
and then provides all three to DynamicTest.stream()
. Although the non-deterministic
behavior of generateRandomNumberOfTests()
is of course in conflict with test
repeatability and should thus be used with care, it serves to demonstrate the
expressiveness and power of dynamic tests.
The next method is similar to generateRandomNumberOfTests()
in terms of flexibility;
however, dynamicTestsFromStreamFactoryMethod()
generates a stream of dynamic tests from
an existing Stream
via the DynamicTest.stream()
factory method.
For demonstration purposes, the dynamicNodeSingleTest()
method generates a single
DynamicTest
instead of a stream, and the dynamicNodeSingleContainer()
method generates
a nested hierarchy of dynamic tests utilizing DynamicContainer
.
link:{testDir}/example/DynamicTestsDemo.java[role=include]
The JUnit Platform provides TestSource
, a representation of the source of a test or
container used to navigate to its location by IDEs and build tools.
The TestSource
for a dynamic test or dynamic container can be constructed from a
java.net.URI
which can be supplied via the DynamicTest.dynamicTest(String, URI,
Executable)
or DynamicContainer.dynamicContainer(String, URI, Stream)
factory method,
respectively. The URI
will be converted to one of the following TestSource
implementations.
ClasspathResourceSource
-
If the
URI
contains theclasspath
scheme — for example,classpath:/test/foo.xml?line=20,column=2
. DirectorySource
-
If the
URI
represents a directory present in the file system. FileSource
-
If the
URI
represents a file present in the file system. MethodSource
-
If the
URI
contains themethod
scheme and the fully qualified method name (FQMN) — for example,method:org.junit.Foo#bar(java.lang.String, java.lang.String[])
. Please refer to the Javadoc for{DiscoverySelectors}.{DiscoverySelectors_selectMethod}
for the supported formats for a FQMN. ClassSource
-
If the
URI
contains theclass
scheme and the fully qualified class name — for example,class:org.junit.Foo?line=42
. UriSource
-
If none of the above
TestSource
implementations are applicable.
The @Timeout
annotation allows one to declare that a test, test factory, test template,
or lifecycle method should fail if its execution time exceeds a given duration. The time
unit for the duration defaults to seconds but is configurable.
The following example shows how @Timeout
is applied to lifecycle and test methods.
link:{testDir}/example/TimeoutDemo.java[role=include]
To apply the same timeout to all test methods within a test class and all of its @Nested
classes, you can declare the @Timeout
annotation at the class level. It will then be
applied to all test, test factory, and test template methods within that class and its
@Nested
classes unless overridden by a @Timeout
annotation on a specific method or
@Nested
class. Please note that @Timeout
annotations declared at the class level are
not applied to lifecycle methods.
Declaring @Timeout
on a @TestFactory
method checks that the factory method returns
within the specified duration but does not verify the execution time of each individual
DynamicTest
generated by the factory. Please use
assertTimeout()
or assertTimeoutPreemptively()
for that purpose.
If @Timeout
is present on a @TestTemplate
method — for example, a @RepeatedTest
or
@ParameterizedTest
— each invocation will have the given timeout applied to it.
The timeout can be applied using one of the following three thread modes: SAME_THREAD
,
SEPARATE_THREAD
, or INFERRED
.
When SAME_THREAD
is used, the execution of the annotated method proceeds in the main
thread of the test. If the timeout is exceeded, the main thread is interrupted from
another thread. This is done to ensure interoperability with frameworks such as Spring
that make use of mechanisms that are sensitive to the currently running thread — for
example, ThreadLocal
transaction management.
On the contrary when SEPARATE_THREAD
is used, like the assertTimeoutPreemptively()
assertion, the execution of the annotated method proceeds in a separate thread, this
can lead to undesirable side effects, see Preemptive Timeouts with assertTimeoutPreemptively()
.
When INFERRED
(default) thread mode is used, the thread mode is resolved via the
junit.jupiter.execution.timeout.thread.mode.default
configuration parameter. If the
provided configuration parameter is invalid or not present then SAME_THREAD
is used as
fallback.
The following configuration parameters can be used to
specify default timeouts for all methods of a certain category unless they or an enclosing
test class is annotated with @Timeout
:
junit.jupiter.execution.timeout.default
-
Default timeout for all testable and lifecycle methods
junit.jupiter.execution.timeout.testable.method.default
-
Default timeout for all testable methods
junit.jupiter.execution.timeout.test.method.default
-
Default timeout for
@Test
methods junit.jupiter.execution.timeout.testtemplate.method.default
-
Default timeout for
@TestTemplate
methods junit.jupiter.execution.timeout.testfactory.method.default
-
Default timeout for
@TestFactory
methods junit.jupiter.execution.timeout.lifecycle.method.default
-
Default timeout for all lifecycle methods
junit.jupiter.execution.timeout.beforeall.method.default
-
Default timeout for
@BeforeAll
methods junit.jupiter.execution.timeout.beforeeach.method.default
-
Default timeout for
@BeforeEach
methods junit.jupiter.execution.timeout.aftereach.method.default
-
Default timeout for
@AfterEach
methods junit.jupiter.execution.timeout.afterall.method.default
-
Default timeout for
@AfterAll
methods
More specific configuration parameters override less specific ones. For example,
junit.jupiter.execution.timeout.test.method.default
overrides
junit.jupiter.execution.timeout.testable.method.default
which overrides
junit.jupiter.execution.timeout.default
.
The values of such configuration parameters must be in the following, case-insensitive
format: <number> [ns|μs|ms|s|m|h|d]
. The space between the number and the unit may be
omitted. Specifying no unit is equivalent to using seconds.
Parameter value | Equivalent annotation |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When dealing with asynchronous code, it is common to write tests that poll while waiting
for something to happen before performing any assertions. In some cases you can rewrite
the logic to use a CountDownLatch
or another synchronization mechanism, but sometimes
that is not possible — for example, if the subject under test sends a message to a channel
in an external message broker and assertions cannot be performed until the message has
been successfully sent through the channel. Asynchronous tests like these require some
form of timeout to ensure they don’t hang the test suite by executing indefinitely, as
would be the case if an asynchronous message never gets successfully delivered.
By configuring a timeout for an asynchronous test that polls, you can ensure that the test
does not execute indefinitely. The following example demonstrates how to achieve this with
JUnit Jupiter’s @Timeout
annotation. This technique can be used to implement "poll
until" logic very easily.
link:{testDir}/example/PollingTimeoutDemo.java[role=include]
Note
|
If you need more control over polling intervals and greater flexibility with asynchronous tests, consider using a dedicated library such as Awaitility. |
When stepping through your code in a debug session, a fixed timeout limit may influence the result of the test, e.g. mark the test as failed although all assertions were met.
JUnit Jupiter supports the junit.jupiter.execution.timeout.mode
configuration parameter
to configure when timeouts are applied. There are three modes: enabled
, disabled
,
and disabled_on_debug
. The default mode is enabled
.
A VM runtime is considered to run in debug mode when one of its input parameters starts
with -agentlib:jdwp
or -Xrunjdwp
.
This heuristic is queried by the disabled_on_debug
mode.
By default, JUnit Jupiter tests are run sequentially in a single thread. Running tests in
parallel — for example, to speed up execution — is available as an opt-in feature since
version 5.3. To enable parallel execution, set the
junit.jupiter.execution.parallel.enabled
configuration parameter to true
— for
example, in junit-platform.properties
(see [running-tests-config-params] for other
options).
Please note that enabling this property is only the first step required to execute tests in parallel. If enabled, test classes and methods will still be executed sequentially by default. Whether or not a node in the test tree is executed concurrently is controlled by its execution mode. The following two modes are available.
SAME_THREAD
-
Force execution in the same thread used by the parent. For example, when used on a test method, the test method will be executed in the same thread as any
@BeforeAll
or@AfterAll
methods of the containing test class. CONCURRENT
-
Execute concurrently unless a resource lock forces execution in the same thread.
By default, nodes in the test tree use the SAME_THREAD
execution mode. You can change
the default by setting the junit.jupiter.execution.parallel.mode.default
configuration
parameter. Alternatively, you can use the {Execution}
annotation to change the
execution mode for the annotated element and its subelements (if any) which allows you to
activate parallel execution for individual test classes, one by one.
junit.jupiter.execution.parallel.enabled = true
junit.jupiter.execution.parallel.mode.default = concurrent
The default execution mode is applied to all nodes of the test tree with a few notable
exceptions, namely test classes that use the Lifecycle.PER_CLASS
mode or a
{MethodOrderer}
(except for {MethodOrderer_Random}
). In the former case, test authors
have to ensure that the test class is thread-safe; in the latter, concurrent execution
might conflict with the configured execution order. Thus, in both cases, test methods in
such test classes are only executed concurrently if the @Execution(CONCURRENT)
annotation is present on the test class or method.
When parallel execution is enabled and a default {ClassOrderer}
is registered (see
Class Order for details), top-level test classes will
initially be sorted accordingly and scheduled in that order. However, they are not
guaranteed to be started in exactly that order since the threads they are executed on are
not controlled directly by JUnit.
All nodes of the test tree that are configured with the CONCURRENT
execution mode will
be executed fully in parallel according to the provided
configuration while observing the
declarative synchronization
mechanism. Please note that [running-tests-capturing-output] needs to be enabled
separately.
In addition, you can configure the default execution mode for top-level classes by setting
the junit.jupiter.execution.parallel.mode.classes.default
configuration parameter. By
combining both configuration parameters, you can configure classes to run in parallel but
their methods in the same thread:
junit.jupiter.execution.parallel.enabled = true
junit.jupiter.execution.parallel.mode.default = same_thread
junit.jupiter.execution.parallel.mode.classes.default = concurrent
The opposite combination will run all methods within one class in parallel, but top-level classes will run sequentially:
junit.jupiter.execution.parallel.enabled = true
junit.jupiter.execution.parallel.mode.default = concurrent
junit.jupiter.execution.parallel.mode.classes.default = same_thread
The following diagram illustrates how the execution of two top-level test classes A
and
B
with two test methods per class behaves for all four combinations of
junit.jupiter.execution.parallel.mode.default
and
junit.jupiter.execution.parallel.mode.classes.default
(see labels in first column).
If the junit.jupiter.execution.parallel.mode.classes.default
configuration parameter is
not explicitly set, the value for junit.jupiter.execution.parallel.mode.default
will be
used instead.
Properties such as the desired parallelism and the maximum pool size can be configured
using a {ParallelExecutionConfigurationStrategy}
. The JUnit Platform provides two
implementations out of the box: dynamic
and fixed
. Alternatively, you may implement a
custom
strategy.
To select a strategy, set the junit.jupiter.execution.parallel.config.strategy
configuration parameter to one of the following options.
dynamic
-
Computes the desired parallelism based on the number of available processors/cores multiplied by the
junit.jupiter.execution.parallel.config.dynamic.factor
configuration parameter (defaults to1
). The optionaljunit.jupiter.execution.parallel.config.dynamic.max-pool-size-factor
configuration parameter can be used to limit the maximum number of threads. fixed
-
Uses the mandatory
junit.jupiter.execution.parallel.config.fixed.parallelism
configuration parameter as the desired parallelism. The optionaljunit.jupiter.execution.parallel.config.fixed.max-pool-size
configuration parameter can be used to limit the maximum number of threads. custom
-
Allows you to specify a custom
{ParallelExecutionConfigurationStrategy}
implementation via the mandatoryjunit.jupiter.execution.parallel.config.custom.class
configuration parameter to determine the desired configuration.
If no configuration strategy is set, JUnit Jupiter uses the dynamic
configuration
strategy with a factor of 1
. Consequently, the desired parallelism will be equal to the
number of available processors/cores.
Note
|
Parallelism alone does not imply maximum number of concurrent threads
By default JUnit Jupiter does not guarantee that the number of concurrently
executing tests will not exceed the configured parallelism. For example, when using one
of the synchronization mechanisms described in the next section, the ForkJoinPool that
is used behind the scenes may spawn additional threads to ensure execution continues with
sufficient parallelism.
If you require such guarantees, with Java 9+, it is possible to limit the maximum number
of concurrent threads by controlling the maximum pool size of the dynamic , fixed and
custom strategies.
|
The following table lists relevant properties for configuring parallel execution. See [running-tests-config-params] for details on how to set such properties.
Property | Description | Supported Values | Default Value |
---|---|---|---|
|
Enable parallel test execution |
|
|
|
Default execution mode of nodes in the test tree |
|
|
|
Default execution mode of top-level classes |
|
|
|
Execution strategy for desired parallelism and maximum pool size |
|
|
|
Factor to be multiplied by the number of available processors/cores to determine the
desired parallelism for the |
a positive decimal number |
|
|
Factor to be multiplied by the number of available processors/cores and the value of
|
a positive decimal number, must be greater than or equal to |
256 + the value of |
|
Disable saturation of the underlying fork-join pool for the |
|
|
|
Desired parallelism for the |
a positive integer |
no default value |
|
Desired maximum pool size of the underlying fork-join pool for the |
a positive integer, must be greater than or equal to |
256 + the value of |
|
Disable saturation of the underlying fork-join pool for the |
|
|
|
Fully qualified class name of the ParallelExecutionConfigurationStrategy to be
used for the |
for example, org.example.CustomStrategy |
no default value |
In addition to controlling the execution mode using the {Execution}
annotation, JUnit
Jupiter provides another annotation-based declarative synchronization mechanism. The
{ResourceLock}
annotation allows you to declare that a test class or method uses a
specific shared resource that requires synchronized access to ensure reliable test
execution. The shared resource is identified by a unique name which is a String
. The
name can be user-defined or one of the predefined constants in {Resources}
:
SYSTEM_PROPERTIES
, SYSTEM_OUT
, SYSTEM_ERR
, LOCALE
, or TIME_ZONE
.
If the tests in the following example were run in parallel without the use of {ResourceLock}, they would be flaky. Sometimes they would pass, and at other times they would fail due to the inherent race condition of writing and then reading the same JVM System Property.
When access to shared resources is declared using the {ResourceLock}
annotation, the
JUnit Jupiter engine uses this information to ensure that no conflicting tests are run in
parallel. This guarantee extends to lifecycle methods of a test class or method. For
example, if a test method is annotated with a {ResourceLock}
annotation, the "lock" will
be acquired before any @BeforeEach
methods are executed and released after all
@AfterEach
methods have been executed.
Note
|
Running tests in isolation
If most of your test classes can be run in parallel without any synchronization but you
have some test classes that need to run in isolation, you can mark the latter with the
|
In addition to the String
that uniquely identifies the shared resource, you may specify
an access mode. Two tests that require READ
access to a shared resource may run in
parallel with each other but not while any other test that requires READ_WRITE
access
to the same shared resource is running.
link:{testDir}/example/SharedResourcesDemo.java[role=include]
While the JUnit team encourages reusable extensions to be packaged and maintained in separate libraries, JUnit Jupiter includes a few user-facing extension implementations that are considered so generally useful that users shouldn’t have to add another dependency.
The built-in {TempDirectory}
extension is used to create and clean up a temporary
directory for an individual test or all tests in a test class. It is registered by
default. To use it, annotate a non-final, unassigned field of type java.nio.file.Path
or
java.io.File
with {TempDir}
or add a parameter of type java.nio.file.Path
or
java.io.File
annotated with @TempDir
to a lifecycle method or test method.
For example, the following test declares a parameter annotated with @TempDir
for a
single test method, creates and writes to a file in the temporary directory, and checks
its content.
link:{testDir}/example/TempDirectoryDemo.java[role=include]
You can inject multiple temporary directories by specifying multiple annotated parameters.
link:{testDir}/example/TempDirectoryDemo.java[role=include]
Warning
|
To revert to the old behavior of using a single temporary directory for the
entire test class or method (depending on which level the annotation is used), you can set
the junit.jupiter.tempdir.scope configuration parameter to per_context . However,
please note that this option is deprecated and will be removed in a future release.
|
@TempDir
is not supported on constructor parameters. If you wish to retain a single
reference to a temp directory across lifecycle methods and the current test method, please
use field injection by annotating an instance field with @TempDir
.
The following example stores a shared temporary directory in a static
field. This
allows the same sharedTempDir
to be used in all lifecycle methods and test methods of
the test class. For better isolation, you should use an instance field so that each test
method uses a separate directory.
link:{testDir}/example/TempDirectoryDemo.java[role=include]
The @TempDir
annotation has an optional cleanup
attribute that can be set to either
NEVER
, ON_SUCCESS
, or ALWAYS
. If the cleanup mode is set to NEVER
, temporary
directories are not deleted after a test completes. If it is set to ON_SUCCESS
,
temporary directories are deleted only after a test completed successfully.
The default cleanup mode is ALWAYS
. You can use the
junit.jupiter.tempdir.cleanup.mode.default
configuration parameter to override this default.
link:{testDir}/example/TempDirectoryDemo.java[role=include]
@TempDir
supports the programmatic creation of temporary directories via the optional
factory
attribute. This is typically used to gain control over the temporary directory
creation, like defining the parent directory or the file system that should be used.
Factories can be created by implementing TempDirFactory
. Implementations must provide a
no-args constructor and should not make any assumptions regarding when and how many times
they are instantiated, but they can assume that their createTempDirectory(…)
and
close()
methods will both be called once per instance, in this order, and from the same
thread.
The default implementation available in Jupiter delegates the directory creation to
java.nio.file.Files::createTempDirectory
, passing junit
as the prefix string to be
used in generating the directory’s name.
The following example defines a factory that uses the test name as the directory name
prefix instead of the junit
constant value.
link:{testDir}/example/TempDirectoryDemo.java[role=include]
It’s also possible to use an in-memory file system like {Jimfs}
for the creation of the
temporary directory. The following example demonstrates how to achieve that.
link:{testDir}/example/TempDirectoryDemo.java[role=include]
@TempDir
can also be used as a meta-annotation to
reduce repetition. The following code listing shows how to create a custom @JimfsTempDir
annotation that can be used as a drop-in replacement for
@TempDir(factory = JimfsTempDirFactory.class)
.
@TempDir
link:{testDir}/example/TempDirectoryDemo.java[role=include]
The following example demonstrates how to use the custom @JimfsTempDir
annotation.
link:{testDir}/example/TempDirectoryDemo.java[role=include]
Meta-annotations or additional annotations on the field or parameter the TempDir
annotation is declared on might expose additional attributes to configure the factory.
Such annotations and related attributes can be accessed via the AnnotatedElementContext
parameter of createTempDirectory
.
You can use the junit.jupiter.tempdir.factory.default
configuration parameter to specify the fully qualified
class name of the TempDirFactory
you would like to use by default. Just like for
factories configured via the factory
attribute of the @TempDir
annotation,
the supplied class has to implement the TempDirFactory
interface. The default factory
will be used for all @TempDir
annotations unless the factory
attribute of the
annotation specifies a different factory.
In summary, the factory for a temporary directory is determined according to the following precedence rules:
-
The
factory
attribute of the@TempDir
annotation, if present -
The default
TempDirFactory
configured via the configuration parameter, if present -
Otherwise,
org.junit.jupiter.api.io.TempDirFactory$Standard
will be used.
The built-in {AutoCloseExtension}
automatically closes resources associated with fields.
It is registered by default. To use it, annotate a field in a test class with
{AutoClose}
.
@AutoClose
fields may be either static
or non-static. If the value of an @AutoClose
field is null
when it is evaluated the field will be ignored, but a warning message will
be logged to inform you.
By default, @AutoClose
expects the value of the annotated field to implement a close()
method that will be invoked to close the resource. However, developers can customize the
name of the close method via the value
attribute. For example, @AutoClose("shutdown")
instructs JUnit to look for a shutdown()
method to close the resource.
@AutoClose
fields are inherited from superclasses. Furthermore, @AutoClose
fields from
subclasses will be closed before @AutoClose
fields in superclasses.
When multiple @AutoClose
fields exist within a given test class, the order in which the
resources are closed depends on an algorithm that is deterministic but intentionally
nonobvious. This ensures that subsequent runs of a test suite close resources in the same
order, thereby allowing for repeatable builds.
The AutoCloseExtension
implements the AfterAllCallback
and
TestInstancePreDestroyCallback
extension APIs. Consequently, a static
@AutoClose
field will be closed after all tests in the current test class have completed, effectively
after @AfterAll
methods have executed for the test class. A non-static @AutoClose
field will be closed before the current test class instance is destroyed. Specifically, if
the test class is configured with @TestInstance(Lifecycle.PER_METHOD)
semantics, a
non-static @AutoClose
field will be closed after the execution of each test method, test
factory method, or test template method. However, if the test class is configured with
@TestInstance(Lifecycle.PER_CLASS)
semantics, a non-static @AutoClose
field will not
be closed until the current test class instance is no longer needed, which means after
@AfterAll
methods and after all static
@AutoClose
fields have been closed.
The following example demonstrates how to annotate an instance field with @AutoClose
so
that the resource is automatically closed after test execution. In this example, we assume
that the default @TestInstance(Lifecycle.PER_METHOD)
semantics apply.
@AutoClose
to close a resourcelink:{testDir}/example/AutoCloseDemo.java[role=include]
-
Annotate an instance field with
@AutoClose
. -
WebClient
implementsjava.lang.AutoCloseable
which defines aclose()
method that will be invoked after each@Test
method.