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.