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
junit.platform.discovery.issue.severity.critical: Property name used to configure the critical severity of issues encountered during test discovery. Defaults to ERROR.
junit.platform.execution.dryRun.enabled: Property name used to enable dry-run mode for test execution. Defaults to 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 <em>experimental</em> memory cleanup mode. Defaults to 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. Defaults to 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. Defaults to false.
junit.platform.output.capture.stdout: Property name used to enable capturing output to System#out. Defaults to 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. Defaults to true.

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. 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.
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. Defaults to WORKER_THREAD_POOL.
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. Defaults to true.
junit.jupiter.execution.parallel.config.strategy: Property name used to select the parallel execution configuration strategy. Defaults to DYNAMIC.
junit.jupiter.execution.parallel.enabled: Property name used to enable parallel test execution. Defaults to false.
junit.jupiter.execution.parallel.mode.classes.default: Property name used to set the default test execution mode for top-level classes.
junit.jupiter.execution.parallel.mode.default: Property name used to set the default test execution mode. Defaults to SAME_THREAD.
junit.jupiter.execution.timeout.afterall.method.default: Property name used to set the default timeout for all @AfterAll methods.
junit.jupiter.execution.timeout.aftereach.method.default: Property name used to set the default timeout for all @AfterEach methods.
junit.jupiter.execution.timeout.beforeall.method.default: Property name used to set the default timeout for all @BeforeAll methods.
junit.jupiter.execution.timeout.beforeeach.method.default: Property name used to set the default timeout for all @BeforeEach methods.
junit.jupiter.execution.timeout.default: Property name used to set the default timeout for all testable and lifecycle methods.
junit.jupiter.execution.timeout.lifecycle.method.default: Property name used to set the default timeout for all lifecycle methods.
junit.jupiter.execution.timeout.mode: Property name used to configure whether timeouts are applied to tests. Defaults to ENABLED.
junit.jupiter.execution.timeout.test.method.default: Property name used to set the default timeout for all @Test methods.
junit.jupiter.execution.timeout.testable.method.default: Property name used to set the default timeout for all testable methods.
junit.jupiter.execution.timeout.testfactory.method.default: Property name used to set the default timeout for all @TestFactory methods.
junit.jupiter.execution.timeout.testtemplate.method.default: Property name used to set the default timeout for all @TestTemplate methods.
junit.jupiter.execution.timeout.thread.mode.default: Property name used to set the default timeout thread mode. Defaults to SAME_THREAD.
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. Defaults to false.
junit.jupiter.extensions.autodetection.enabled: Property name used to enable auto-detection and registration of extensions via Java’s java.util.ServiceLoader mechanism. Defaults to 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. Defaults to true.
junit.jupiter.extensions.testinstantiation.extensioncontextscope.default: Property name used to set the default extension context scope for extensions that participate in test instantiation. Defaults to DEFAULT.
junit.jupiter.tempdir.cleanup.mode.default: Property name used to configure the default CleanupMode for temporary directories created via the @TempDir annotation. Defaults to ALWAYS.
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. 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. 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.
junit.jupiter.testinstance.lifecycle.default: Property name used to set the default test instance lifecycle mode. Defaults to PER_METHOD.
junit.jupiter.testmethod.order.default: Property name used to set the default method orderer class name.

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. Defaults to true.
junit.vintage.execution.parallel.classes: Property name used to indicate whether parallel execution is enabled for test classes in the JUnit Vintage engine. Defaults to false.
junit.vintage.execution.parallel.enabled: Property name used to indicate whether parallel execution is enabled for the JUnit Vintage engine. Defaults to false.
junit.vintage.execution.parallel.methods: Property name used to indicate whether parallel execution is enabled for test methods in the JUnit Vintage engine. Defaults to false.
junit.vintage.execution.parallel.pool-size: Property name used to specify the size of the thread pool to be used for parallel execution.