Configuration Parameters

In addition to instructing the platform which test classes and test engines to include, which packages to scan, etc., it is sometimes necessary to provide additional custom configuration parameters that are specific to a particular test engine, listener, or registered extension. For example, the JUnit Jupiter TestEngine supports configuration parameters for the following use cases.

Configuration Parameters are text-based key-value pairs that can be supplied to test engines running on the JUnit Platform via one of the following mechanisms.

The configurationParameter() and configurationParameters() methods in LauncherDiscoveryRequestBuilder which is used to build a request supplied to the Launcher API.
When running tests via one of the tools provided by the JUnit Platform you can specify configuration parameters as follows:
- Console Launcher: use the --config command-line option.
- Gradle: use the systemProperty or systemProperties DSL.
- Maven Surefire provider: use the configurationParameters property.
The configurationParametersResources() method in LauncherDiscoveryRequestBuilder.
When running tests via the Console Launcher you can specify custom configuration files using the --config-resource command-line option.
JVM system properties.
The JUnit Platform default configuration file: a file named junit-platform.properties in the root of the class path that follows the syntax rules for Java Properties files.

Configuration parameters are looked up in the exact order defined above. Consequently, configuration parameters supplied directly to the Launcher take precedence over those supplied via custom configuration files, system properties, and the default configuration file. Similarly, configuration parameters supplied via system properties take precedence over those supplied via the default configuration file.

Pattern Matching Syntax

This section describes the pattern matching syntax that is applied to the configuration parameters used for the following features.

If the value for the given configuration parameter consists solely of an asterisk (*), the pattern will match against all candidate classes. Otherwise, the value will be treated as a comma-separated list of patterns where each pattern will be matched against the fully qualified class name (FQCN) of each candidate class. Any dot (.) in a pattern will match against a dot (.) or a dollar sign ($) in a FQCN. Any asterisk (*) will match against one or more characters in a FQCN. All other characters in a pattern will be matched one-to-one against a FQCN.

Examples:

*: matches all candidate classes.
org.junit.*: matches all candidate classes under the org.junit base package and any of its subpackages.
*.MyCustomImpl: matches every candidate class whose simple class name is exactly MyCustomImpl.
*System*: matches every candidate class whose FQCN contains System.
*System*, *Unit*: matches every candidate class whose FQCN contains System or Unit.
org.example.MyCustomImpl: matches the candidate class whose FQCN is exactly org.example.MyCustomImpl.
org.example.MyCustomImpl, org.example.TheirCustomImpl: matches candidate classes whose FQCN is exactly org.example.MyCustomImpl or org.example.TheirCustomImpl.

Reference

The following lists enumerate the configuration parameters supported by the JUnit Platform, Jupiter, and Vintage.

Third-party JUnit Platform test engines and JUnit Jupiter extensions may provide additional configuration parameters.

JUnit Platform

`junit.platform.discovery.issue.failure.phase`

Property name used to configure the phase that critical discovery issues should cause a failure.

Default

Value

Description

discovery

Discovery issues are reported during the discovery phase.

execution

Discovery issues are reported during the execution phase.

✓

automatic

Discovery issues are reported during the discovery phase if Launcher.discover is called, and during the execution phase if Launcher.execute is called.

`junit.platform.discovery.issue.severity.critical`

Property name used to configure the critical severity of issues encountered during test discovery.

Default

Value

Description

info

Indicates that the engine encountered something that could be potentially problematic, but could also happen due to a valid setup or configuration.

warning

Indicates that the engine encountered something that is problematic and might lead to unexpected behavior or will be removed or changed in a future release.

✓

error

Indicates that the engine encountered something that is definitely problematic and will lead to unexpected behavior.

`junit.platform.execution.dryRun.enabled`

Property name used to enable dry-run mode for test execution.

Default

Value

Description

true

✓

false

`junit.platform.execution.listeners.deactivate`

Property name used to provide patterns for deactivating listeners registered via the ServiceLoader mechanism.

`junit.platform.execution.memory.cleanup.enabled`

Property name used to enable the experimental memory cleanup mode.

Default

Value

Description

true

✓

false

`junit.platform.execution.memory.cleanup.engines.excluded`

Property name used to configure which test engines should be excluded from memory cleanup in case it's enabled.

`junit.platform.launcher.interceptors.enabled`

Property name used to enable support for LauncherInterceptor instances to be registered via the ServiceLoader mechanism.

Default

Value

Description

true

✓

false

`junit.platform.output.capture.maxBuffer`

Property name used to configure the maximum number of bytes for buffering to use per thread and output type if output capturing is enabled. Defaults to 4194304.

`junit.platform.output.capture.stderr`

Property name used to enable capturing output to System.err.

Default

Value

Description

true

✓

false

`junit.platform.output.capture.stdout`

Property name used to enable capturing output to System.out.

Default

Value

Description

true

✓

false

`junit.platform.reporting.output.dir`

Property name used to configure the output directory for reporting.

`junit.platform.stacktrace.pruning.enabled`

Property name used to enable or disable stack trace pruning.

Default

Value

Description

✓

true

false

JUnit Jupiter

`junit.jupiter.conditions.deactivate`

Property name used to provide patterns for deactivating conditions.

`junit.jupiter.displayname.generator.default`

Property name used to set the default display name generator class name. Value must be the fully qualified name of a class that implements DisplayNameGenerator. Defaults to org.junit.jupiter.api.DisplayNameGenerator.Standard.

`junit.jupiter.execution.parallel.config.custom.class`

Property name used to specify the fully qualified class name of the custom parallel execution configuration strategy to be used. Value must be the fully qualified name of a class that implements ParallelExecutionConfigurationStrategy.

`junit.jupiter.execution.parallel.config.dynamic.factor`

Property name used to set the factor to be multiplied with the number of available processors/cores to determine the desired parallelism for the dynamic configuration strategy. Defaults to 1.0.

`junit.jupiter.execution.parallel.config.executor-service`

Property name used to determine the desired parallel executor service type.

Default

Value

Description

fork_join_pool

Indicates that ForkJoinPoolHierarchicalTestExecutorService should be used.

✓

worker_thread_pool

Indicates that WorkerThreadPoolHierarchicalTestExecutorService should be used.

`junit.jupiter.execution.parallel.config.fixed.max-pool-size`

Property name used to configure the maximum pool size of the underlying fork-join pool for the fixed configuration strategy.

`junit.jupiter.execution.parallel.config.fixed.parallelism`

Property name used to set the desired parallelism for the fixed configuration strategy.

`junit.jupiter.execution.parallel.config.fixed.saturate`

Property name used to disable saturation of the underlying fork-join pool for the fixed configuration strategy.

Default

Value

Description

✓

true

false

`junit.jupiter.execution.parallel.config.strategy`

Property name used to select the parallel execution configuration strategy.

Default

Value

Description

fixed

✓

dynamic

custom

`junit.jupiter.execution.parallel.enabled`

Property name used to enable parallel test execution.

Default

Value

Description

true

✓

false

`junit.jupiter.execution.parallel.mode.classes.default`

Property name used to set the default test execution mode for top-level classes.

Value

Description

same_thread

Force execution in same thread as the parent node.

concurrent

Allow concurrent execution with any other node.

`junit.jupiter.execution.parallel.mode.default`

Property name used to set the default test execution mode.

Default

Value

Description

✓

same_thread

Force execution in same thread as the parent node.

concurrent

Allow concurrent execution with any other node.

`junit.jupiter.execution.timeout.afterall.method.default`

Property name used to set the default timeout for all @AfterAll methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.aftereach.method.default`

Property name used to set the default timeout for all @AfterEach methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.beforeall.method.default`

Property name used to set the default timeout for all @BeforeAll methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.beforeeach.method.default`

Property name used to set the default timeout for all @BeforeEach methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.default`

Property name used to set the default timeout for all testable and lifecycle methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.lifecycle.method.default`

Property name used to set the default timeout for all lifecycle methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.mode`

Property name used to configure whether timeouts are applied to tests.

Default

Value

Description

✓

enabled

Timeouts are applied to tests.

disabled

Timeouts are not applied to tests.

disabled_on_debug

Timeouts are not applied to tests when the JVM is started in debug mode.

`junit.jupiter.execution.timeout.test.method.default`

Property name used to set the default timeout for all @Test methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.testable.method.default`

Property name used to set the default timeout for all testable methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.testfactory.method.default`

Property name used to set the default timeout for all @TestFactory methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.testtemplate.method.default`

Property name used to set the default timeout for all @TestTemplate methods.

Example

Description

42

A duration in seconds

42 ns

A duration in nanoseconds

42 μs

A duration in microseconds

42 ms

A duration in milliseconds

42 s

A duration in seconds

42 m

A duration in minutes

42 h

A duration in hours

42 d

A duration in days

`junit.jupiter.execution.timeout.thread.mode.default`

Property name used to set the default timeout thread mode.

Default

Value

Description

✓

same_thread

The test code is executed in the thread of the calling code.

separate_thread

The test code is executed in a different thread than that of the calling code. Furthermore, execution of the test code will be preemptively aborted if the timeout is exceeded.

`junit.jupiter.execution.timeout.threaddump.enabled`

Property name used to enable dumping the stack of all threads to System.out when a timeout has occurred.

Default

Value

Description

true

✓

false

`junit.jupiter.extensions.autodetection.enabled`

Property name used to enable auto-detection and registration of extensions via Java's java.util.ServiceLoader mechanism.

Default

Value

Description

true

✓

false

`junit.jupiter.extensions.autodetection.exclude`

Property name used to exclude patterns for auto-detecting extensions.

`junit.jupiter.extensions.autodetection.include`

Property name used to include patterns for auto-detecting extensions. Defaults to *.

`junit.jupiter.extensions.store.close.autocloseable.enabled`

Property name used to enable auto-closing of AutoCloseable instances.

Default

Value

Description

✓

true

false

`junit.jupiter.extensions.testinstantiation.extensioncontextscope.default`

Property name used to set the default extension context scope for extensions that participate in test instantiation.

Default

Value

Description

✓

default

The extension should receive an ExtensionContext for the default scope.

test_method

The extension should receive an ExtensionContext scoped to the test method.

`junit.jupiter.tempdir.cleanup.mode.default`

Property name used to configure the default CleanupMode for temporary directories created via the @TempDir annotation.

Default

Value

Description

default

Use the default cleanup mode.

✓

always

Always clean up a temporary directory after the test has completed.

on_success

Only clean up a temporary directory if the test completed successfully.

never

Never clean up a temporary directory after the test has completed.

`junit.jupiter.tempdir.deletion.strategy.default`

Property name used to set the default deletion strategy class name for temporary directories created via the @TempDir annotation. Value must be the fully qualified name of a class that implements TempDirDeletionStrategy. Defaults to org.junit.jupiter.api.io.TempDirDeletionStrategy.Standard.

`junit.jupiter.tempdir.factory.default`

Property name used to set the default factory for temporary directories created via the @TempDir annotation. Value must be the fully qualified name of a class that implements TempDirFactory. Defaults to org.junit.jupiter.api.io.TempDirFactory.Standard.

`junit.jupiter.testclass.order.default`

Property name used to set the default class orderer class name. Value must be the fully qualified name of a class that implements ClassOrderer.

`junit.jupiter.testinstance.lifecycle.default`

Property name used to set the default test instance lifecycle mode.

Default

Value

Description

per_class

When using this mode, a new test instance will be created once per test class or class template.

✓

per_method

When using this mode, a new test instance will be created for each test method, test factory method, or test template method.

`junit.jupiter.testmethod.order.default`

Property name used to set the default method orderer class name. Value must be the fully qualified name of a class that implements MethodOrderer.

JUnit Vintage

`junit.vintage.discovery.issue.reporting.enabled`

Property name used to configure whether the JUnit Vintage engine should report discovery issues such as deprecation notices.

Default

Value

Description

✓

true

false

`junit.vintage.execution.parallel.classes`

Property name used to indicate whether parallel execution is enabled for test classes in the JUnit Vintage engine.

Default

Value

Description

true

✓

false

`junit.vintage.execution.parallel.enabled`

Property name used to indicate whether parallel execution is enabled for the JUnit Vintage engine.

Default

Value

Description

true

✓

false

`junit.vintage.execution.parallel.methods`

Property name used to indicate whether parallel execution is enabled for test methods in the JUnit Vintage engine.

Default

Value

Description

true

✓

false

`junit.vintage.execution.parallel.pool-size`

Property name used to specify the size of the thread pool to be used for parallel execution.