<commit_before>[[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
testRuntime("org.junit.platform:junit-platform-launcher:{platform-version}")
testRuntime("org.junit.jupiter:junit-jupiter-engine:{jupiter-version}")
testRuntime("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-other]]
==== Other IDEs

At the time of this writing, there is no direct support for running tests on the JUnit
Platform within IDEs other than IntelliJ IDEA and Eclipse. However, the JUnit team
provides two intermediate solutions so that you can go ahead and try out JUnit 5 within
your IDE today. You can use the <<running-tests-console-launcher>> manually or execute
tests with a <<running-tests-junit-platform-runner,JUnit 4 based Runner>>.

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

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

Starting with https://docs.gradle.org/4.6/release-notes.html[version 4.6], Gradle provides
https://docs.gradle.org/current/userguide/java_plugin.html#using_junit5[native support]
for executing tests on the JUnit Platform. To enable it, you just need to add one line to
your `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.

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

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

The standard `test` tasks does currently not provide a dedicated DSL to set configuration
parameters to influence test discovery and execution. However, you can use system
properties instead.

[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 `testCompile` dependency
on the JUnit Jupiter API and a `testRuntime` dependency on the JUnit Jupiter `TestEngine`
implementation similar to the following.

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

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

[source,java,indent=0]
[subs=attributes+]
----
dependencies {
	testCompile("junit:junit:{junit4-version}")
	testRuntime("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 supplied _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

The JUnit team has developed a very basic provider for Maven Surefire that lets you run
JUnit 4 and JUnit Jupiter tests via `mvn test`. The `pom.xml` file in the
`{junit5-maven-consumer}` project demonstrates how to use it and can serve as a starting
point.

NOTE: Please use Surefire 2.21.0 with `junit-platform-surefire-provider`.

[source,xml,indent=0]
[subs=attributes+]
----
	...
	<build>
		<plugins>
			...
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>2.21.0</version>
				<dependencies>
					<dependency>
						<groupId>org.junit.platform</groupId>
						<artifactId>junit-platform-surefire-provider</artifactId>
						<version>{platform-version}</version>
					</dependency>
				</dependencies>
			</plugin>
		</plugins>
	</build>
	...
----

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

In order to have Maven Surefire run any tests at all, a `TestEngine` implementation must
be added to the runtime classpath.

To configure support for JUnit Jupiter based tests, configure a `test` dependency on the
JUnit Jupiter API, and add the JUnit Jupiter `TestEngine` implementation to the
dependencies of the `maven-surefire-plugin` similar to the following.

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

The JUnit Platform Surefire Provider can run JUnit 4 based tests as long as you configure
a `test` dependency on JUnit 4 and add the JUnit Vintage `TestEngine` implementation to
the dependencies of the `maven-surefire-plugin` similar to the following.

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

[[running-tests-build-maven-test-system-property]]
===== Running a Single Test Class

The JUnit Platform Surefire Provider supports the `test` JVM system property supported by
the Maven Surefire Plugin. For example, to run only test methods in the
`org.example.MyTest` test class you can execute `mvn -Dtest=org.example.MyTest test` from
the command line. For further details, consult the
https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html[Maven Surefire Plugin]
documentation.

[[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+`
- `+**/*TestCase.java+`

Note, however, that you can override this default behavior by configuring explicit
`include` and `exclude` rules in your `pom.xml` file. 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 either `groups` or `includeTags`.
- to exclude _tags_ or _tag expressions_, use either `excludedGroups` or `excludeTags`.

[source,xml,indent=0]
----
	...
	<build>
		<plugins>
			...
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>2.21.0</version>
				<configuration>
			        <properties>
			            <includeTags>acceptance | !feature-a</includeTags>
			            <excludeTags>integration, regression</excludeTags>
			        </properties>
			    </configuration>
				<dependencies>
					...
				</dependencies>
			</plugin>
		</plugins>
	</build>
	...
----

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

You can set configuration parameters to influence test discovery and execution by using
the `configurationParameters` property and providing key-value pairs in the Java
`Properties` file syntax.

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

[[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 central Maven 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. Otherwise the exit code is `0`.

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

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


[[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 Vintage). 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/JUnit4ClassDemo.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/JUnit4SuiteDemo.java[tags=user_guide]
----

The `JUnit4SuiteDemo` will discover and run all tests in the `example` package
and its subpackages. By default, it will only include test classes whose names match the
pattern `{standard-include-class-name-pattern}`.

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

[[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. 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>><commit_msg>Polish Gradle and Maven content in User Guide<commit_after>[[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
testRuntime("org.junit.platform:junit-platform-launcher:{platform-version}")
testRuntime("org.junit.jupiter:junit-jupiter-engine:{jupiter-version}")
testRuntime("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-other]]
==== Other IDEs

At the time of this writing, there is no direct support for running tests on the JUnit
Platform within IDEs other than IntelliJ IDEA and Eclipse. However, the JUnit team
provides two intermediate solutions so that you can go ahead and try out JUnit 5 within
your IDE today. You can use the <<running-tests-console-launcher>> manually or execute
tests with a <<running-tests-junit-platform-runner,JUnit 4 based Runner>>.

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

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

Starting with https://docs.gradle.org/4.6/release-notes.html[version 4.6], Gradle provides
https://docs.gradle.org/current/userguide/java_plugin.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.

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

[[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 `testCompile` dependency
on the JUnit Jupiter API and a `testRuntime` dependency on the JUnit Jupiter `TestEngine`
implementation similar to the following.

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

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

[source,java,indent=0]
[subs=attributes+]
----
dependencies {
	testCompile("junit:junit:{junit4-version}")
	testRuntime("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

The JUnit team has developed a very basic provider for Maven Surefire that lets you run
JUnit 4 and JUnit Jupiter tests via `mvn test`. The `pom.xml` file in the
`{junit5-maven-consumer}` project demonstrates how to use it and can serve as a starting
point.

NOTE: Please use Maven Surefire 2.21.0 with the `junit-platform-surefire-provider`.

[source,xml,indent=0]
[subs=attributes+]
----
	...
	<build>
		<plugins>
			...
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>2.21.0</version>
				<dependencies>
					<dependency>
						<groupId>org.junit.platform</groupId>
						<artifactId>junit-platform-surefire-provider</artifactId>
						<version>{platform-version}</version>
					</dependency>
				</dependencies>
			</plugin>
		</plugins>
	</build>
	...
----

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

In order to have Maven Surefire run any tests at all, a `TestEngine` implementation must
be added to the runtime classpath.

To configure support for JUnit Jupiter based tests, configure a `test` dependency on the
JUnit Jupiter API, and add the JUnit Jupiter `TestEngine` implementation to the
dependencies of the `maven-surefire-plugin` similar to the following.

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

The JUnit Platform Surefire Provider can run JUnit 4 based tests as long as you configure
a `test` dependency on JUnit 4 and add the JUnit Vintage `TestEngine` implementation to
the dependencies of the `maven-surefire-plugin` similar to the following.

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

[[running-tests-build-maven-test-system-property]]
===== Running a Single Test Class

The JUnit Platform Surefire Provider supports the `test` JVM system property supported by
the Maven Surefire Plugin. For example, to run only test methods in the
`org.example.MyTest` test class you can execute `mvn -Dtest=org.example.MyTest test` from
the command line. For further details, consult the
https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html[Maven Surefire Plugin]
documentation.

[[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+` _(supported since Surefire 2.20)_
- `+**/*TestCase.java+`

Note, however, that you can override this default behavior by configuring explicit
`include` and `exclude` rules in your `pom.xml` file. 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 either `groups` or `includeTags`.
- to exclude _tags_ or _tag expressions_, use either `excludedGroups` or `excludeTags`.

[source,xml,indent=0]
----
	...
	<build>
		<plugins>
			...
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>2.21.0</version>
				<configuration>
			        <properties>
			            <includeTags>acceptance | !feature-a</includeTags>
			            <excludeTags>integration, regression</excludeTags>
			        </properties>
			    </configuration>
				<dependencies>
					...
				</dependencies>
			</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]
----
	...
	<build>
		<plugins>
			...
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>2.21.0</version>
				<configuration>
					<properties>
						<configurationParameters>
							junit.jupiter.conditions.deactivate = *
							junit.jupiter.extensions.autodetection.enabled = true
							junit.jupiter.testinstance.lifecycle.default = per_class
						</configurationParameters>
					</properties>
				</configuration>
				<dependencies>
					...
				</dependencies>
			</plugin>
		</plugins>
	</build>
	...
----

[[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 central Maven 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. Otherwise the exit code is `0`.

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

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


[[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 Vintage). 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/JUnit4ClassDemo.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/JUnit4SuiteDemo.java[tags=user_guide]
----

The `JUnit4SuiteDemo` will discover and run all tests in the `example` package
and its subpackages. By default, it will only include test classes whose names match the
pattern `{standard-include-class-name-pattern}`.

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

[[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>>
{'fraction_non_alphanumeric': 0.11342073046317078, 'fraction_numerical': 0.006962864721485411, 'mean_word_length': 4.144187877197586, 'pattern_counts': {'":': 0, '<': 379, '<?xml version=': 0, '>': 379, 'https://': 20, 'lorem ipsum': 0, 'www.': 4, 'xml': 16}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5830165', 'n_tokens_mistral': 12531, 'n_tokens_neox': 11235, 'n_words': 3841}