[[running-tests]]
== Running Tests

[[running-tests-ide]]
=== IDE Support

[[running-tests-ide-intellij-idea]]
==== IntelliJ IDEA

IntelliJ IDEA supports running tests on the JUnit Platform since version 2016.2. For
details please see the
https://blog.jetbrains.com/idea/2016/08/using-junit-5-in-intellij-idea/[post on the
IntelliJ IDEA blog]. Note, however, that it is recommended to use IDEA 2017.3 or newer
since these newer versions of IDEA will download the following JARs automatically based
on the API version used in the project: `junit-platform-launcher`,
`junit-jupiter-engine`, and `junit-vintage-engine`.

WARNING: IntelliJ IDEA releases prior to IDEA 2017.3 bundle specific versions of JUnit 5.
Thus, if you want to use a newer version of JUnit Jupiter, execution of tests within the
IDE might fail due to version conflicts. In such cases, please follow the instructions
below to use a newer version of JUnit 5 than the one bundled with IntelliJ IDEA.

In order to use a different JUnit 5 version (e.g., {jupiter-version}), you may need to
include the corresponding versions of the `junit-platform-launcher`,
`junit-jupiter-engine`, and `junit-vintage-engine` JARs in the classpath.

.Additional Gradle Dependencies
[source,groovy]
[subs=attributes+]
----
// Only needed to run tests in a version of IntelliJ IDEA that bundles older versions
testRuntimeOnly("org.junit.platform:junit-platform-launcher:{platform-version}")
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:{jupiter-version}")
testRuntimeOnly("org.junit.vintage:junit-vintage-engine:{vintage-version}")
----

.Additional Maven Dependencies
[source,xml]
[subs=attributes+]
----
<!-- Only needed to run tests in a version of IntelliJ IDEA that bundles older versions -->
<dependency>
	<groupId>org.junit.platform</groupId>
	<artifactId>junit-platform-launcher</artifactId>
	<version>{platform-version}</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>org.junit.jupiter</groupId>
	<artifactId>junit-jupiter-engine</artifactId>
	<version>{jupiter-version}</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>org.junit.vintage</groupId>
	<artifactId>junit-vintage-engine</artifactId>
	<version>{vintage-version}</version>
	<scope>test</scope>
</dependency>
----

[[running-tests-ide-eclipse]]
==== Eclipse

Eclipse IDE offers support for the JUnit Platform since the Eclipse Oxygen.1a (4.7.1a)
release.

For more information on using JUnit 5 in Eclipse consult the official _Eclipse support
for JUnit 5_ section of the
https://www.eclipse.org/eclipse/news/4.7.1a/#junit-5-support[Eclipse Project Oxygen.1a
(4.7.1a) - New and Noteworthy] documentation.

[[running-tests-ide-netbeans]]
==== NetBeans

NetBeans offers support for JUnit Jupiter and the JUnit Platform since the
https://netbeans.apache.org/download/nb100/nb100.html[Apache NetBeans 10.0 release].

For more information consult the JUnit 5 section of the
https://netbeans.apache.org/download/nb100/index.html#_junit_5[Apache NetBeans 10.0
release notes].

[[running-tests-ide-vscode]]
==== Visual Studio Code

https://code.visualstudio.com/[Visual Studio Code] supports JUnit Jupiter and the JUnit
Platform via the
https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-test[Java Test
Runner] extension which is installed by default as part of the
https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack[Java
Extension Pack].

For more information consult the _Testing_ section of the
https://code.visualstudio.com/docs/languages/java#_testing[Java in Visual Studio Code]
documentation.

[[running-tests-ide-other]]
==== Other IDEs

If you are using an editor or IDE other than one of those listed in the previous sections,
the JUnit team provides two alternative solutions to assist you in using JUnit 5. You can
use the <<running-tests-console-launcher>> manually -- for example, from the command line
-- or execute tests with a <<running-tests-junit-platform-runner,JUnit 4 based Runner>> if
your IDE has built-in support for JUnit 4.

[[running-tests-build]]
=== Build Support

[[running-tests-build-gradle]]
==== Gradle

[WARNING]
.The JUnit Platform Gradle Plugin has been discontinued
====
The `junit-platform-gradle-plugin` developed by the JUnit team was deprecated in JUnit
Platform 1.2 and discontinued in 1.3. Please switch to Gradle's standard `test` task.
====

Starting with https://docs.gradle.org/4.6/release-notes.html[version 4.6], Gradle provides
https://docs.gradle.org/current/userguide/java_testing.html#using_junit5[native support]
for executing tests on the JUnit Platform. To enable it, you just need to specify
`useJUnitPlatform()` within a `test` task declaration in `build.gradle`:

[source,java,indent=0]
[subs=attributes+]
----
test {
    useJUnitPlatform()
}
----

Filtering by tags or engines is also supported:

[source,java,indent=0]
[subs=attributes+]
----
test {
    useJUnitPlatform {
        includeTags 'fast', 'smoke & feature-a'
        // excludeTags 'slow', 'ci'
        includeEngines 'junit-jupiter'
        // excludeEngines 'junit-vintage'
	}
}
----

Please refer to the
https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_test[official Gradle documentation]
for a comprehensive list of options.

[[running-tests-build-gradle-config-params]]
===== Configuration Parameters

The standard Gradle `test` task currently does not provide a dedicated DSL to set JUnit
Platform <<running-tests-config-params, configuration parameters>> to influence test
discovery and execution. However, you can provide configuration parameters within the
build script via system properties (as shown below) or via the
`junit-platform.properties` file.

[source,java,indent=0]
----
test {
	// ...
	systemProperty 'junit.jupiter.conditions.deactivate', '*'
	systemProperties = [
		'junit.jupiter.extensions.autodetection.enabled': 'true',
		'junit.jupiter.testinstance.lifecycle.default': 'per_class'
	]
	// ...
}
----

[[running-tests-build-gradle-engines-configure]]
===== Configuring Test Engines

In order to run any tests at all, a `TestEngine` implementation must be on the classpath.

To configure support for JUnit Jupiter based tests, configure a `testImplementation` dependency
on the JUnit Jupiter API and a `testRuntimeOnly` dependency on the JUnit Jupiter `TestEngine`
implementation similar to the following.

[source,java,indent=0]
[subs=attributes+]
----
dependencies {
	testImplementation("org.junit.jupiter:junit-jupiter-api:{jupiter-version}")
	testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:{jupiter-version}")
}
----

The JUnit Platform can run JUnit 4 based tests as long as you configure a `testImplementation`
dependency on JUnit 4 and a `testRuntimeOnly` dependency on the JUnit Vintage `TestEngine`
implementation similar to the following.

[source,java,indent=0]
[subs=attributes+]
----
dependencies {
	testImplementation("junit:junit:{junit4-version}")
	testRuntimeOnly("org.junit.vintage:junit-vintage-engine:{vintage-version}")
}
----

[[running-tests-build-gradle-logging]]
===== Configuring Logging (optional)

JUnit uses the Java Logging APIs in the `java.util.logging` package (a.k.a. _JUL_) to
emit warnings and debug information. Please refer to the official documentation of
`{LogManager}` for configuration options.

Alternatively, it's possible to redirect log messages to other logging frameworks such as
{Log4j} or {Logback}. To use a logging framework that provides a custom implementation of
`{LogManager}`, set the `java.util.logging.manager` system property to the _fully
qualified class name_ of the `{LogManager}` implementation to use. The example below
demonstrates how to configure Log4j{nbsp}2.x (see {Log4j_JDK_Logging_Adapter} for
details).

[source,java,indent=0]
[subs=attributes+]
----
test {
	systemProperty 'java.util.logging.manager', 'org.apache.logging.log4j.jul.LogManager'
}
----

Other logging frameworks provide different means to redirect messages logged using
`java.util.logging`. For example, for {Logback} you can use the
https://www.slf4j.org/legacy.html#jul-to-slf4j[JUL to SLF4J Bridge] by adding an
additional dependency to the runtime classpath.

[[running-tests-build-maven]]
==== Maven

[WARNING]
.The JUnit Platform Maven Surefire Provider has been discontinued
====
The `junit-platform-surefire-provider`, which was originally developed by the JUnit team,
was deprecated in JUnit Platform 1.3 and discontinued in 1.4. Please use Maven Surefire's
native support instead.
====

Starting with https://issues.apache.org/jira/browse/SUREFIRE-1330[version 2.22.0], Maven
Surefire and Maven Failsafe provide
https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html[native support]
for executing tests on the JUnit Platform. The `pom.xml` file in the
`{junit5-jupiter-starter-maven}` project demonstrates how to use the Maven Surefire plugin
and can serve as a starting point for configuring your Maven build.

[[running-tests-build-maven-engines-configure]]
===== Configuring Test Engines

In order to have Maven Surefire or Maven Failsafe run any tests at all, at least one
`TestEngine` implementation must be added to the test classpath.

To configure support for JUnit Jupiter based tests, configure `test` scoped dependencies
on the JUnit Jupiter API and the JUnit Jupiter `TestEngine` implementation similar to the
following.

[source,xml,indent=0]
[subs=attributes+]
----
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</version>
			</plugin>
			<plugin>
				<artifactId>maven-failsafe-plugin</artifactId>
				<version>{surefire-version}</version>
			</plugin>
		</plugins>
	</build>
	<!-- ... -->
	<dependencies>
		<!-- ... -->
		<dependency>
			<groupId>org.junit.jupiter</groupId>
			<artifactId>junit-jupiter-api</artifactId>
			<version>{jupiter-version}</version>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.junit.jupiter</groupId>
			<artifactId>junit-jupiter-engine</artifactId>
			<version>{jupiter-version}</version>
			<scope>test</scope>
		</dependency>
		<!-- ... -->
	</dependencies>
	<!-- ... -->
----

Maven Surefire and Maven Failsafe can run JUnit 4 based tests alongside Jupiter tests as
long as you configure `test` scoped dependencies on JUnit 4 and the JUnit Vintage
`TestEngine` implementation similar to the following.

[source,xml,indent=0]
[subs=attributes+]
----
	<!-- ... -->
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</version>
			</plugin>
			<plugin>
				<artifactId>maven-failsafe-plugin</artifactId>
				<version>{surefire-version}</version>
			</plugin>
		</plugins>
	</build>
	<!-- ... -->
	<dependencies>
		<!-- ... -->
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>{junit4-version}</version>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.junit.vintage</groupId>
			<artifactId>junit-vintage-engine</artifactId>
			<version>{vintage-version}</version>
			<scope>test</scope>
		</dependency>
		<!-- ... -->
	</dependencies>
	<!-- ... -->
----

[[running-tests-build-maven-filter-test-class-names]]
===== Filtering by Test Class Names

The Maven Surefire Plugin will scan for test classes whose fully qualified names match
the following patterns.

- `+**/Test*.java+`
- `+**/*Test.java+`
- `+**/*Tests.java+`
- `+**/*TestCase.java+`

Moreover, it will exclude all nested classes (including static member classes) by default.

Note, however, that you can override this default behavior by configuring explicit
`include` and `exclude` rules in your `pom.xml` file. For example, to keep Maven Surefire
from excluding static member classes, you can override its exclude rules as follows.

[source,xml,indent=0]
[subs=attributes+]
.Overriding exclude rules of Maven Surefire
----
	<!-- ... -->
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</version>
				<configuration>
					<excludes>
						<exclude/>
					</excludes>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<!-- ... -->
----

Please see the
https://maven.apache.org/surefire/maven-surefire-plugin/examples/inclusion-exclusion.html[Inclusions and Exclusions of Tests]
documentation for Maven Surefire for details.

[[running-tests-build-maven-filter-tags]]
===== Filtering by Tags

You can filter tests by tags or <<running-tests-tag-expressions, tag expressions>> using
the following configuration properties.

- to include _tags_ or _tag expressions_, use `groups`.
- to exclude _tags_ or _tag expressions_, use `excludedGroups`.

[source,xml,indent=0]
[subs=attributes+]
----
	<!-- ... -->
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</version>
				<configuration>
					<groups>acceptance | !feature-a</groups>
					<excludedGroups>integration, regression</excludedGroups>
			    </configuration>
			</plugin>
		</plugins>
	</build>
	<!-- ... -->
----

[[running-tests-build-maven-config-params]]
===== Configuration Parameters

You can set JUnit Platform <<running-tests-config-params, configuration parameters>> to
influence test discovery and execution by declaring the `configurationParameters`
property and providing key-value pairs using the Java `Properties` file syntax (as shown
below) or via the `junit-platform.properties` file.

[source,xml,indent=0]
[subs=attributes+]
----
	<!-- ... -->
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</version>
				<configuration>
					<properties>
						<configurationParameters>
							junit.jupiter.conditions.deactivate = *
							junit.jupiter.extensions.autodetection.enabled = true
							junit.jupiter.testinstance.lifecycle.default = per_class
						</configurationParameters>
					</properties>
				</configuration>
			</plugin>
		</plugins>
	</build>
	<!-- ... -->
----

[[running-tests-build-ant]]
==== Ant

Starting with version `1.10.3` of link:https://ant.apache.org/[Ant], a new
link:https://ant.apache.org/manual/Tasks/junitlauncher.html[`junitlauncher`] task has
been introduced to provide native support for launching tests on the JUnit Platform. The
`junitlauncher` task is solely responsible for launching the JUnit Platform and passing
it the selected collection of tests. The JUnit Platform then delegates to registered test
engines to discover and execute the tests.

The `junitlauncher` task attempts to align as close as possible with native Ant
constructs such as
link:https://ant.apache.org/manual/Types/resources.html#collection[resource collections]
for allowing users to select the tests that they want executed by test engines. This
gives the task a consistent and natural feel when compared to many other core Ant tasks.

Starting with version `1.10.6` of Ant, the `junitlauncher` task supports
link:https://ant.apache.org/manual/Tasks/junitlauncher.html#fork[forking the tests in a separate JVM].

The `build.xml` file in the `{junit5-jupiter-starter-ant}` project demonstrates how to use
the task and can serve as a starting point.

===== Basic Usage

The following example demonstrates how to configure the `junitlauncher` task to select a
single test class (i.e., `org.myapp.test.MyFirstJUnit5Test`).

[source,xml,indent=0]
----
	<path id="test.classpath">
		<!-- The location where you have your compiled classes -->
		<pathelement location="${build.classes.dir}" />
	</path>

	<!-- ... -->

	<junitlauncher>
		<classpath refid="test.classpath" />
		<test name="org.myapp.test.MyFirstJUnit5Test" />
	</junitlauncher>
----

The `test` element allows you to specify a single test class that you want to be selected
and executed. The `classpath` element allows you to specify the classpath to be used to
launch the JUnit Platform. This classpath will also be used to locate test classes that
are part of the execution.

The following example demonstrates how to configure the `junitlauncher` task to select
test classes from multiple locations.

[source,xml,indent=0]
----
	<path id="test.classpath">
		<!-- The location where you have your compiled classes -->
		<pathelement location="${build.classes.dir}" />
	</path>
	<!-- ... -->
	<junitlauncher>
		<classpath refid="test.classpath" />
		<testclasses outputdir="${output.dir}">
			<fileset dir="${build.classes.dir}">
				<include name="org/example/**/demo/**/" />
			</fileset>
			<fileset dir="${some.other.dir}">
				<include name="org/myapp/**/" />
			</fileset>
		</testclasses>
	</junitlauncher>
----

In the above example, the `testclasses` element allows you to select multiple test
classes that reside in different locations.

For further details on usage and configuration options please refer to the official Ant
documentation for the
link:https://ant.apache.org/manual/Tasks/junitlauncher.html[`junitlauncher` task].

[[running-tests-console-launcher]]
=== Console Launcher

The `{ConsoleLauncher}` is a command-line Java application that lets you launch the JUnit
Platform from the console. For example, it can be used to run JUnit Vintage and JUnit
Jupiter tests and print test execution results to the console.

An executable `junit-platform-console-standalone-{platform-version}.jar` with all
dependencies included is published in the {Maven_Central} repository under the
https://repo1.maven.org/maven2/org/junit/platform/junit-platform-console-standalone[junit-platform-console-standalone]
directory. You can https://docs.oracle.com/javase/tutorial/deployment/jar/run.html[run]
the standalone `ConsoleLauncher` as shown below.

`java -jar junit-platform-console-standalone-{platform-version}.jar <<<running-tests-console-launcher-options>>>`

Here's an example of its output:

....
├─ JUnit Vintage
│  └─ example.JUnit4Tests
│     └─ standardJUnit4Test ✔
└─ JUnit Jupiter
   ├─ StandardTests
   │  ├─ succeedingTest() ✔
   │  └─ skippedTest() ↷ for demonstration purposes
   └─ A special test case
      ├─ Custom test name containing spaces ✔
      ├─ ╯°□°）╯ ✔
      └─ 😱 ✔

Test run finished after 64 ms
[         5 containers found      ]
[         0 containers skipped    ]
[         5 containers started    ]
[         0 containers aborted    ]
[         5 containers successful ]
[         0 containers failed     ]
[         6 tests found           ]
[         1 tests skipped         ]
[         5 tests started         ]
[         0 tests aborted         ]
[         5 tests successful      ]
[         0 tests failed          ]
....

.Exit Code
NOTE: The `{ConsoleLauncher}` exits with a status code of `1` if any containers or tests
failed. If no tests are discovered and the `--fail-if-no-tests` command-line option is
supplied, the `ConsoleLauncher` exits with a status code of `2`. Otherwise the exit code
is `0`.

[[running-tests-console-launcher-options]]
==== Options

----
include::{consoleLauncherOptionsFile}[]
----

[[running-tests-console-launcher-argument-files]]
==== Argument Files (@-files)

On some platforms you may run into system limitations on the length of a command line
when creating a command line with lots of options or with long arguments.

Since version 1.3, the `ConsoleLauncher` supports _argument files_, also known as
_@-files_. Argument files are files that themselves contain arguments to be passed to the
command. When the underlying https://github.com/remkop/picocli[picocli] command line
parser encounters an argument beginning with the character `@`, it expands the contents
of that file into the argument list.

The arguments within a file can be separated by spaces or newlines. If an argument
contains embedded whitespace, the whole argument should be wrapped in double or single
quotes -- for example, `"-f=My Files/Stuff.java"`.

If the argument file does not exist or cannot be read, the argument will be treated
literally and will not be removed. This will likely result in an "unmatched argument"
error message. You can troubleshoot such errors by executing the command with the
`picocli.trace` system property set to `DEBUG`.

Multiple _@-files_ may be specified on the command line. The specified path may be
relative to the current directory or absolute.

You can pass a real parameter with an initial `@` character by escaping it with an
additional `@` symbol. For example, `@@somearg` will become `@somearg` and will not be
subject to expansion.


[[running-tests-junit-platform-runner]]
=== Using JUnit 4 to run the JUnit Platform

The `JUnitPlatform` runner is a JUnit 4 based `Runner` which enables you to run any test
whose programming model is supported on the JUnit Platform in a JUnit 4 environment --
for example, a JUnit Jupiter test class.

Annotating a class with `@RunWith(JUnitPlatform.class)` allows it to be run with IDEs and
build systems that support JUnit 4 but do not yet support the JUnit Platform directly.

NOTE: Since the JUnit Platform has features that JUnit 4 does not have, the runner is
only able to support a subset of the JUnit Platform functionality, especially with regard
to reporting (see <<running-tests-junit-platform-runner-technical-names>>). But for the
time being the `JUnitPlatform` runner is an easy way to get started.

[[running-tests-junit-platform-runner-setup]]
==== Setup

You need the following artifacts and their dependencies on the classpath. See
<<dependency-metadata>> for details regarding group IDs, artifact IDs, and versions.

===== Explicit Dependencies

* `junit-platform-runner` in _test_ scope: location of the `JUnitPlatform` runner
* `junit-{junit4-version}.jar` in _test_ scope: to run tests using JUnit 4
* `junit-jupiter-api` in _test_ scope: API for writing tests using JUnit Jupiter,
  including `@Test`, etc.
* `junit-jupiter-engine` in _test runtime_ scope: implementation of the `TestEngine` API
  for JUnit Jupiter

===== Transitive Dependencies

* `junit-platform-suite-api` in _test_ scope
* `junit-platform-launcher` in _test_ scope
* `junit-platform-engine` in _test_ scope
* `junit-platform-commons` in _test_ scope
* `opentest4j` in _test_ scope

[[running-tests-junit-platform-runner-technical-names]]
==== Display Names vs. Technical Names

To define a custom _display name_ for the class run via `@RunWith(JUnitPlatform.class)`
simply annotate the class with `@SuiteDisplayName` and provide a custom value.

By default, _display names_ will be used for test artifacts; however, when the
`JUnitPlatform` runner is used to execute tests with a build tool such as Gradle or
Maven, the generated test report often needs to include the _technical names_ of test
artifacts — for example, fully qualified class names — instead of shorter display names
like the simple name of a test class or a custom display name containing special
characters. To enable technical names for reporting purposes, simply declare the
`@UseTechnicalNames` annotation alongside `@RunWith(JUnitPlatform.class)`.

Note that the presence of `@UseTechnicalNames` overrides any custom display name
configured via `@SuiteDisplayName`.

[[running-tests-junit-platform-runner-single-test]]
==== Single Test Class

One way to use the `JUnitPlatform` runner is to annotate a test class with
`@RunWith(JUnitPlatform.class)` directly. Please note that the test methods in the
following example are annotated with `org.junit.jupiter.api.Test` (JUnit Jupiter), not
`org.junit.Test` (JUnit 4). Moreover, in this case the test class must be `public`;
otherwise, some IDEs and build tools might not recognize it as a JUnit 4 test class.

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

[[running-tests-junit-platform-runner-test-suite]]
==== Test Suite

If you have multiple test classes you can create a test suite as can be seen in the
following example.

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

The `JUnitPlatformSuiteDemo` will discover and run all tests in the `example` package and
its subpackages. By default, it will only include test classes whose names either begin
with `Test` or end with `Test` or `Tests`.

.Additional Configuration Options
NOTE: There are more configuration options for discovering and filtering tests than just
`@SelectPackages`. Please consult the
{javadoc-root}/org/junit/platform/suite/api/package-summary.html[Javadoc] for further
details.

WARNING: Test classes and suites annotated with `@RunWith(JUnitPlatform.class)`
**cannot** be executed directly on the JUnit Platform (or as a "JUnit 5" test as
documented in some IDEs). Such classes and suites can only be executed using JUnit 4
infrastructure.

[[running-tests-config-params]]
=== 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 or registered
extension. For example, the JUnit Jupiter `TestEngine` supports _configuration
parameters_ for the following use cases.

- <<writing-tests-test-instance-lifecycle-changing-default>>
- <<extensions-registration-automatic-enabling>>
- <<extensions-conditions-deactivation>>
- <<writing-tests-display-name-generator-default>>

_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.

1. The `configurationParameter()` and `configurationParameters()` methods in the
  `LauncherDiscoveryRequestBuilder` which is used to build a request supplied to the
  <<launcher-api, `Launcher` API>>. When running tests via one of the tools provided
  by the JUnit Platform you can specify configuration parameters as follows:
  * <<running-tests-console-launcher,Console Launcher>>: use the `--config`
    command-line option.
  * <<running-tests-build-gradle-config-params,Gradle>>: use the
    `systemProperty` or `systemProperties` DSL.
  * <<running-tests-build-maven-config-params,Maven Surefire provider>>: use the
    `configurationParameters` property.
2. JVM system properties.
3. The JUnit Platform configuration file: a file named `junit-platform.properties` in the
  root of the class path that follows the syntax rules for a Java `Properties` file.

NOTE: 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 system properties and the configuration file.
Similarly, configuration parameters supplied via system properties take precedence over
those supplied via the configuration file.

[[running-tests-tag-expressions]]
=== Tag Expressions
Tag expressions are boolean expressions with the operators `!`, `&` and `|`. In addition,
`(` and `)` can be used to adjust for operator precedence.

.Operators (in descending order of precedence)
|===
| Operator | Meaning | Associativity

| `!`      | not     | right
| `&`      | and     | left
| `\|`     | or      | left
|===

If you are tagging your tests across multiple dimensions, tag expressions help you to
select which tests to execute. When tagging by test type (e.g., _micro_, _integration_,
_end-to-end_) and feature (e.g., *product*, *catalog*, *shipping*), the following tag
expressions can be useful.

[%header,cols="40,60"]
|===
| Tag Expression
| Selection

| +product+
| all tests for *product*

| +catalog \| shipping+
| all tests for *catalog* plus all tests for *shipping*

| +catalog & shipping+
| all tests for the intersection between *catalog* and *shipping*

| +product & !end-to-end+
| all tests for *product*, but not the _end-to-end_ tests

| +(micro \| integration) & (product \| shipping)+
| all _micro_ or _integration_ tests for *product* or *shipping*
|===

[[running-tests-capturing-output]]
=== Capturing Standard Output/Error

Since version 1.3, the JUnit Platform provides opt-in support for capturing output
printed to `System.out` and `System.err`. To enable it, simply set the
`junit.platform.output.capture.stdout` and/or `junit.platform.output.capture.stderr`
<<running-tests-config-params, configuration parameter>> to `true`. In addition, you may
configure the maximum number of buffered bytes to be used per executed test or container
using `junit.platform.output.capture.maxBuffer`.

If enabled, the JUnit Platform captures the corresponding output and publishes it as a
report entry using the `stdout` or `stderr` keys to all registered
`{TestExecutionListener}` instances immediately before reporting the test or container as
finished.

Please note that the captured output will only contain output emitted by the thread that
was used to execute a container or test. Any output by other threads will be omitted
because particularly when
<<writing-tests-parallel-execution, executing tests in parallel>> it would be impossible
to attribute it to a specific test or container.

WARNING: Capturing output is currently an _experimental_ feature. You're invited to give
it a try and provide feedback to the JUnit team so they can improve and eventually
<<api-evolution, promote>> this feature.
