Revise documentation on Maven support

Revise documentation on Maven support

 - Clarify that `junit-platform-surefire-provider` will be removed in
   Platform 1.4.
 - Remove `junit-platform-surefire-provider` from all samples.
 - Move the engine dependencies to the regular dependencies in all
   samples.

Resolves #1535.

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

[WARNING]
.The JUnit Platform Gradle Plugin has been discontinued
====
The very basic `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.
====

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

NOTE: The custom `junit-platform-surefire-provider`, which was originally developed by the JUnit team, has been deprecated and is scheduled to be removed in JUnit Platform 1.4. Please use the Maven Surefire's native support instead.

Starting with https://issues.apache.org/jira/browse/SUREFIRE-1330[version 2.22.0],
Maven Surefire provides
http://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 it 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 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 a `test` dependency on the
JUnit Jupiter API and the JUnit Jupiter `TestEngine` implementation.

[source,xml,indent=0]
[subs=attributes+]
----
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-surefire-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 can run JUnit 4 based tests alongside Jupiter tests as long as you
configure a `test` dependency 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>
		</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.

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

NOTE: The version of the `junitlauncher` task shipped in Ant 1.10.3 provides basic,
minimal support for launching the JUnit Platform. Additional enhancements (including
support for forking the tests in a separate JVM) will be available in subsequent releases
of Ant.

The `build.xml` file in the `{junit5-jupiter-starter-ant}` project demonstrates how to use
it 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 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. 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 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
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.

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

_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. Tagging by test type (e.g. _micro_, _integration_,
_end-to-end_) and feature (e.g. *foo*, *bar*, *baz*) the following tag expressions can be
useful.

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

| +foo+
| all tests for *foo*

| +bar \| baz+
| all tests for *bar* plus all tests for *baz*

| +bar & baz+
| all tests for the intersection between *bar* and *baz*

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

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

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

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

[WARNING]
.The JUnit Platform Gradle Plugin has been discontinued
====
The very basic `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.
====

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

NOTE: Starting with https://issues.apache.org/jira/browse/SUREFIRE-1330[version 2.22.0],
Maven Surefire provides
http://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 native support and
can serve as a starting point for configuring your Maven build.

The JUnit team has developed a basic provider for Maven Surefire that lets you run JUnit
4 and JUnit Jupiter tests via `mvn test` on versions of Maven Surefire prior to 2.22.0.
Due to the release of Surefire 2.22.0, the `junit-platform-surefire-provider` from the
JUnit team has been deprecated and will be discontinued in a subsequent release of the
JUnit Platform.

NOTE: Please use Maven Surefire {surefire-version} with the
`junit-platform-surefire-provider`.

[source,xml,indent=0]
[subs=attributes+]
----
	...
	<build>
		<plugins>
			...
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</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>{surefire-version}</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>{surefire-version}</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+`
- `+**/*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.

[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 either `groups` or `includeTags`.
- to exclude _tags_ or _tag expressions_, use either `excludedGroups` or `excludeTags`.

[source,xml,indent=0]
[subs=attributes+]
----
	...
	<build>
		<plugins>
			...
			<plugin>
				<artifactId>maven-surefire-plugin</artifactId>
				<version>{surefire-version}</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]
[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>
				<dependencies>
					...
				</dependencies>
			</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.

NOTE: The version of the `junitlauncher` task shipped in Ant 1.10.3 provides basic,
minimal support for launching the JUnit Platform. Additional enhancements (including
support for forking the tests in a separate JVM) will be available in subsequent releases
of Ant.

The `build.xml` file in the `{junit5-jupiter-starter-ant}` project demonstrates how to use
it 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 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. 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 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
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.

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

_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. Tagging by test type (e.g. _micro_, _integration_,
_end-to-end_) and feature (e.g. *foo*, *bar*, *baz*) the following tag expressions can be
useful.

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

| +foo+
| all tests for *foo*

| +bar \| baz+
| all tests for *bar* plus all tests for *baz*

| +bar & baz+
| all tests for the intersection between *bar* and *baz*

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

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

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


updated changelog

updated changelog

= Asciidoctor IntelliJ Plugin Changelog

== About

This document provides a high-level view of the changes introduced by release.

[[releasenotes]]
== Release notes

=== 0.29.x (work in progress)

- improve handling of emails and links in editor (#307)

=== 0.28.25

- security review for in-browser preview, adding mac to prevent browser to retrieve arbitrary file, hiding referrer from externally retrieved resources (#303)

=== 0.28.24 (preview, available from Github releases)

- support undo for paste-image and send out notifications to add files to VCS (#298)
- fix rendering of images in flicker-free fast preview (#241)
- prevent NPE when opening AsciiDoc documents or fragments in browser (#303)
- inspection to convert Markdown-style horizontal rules to AsciiDoc-style horizontal rules (thanks to @bbrenne) (#272, #302)

=== 0.28.23 (preview, available from Github releases)

- Paste image from clipboard (thanks to @bbrenne) (#298, #300)

=== 0.28.22

- Wrong test name in gutter when running tests, BrowserUrlProvider eagerly works on all files (#301)

=== 0.28.21

- fixing autocomplete for link: when brackets already provided
- avoid flickering Math preview by replacing contents in Preview via JavaScript (#241)

=== 0.28.20

- Linking to Wiki page if JavaFX initialization is stuck (#299)

=== 0.28.19

- prevent "`Initializing...`" message in preview of empty file

=== 0.28.18 (preview, available from Github releases)

- detecting a stuck JavaFX initialization (#299)

=== 0.28.17 (preview, available from Github releases)

- tuning state resetting for lexer (#289)

=== 0.28.16 (preview, available from Github releases)

- adding code style settings for reformat (#289)
- rework inline macro for false positives (#275)
- ifdef/ifndef/endif body references attributes in (#275)
- reset formatting after a blank line (#289)
- navigate to auto-generated IDs of sections

=== 0.28.15 (preview, available from Github releases)

- respect imagesdir when resolving image paths in source file (#275)
- resolve attribute names in macro definition (#275)
- auto-completion of files should include ".." (#253)

=== 0.28.14 (preview, available from Github releases)

- lexer and highlighting support blocks with unbalanced or no delimiters (#289)

=== 0.28.13 (preview, available from Github releases)

- lexer and highlighting support several new tokens (callouts, admonitions, markdown style listings, definition lists) (#289)
- reformat supports break-after-end-of-sentence, but still experimental (#289)

=== 0.28.12 (preview, available from Github releases)

- rework zoom for touchpads (#295)
- added setting to disable error/warning highlighting in editor (#296)

=== 0.28.11 (preview, available from Github releases)

- inject absolute location of .asciidoctorconfig file (thanks to @rdmueller) (#280)
- support for '.adoc' extension of .asciidoctorconfig file (thanks to @rdmueller) (#293, #294)
- new table size selector using the mouse (thanks to @bbrenne) (#92, #290)
- create tables from clipboard and converting CSV/TSV format to AsciiDoc (thanks to @bbrenne) (#92, #290)
- better zoom support for touchpads, adding min/max zoom level (#295)

=== 0.28.10 (preview, available from Github releases)

- inlining and extracting of includes (#271)

=== 0.28.9 (preview, available from Github releases)

- experimental support reformatting of AsciiDoc sources, needs to be enabled in the settings (#289)
- "`Open in Browser`" now opens the contents of the preview in the selected browser including rendered diagrams (#82)

=== 0.28.8 (preview, available from Github releases)

- investigating problem that parts of the UI are not refreshing (#288)

=== 0.28.7

- Save image context menu now showing up on macOS (thanks to @wimdeblauwe) (#283)

=== 0.28.6

- fixing NPE introduced when detecting potentially blurry preview (#284)

=== 0.28.5 (preview, available from Github releases)

- support zoom in preview window (thanks to @ianflett) (#199, #279)
- save generated images from preview (thanks to @bbrenne) (#245, #278)

=== 0.28.4 (preview, available from Github releases)

- autocompletion for attributes and attribute references (`:attr:` and `\{attr}`) (thanks to @bbrenne) (#277)
- renaming and find-usage for attribute names (#243)
- upgrade to AsciidoctorJ 2.1.0 and Asciidoctor 2.0.10
- statement completion adds newline if at end of file (#276)
- listing and other delimiters recognized at end of file (#276)

=== 0.28.3

- brace matching for attribute start/end (`:attr:` and `\{attr}`)
- syntax highlighting for enumerations (`.`)
- fixing "`Edit Fragment...`" for listings (#276)

=== 0.28.2

- fixed parsing for old-style headers (#274)

=== 0.28.1 (preview, available from Github releases)

- new automated release mechanism, also EAP plugin repository

=== 0.26.20 (preview, available from Github releases)

- link to Wiki how to fix blurry preview (#213)
- monospace-bold preview now working (#193)

=== 0.26.19 (preview, available from Github releases)

- tuning parsing and documentation (#267)
- new inspection to shorten page break (`<<<`) where possible
- `\link:file#id[]` now with navigation and autocomplete (thanks to @bbrenne) (#273)

=== 0.26.18 (preview, available from Github releases)

- resolve the last reference in structure view as this will be the file; the others are the subdirectories (#267)
- refactoring or shortened descriptions; now in sync for structure view and breadcrumbs (#267)
- allow browser to cache static content to avoid flickering (#267)
- allow more block types, supporting nested blocks, parsing content within blocks (#267)
- rework folding to show first significant line in block (#267)

=== 0.26.17 (preview, available from Github releases)

- support escaping with backslash (`\`) in editor, avoiding highlighting
- move to released markdown-to-asciidoc version 1.1 to use proper dependency management (#268)
- support spell checking on more elements including quotes, examples and comments (#269)
- fixing autocomplete for file names on `include::[]` within blocks

=== 0.26.16 (preview, available from Github releases)

- show includes and images in structure view, adding icon set for breadcrumbs and structure view, tuning contents (#267)

=== 0.26.15

- fixing equals check for disabled injected languages (#266)

=== 0.26.14

- fixing NullPointerException in settings processing (#266)
- supporting pass-through inline content

=== 0.26.13

- update to asciidoctorj-diagram:1.5.18
- breadcrumb support in editor

=== 0.26.12 (preview, available from Github releases)

- supporting blanks in block attributes (#255)

=== 0.26.11 (preview, available from Github releases)

- adding support for GRAPHVIZ_DOT environment variable (#261)
- adding support for statement completion (ctrl-shift-enter) (#263)
- language injection can now is now enabled by default and can be disabled for specific languages, and will be disabled when the block has an `include::[]` (#255)
- includes are now parsed and highlighted inside code blocks (#255)

=== 0.26.10 (preview, available from Github releases)

- Experimental highlighting in code blocks (#255, #262)

=== 0.26.9 (preview, available from Github releases)

- upgrading gradle and JetBrains plugin; now use `gradlew runIde` to start the plugin in development mode
- allow user to switch left/right and upper/lower in split view (#136)
- add syntax highlighter to support `\link:file[]` (thanks to @bbrenne) (#259)
- add syntax highlighter to support attribute:value and {attribute reference} (thanks to @bbrenne) (#260)

=== 0.26.8 (preview, available from Github releases)

- default file encoding for JRuby now UTF-8 if set file encoding is not supported by JRuby (#174)

=== 0.26.7

- fixing error in tree structure; improving test capabilities for parsing (#174)

=== 0.26.6 (preview, available from Github releases)

- improved brace matcher
- ensure that block IDs are part of next section when folding (#174)

=== 0.26.5 (preview, available from Github releases)

- decouple read action from event thread to avoid error from IDE (#204)
- highlighting for lexical quotes
- parsing referenced file from reference (#204)

=== 0.26.4 (preview, available from Github releases)

- Support for relative path links in preview (#256)

=== 0.26.3 (preview, available from Github releases)

- allow folding of sections and blocks (#174)

=== 0.26.2 (preview, available from Github releases)

- allow horizontal split view via settings (#136)

=== 0.26.1 (preview, available from Github releases)

- adding color settings for syntax highlighting (#254)

=== 0.26.0 (preview, available from Github releases)

- support for anchors, block ids and references including linking and refactoring (#252)

=== 0.25.14

- making linking of documents work for standard includes (#204)
- improved formatting when blank lines are edited, also handling spaces at the end of a line (#248)

=== 0.25.13

- support partitial parsing in lexer to avoid flipping formatting in IntelliJ (#248)

=== 0.25.12 (preview, available from Github releases)

- adding additional rules for constrained formatting (#248)

=== 0.25.11

- moving from jruby-complete to jruby dependency like AsciidoctorJ did for 2.0 (#250)

=== 0.25.10 (preview, available from Github releases)

- improved syntax highlighting for block IDs and references, suppressing message "possible invalid reference" (#249)
- show error message why preview wasn't rendered in preview (#251)

=== 0.25.9

- adding quote handler (#242)
- Tuning highlighting for mono and bullet lists (#244)
- Activating brace highlighting for mono/italic/bold (#244)

=== 0.25.8 (preview, available from Github releases)

- Tuning highlighting italic/bold/mono, adding brace matcher in text (#244)

=== 0.25.7 (preview, available from Github releases)

- Updating to AsciidoctorJ v2.0.0 that includes Asciidoctor 2.0.8
- adding highlighting for italic/bold/mono (#244)
- adding brace matcher for attributes

=== 0.25.6 (preview, available from Github releases)

- Updating to AsciidoctorJ v2.0.0-RC.2 that includes Asciidoctor 2.0.6
- Improved parsing of warnings and errors created by Asciidoctor

=== 0.25.5 (preview, available from Github releases)

- Addding error highlight in tree view

=== 0.25.4 (preview, available from Github releases)

- restart annotation processing for current file once it gets focused or settings change (#225)

=== 0.25.3 (preview, available from Github releases)

- improve offset calculation for .asciidoctorconfig files (#225)

=== 0.25.2 (preview, available from Github releases)

- annotate the file in the editor instead of logging to console for asciidoctor messages (#225)

=== 0.25.1 (preview, available from Github releases)

- Fixing preview line calculation when using .asciidoctorconfig-files
- Updating to AsciidoctorJ v2.0.0-RC.1 that includes Asciidoctor 2.0.2

=== 0.25.0 (preview, available from Github releases)

- Updating to AsciidoctorJ v1.7.0-RC.1 that includes Asciidoctor 2.0.1 and Asciidoctor Diagram 1.5.16

=== 0.24.4

- Fixing preview line calculation when using .asciidoctorconfig-files

=== 0.24.3

- Filter out problematic pass-through JavaScript with Twitter being the first candidate (#235)

=== 0.24.2 (preview, available from Github releases)

- Support JDK11 as of IntelliJ 2019.1 EAP (#238)

=== 0.24.1

- Upgrade to AsciidoctorJ 1.6.2 and JRuby 9.2.6.0 (it's still backed by Asciidoctor 1.5.8)
- Upgrade to asciidoctor diagram 1.5.12
- Additional logging to analyze errors (#236)

=== 0.24.0

- Upgrade to AsciidoctorJ 1.6.1 and JRuby 9.2.5.0 (it's still backed by Asciidoctor 1.5.8)
- Upgrade to asciidoctor diagram 1.5.11
- Updated parser for old style multiline headings  to be more specific (#233)
- Added description for old style heading inspection (#233)

=== 0.23.2

- Resource cleanup for Asciidoctor Ruby Extensions (#220)

=== 0.23.1 (preview, available from Github releases)

- Updated file icon with less intrusive icon, also introducing SVG for icons (#230)
- Editor notification to switch to JetBrains 64bit JDK (#189)
- Tuning support for Asciidoctor Ruby Extensions (#220)

=== 0.23.0 (preview, available from Github releases)

- EXPERIMENTAL: Support Asciidoctor Ruby Extensions when placed in _.asciidoctor/lib_ (#220)

=== 0.22.0

- Update to AsciidoctorJ 1.5.8.1
- Workaround for incompatible plugins (#226)
- Toggle softwraps only available in context menu of AsciiDoc documents (#227)
- Recognize list continuations plus block instead of marking them as old style headings (#228)
- EXPERIMENTAL: supporting _.asciidoctorconfig_ configuration files

=== 0.21.4

- Add official asciidoctor logo (#219)
- Add soft wrap to tool bar (#221)
- Editor Toolbar show status of toggles
- Update to Asciidoctor Diagram 1.5.10 (#215)

=== 0.21.3

- upgrade to MathJAX 2.4.7 (as bundled in AsciidoctorJ 1.5.7)

=== 0.21.2

- Regression: show title of document again (#217)

=== 0.21.1

- allow attributes to be pre-defined in plugin settings (#216)

=== 0.21.0 (preview, available from Github releases)

- Update to AsciidoctorJ 1.5.7 and Asciidoctor Diagram 1.5.9
- Treat "line must be non negative" only as a warning (#212)

=== 0.20.6

- Display all PlantUML graphics as PNG for preview (#170)

=== 0.20.5

- Adding hiDPI support for JavaFX preview (#125)

=== 0.20.4

- Requiring 2017.1 as minimum for this plugin (#207)

=== 0.20.3 (preview, available from Github releases)

- Avoiding deadlock on JavaFX initialization (#207)
- Requiring 2017.2 as minimum for this plugin

=== 0.20.2

- Dejavu fonts now display chinese characters within tables (#203)

=== 0.20.1

- Upgrading to asciidoctorj-diagram 1.5.8
- Dejavu fonts now display chinese characters (#203)

=== 0.20.0

- Add MathJax support in JavaFX preview #201
- JavaFX preview is now the default for new installations of the plugin
- Include DejaVu fonts for improved and consistent preview #184

=== 0.19.2

- Fix NullPointerExceptions when used with IntelliJ Language Injection and Fragment Editor #194

=== 0.19.1

- Support inspections to convert markdown and old style AsciiDoc headings to modern AsciiDoc headings #185
- JRuby runtime updated to 9.1.8.0 to work with recent JDK versions (still, internal JetBrains JRE is the only supported version) #187

=== 0.19.0

- Support Icon fonts (thanks to @matthiasbalke) / #182
- Update to asciidoctorj-1.5.6 (aka asciidoctor-1.5.6.1) and asciidoctorj-diagram-1.5.4.1
- Support "search everywhere" (double Shift) and "goto by name - Symbol..." (Ctrl+Shift+Alt+N) for all AsciiDoc section headings - just enter a part of the heading
- Support Markdown style sections (starting with '#') in syntax highlighting

=== 0.18.2 (preview, available from Github releases)

- Headings in Darcula theme preview are now light grey for better readability

=== 0.18.1

- Improved handling for non-printable characters in syntax highlighting

=== 0.18.0 (preview, available from Github releases)

- Update to asciidoctor 1.5.5/asciidoctor-diagram 1.5.4
- Capture Asciidoctor messages on stdout/stderr and write them to IDE notifications
- Close files when images are shown in preview
- Set focus in editor when re-opening file
- Fix "line must be non negative" error when clicking on preview

=== 0.17.3

- Make click-on-link-to-open and click-on-preview-to-set-cursor in JavaFX preview compatible with Java 8 u111+
- Formatting actions from the toolbar should not throw exceptions when triggered at the beginning or end of the document

=== 0.17.2

- Plugin is now build using the https://gradle.org/[Gradle] and https://github.com/JetBrains/gradle-intellij-plugin[gradle-intellij-plugin]
This should make contributing and releasing easier. Thanks Jiawen Geng!
- Asciidoctor's temporary files are now created in a temporary folder per opened document. Thanks @agorges!

=== 0.17.1 (preview, available from Github releases)

- Improved handling of trailing spaces in syntax highlighting.
- Fixed code/preview sync for nested HTML (i.e. NOTE)

=== 0.17.0 (preview, available from Github releases)

- Updated block parsing to support two styles of headings.
- Block starts and ends are need to be aligned in length and shape when parsed.

=== 0.16.4

- Improved darcula support for JavaFX. More block types are using proper dark background and light text colors.

=== 0.16.3

- Theme in preview can be switched from light to darcula independent of IDE theme

=== 0.16.2

- Handling of Linux and MacOS file names for image preview in JavaFX

=== 0.16.1

- Added darcula theme for JavaFX preview
- Clicking on JavaFX preview will set cursor position in editor (thanks to @kastork for the idea)

=== 0.15.4

- setScene now called from FxThread instead of AWT thread to avoid blocking GUI on MacOS

=== 0.15.3

- Initialization message appears only during initialization
- No error message if user switches to a setup where JavaFX preview is no longer available.

=== 0.15.2 (preview, available from Github releases)

- fixed detection of Mac 64 JVM to be able to activate JavaFX preview
- click-on-url for JavaFX improved, when slow-loading external images are referenced

=== 0.15.1 (preview, available from Github releases)

- revised constrained/unconstrained detection
- Fix problem in syntax highlighting leading to PSI Parser Exceptions
- refreshing images on JavaFX only if their content has changed to save memory consumption
- Limiting JavaFX preview to 64bit platforms due to problems especially with Windows OpenJDK 32bit (as default on Windows).

=== 0.15.0 (preview, available from Github releases)

- correct usage of constrained/unconstrained AsciiDoc formatting
- JavaFX Preview will automatically scroll to the cursor position of the editor
- JavaFX preview will automatically open links in the systems's default browser
- Caching rendering instances of Asciidoctor for better performance

IntelliJ 15 (including AppCode 3.3, CLion 1.2, DataGrip 1.0, PhpStorm 10, PyCharm 5, RubyMine 8, WebStorm 11) is the new minimum version required for this release.

= Asciidoctor IntelliJ Plugin Changelog

== About

This document provides a high-level view of the changes introduced by release.

[[releasenotes]]
== Release notes

=== 0.28.26 (work in progress)

- improve handling of emails and links in editor (#307)

=== 0.28.25

- security review for in-browser preview, adding mac to prevent browser to retrieve arbitrary file, hiding referrer from externally retrieved resources (#303)

=== 0.28.24 (preview, available from Github releases)

- support undo for paste-image and send out notifications to add files to VCS (#298)
- fix rendering of images in flicker-free fast preview (#241)
- prevent NPE when opening AsciiDoc documents or fragments in browser (#303)
- inspection to convert Markdown-style horizontal rules to AsciiDoc-style horizontal rules (thanks to @bbrenne) (#272, #302)

=== 0.28.23 (preview, available from Github releases)

- Paste image from clipboard (thanks to @bbrenne) (#298, #300)

=== 0.28.22

- Wrong test name in gutter when running tests, BrowserUrlProvider eagerly works on all files (#301)

=== 0.28.21

- fixing autocomplete for link: when brackets already provided
- avoid flickering Math preview by replacing contents in Preview via JavaScript (#241)

=== 0.28.20

- Linking to Wiki page if JavaFX initialization is stuck (#299)

=== 0.28.19

- prevent "`Initializing...`" message in preview of empty file

=== 0.28.18 (preview, available from Github releases)

- detecting a stuck JavaFX initialization (#299)

=== 0.28.17 (preview, available from Github releases)

- tuning state resetting for lexer (#289)

=== 0.28.16 (preview, available from Github releases)

- adding code style settings for reformat (#289)
- rework inline macro for false positives (#275)
- ifdef/ifndef/endif body references attributes in (#275)
- reset formatting after a blank line (#289)
- navigate to auto-generated IDs of sections

=== 0.28.15 (preview, available from Github releases)

- respect imagesdir when resolving image paths in source file (#275)
- resolve attribute names in macro definition (#275)
- auto-completion of files should include ".." (#253)

=== 0.28.14 (preview, available from Github releases)

- lexer and highlighting support blocks with unbalanced or no delimiters (#289)

=== 0.28.13 (preview, available from Github releases)

- lexer and highlighting support several new tokens (callouts, admonitions, markdown style listings, definition lists) (#289)
- reformat supports break-after-end-of-sentence, but still experimental (#289)

=== 0.28.12 (preview, available from Github releases)

- rework zoom for touchpads (#295)
- added setting to disable error/warning highlighting in editor (#296)

=== 0.28.11 (preview, available from Github releases)

- inject absolute location of .asciidoctorconfig file (thanks to @rdmueller) (#280)
- support for '.adoc' extension of .asciidoctorconfig file (thanks to @rdmueller) (#293, #294)
- new table size selector using the mouse (thanks to @bbrenne) (#92, #290)
- create tables from clipboard and converting CSV/TSV format to AsciiDoc (thanks to @bbrenne) (#92, #290)
- better zoom support for touchpads, adding min/max zoom level (#295)

=== 0.28.10 (preview, available from Github releases)

- inlining and extracting of includes (#271)

=== 0.28.9 (preview, available from Github releases)

- experimental support reformatting of AsciiDoc sources, needs to be enabled in the settings (#289)
- "`Open in Browser`" now opens the contents of the preview in the selected browser including rendered diagrams (#82)

=== 0.28.8 (preview, available from Github releases)

- investigating problem that parts of the UI are not refreshing (#288)

=== 0.28.7

- Save image context menu now showing up on macOS (thanks to @wimdeblauwe) (#283)

=== 0.28.6

- fixing NPE introduced when detecting potentially blurry preview (#284)

=== 0.28.5 (preview, available from Github releases)

- support zoom in preview window (thanks to @ianflett) (#199, #279)
- save generated images from preview (thanks to @bbrenne) (#245, #278)

=== 0.28.4 (preview, available from Github releases)

- autocompletion for attributes and attribute references (`:attr:` and `\{attr}`) (thanks to @bbrenne) (#277)
- renaming and find-usage for attribute names (#243)
- upgrade to AsciidoctorJ 2.1.0 and Asciidoctor 2.0.10
- statement completion adds newline if at end of file (#276)
- listing and other delimiters recognized at end of file (#276)

=== 0.28.3

- brace matching for attribute start/end (`:attr:` and `\{attr}`)
- syntax highlighting for enumerations (`.`)
- fixing "`Edit Fragment...`" for listings (#276)

=== 0.28.2

- fixed parsing for old-style headers (#274)

=== 0.28.1 (preview, available from Github releases)

- new automated release mechanism, also EAP plugin repository

=== 0.26.20 (preview, available from Github releases)

- link to Wiki how to fix blurry preview (#213)
- monospace-bold preview now working (#193)

=== 0.26.19 (preview, available from Github releases)

- tuning parsing and documentation (#267)
- new inspection to shorten page break (`<<<`) where possible
- `\link:file#id[]` now with navigation and autocomplete (thanks to @bbrenne) (#273)

=== 0.26.18 (preview, available from Github releases)

- resolve the last reference in structure view as this will be the file; the others are the subdirectories (#267)
- refactoring or shortened descriptions; now in sync for structure view and breadcrumbs (#267)
- allow browser to cache static content to avoid flickering (#267)
- allow more block types, supporting nested blocks, parsing content within blocks (#267)
- rework folding to show first significant line in block (#267)

=== 0.26.17 (preview, available from Github releases)

- support escaping with backslash (`\`) in editor, avoiding highlighting
- move to released markdown-to-asciidoc version 1.1 to use proper dependency management (#268)
- support spell checking on more elements including quotes, examples and comments (#269)
- fixing autocomplete for file names on `include::[]` within blocks

=== 0.26.16 (preview, available from Github releases)

- show includes and images in structure view, adding icon set for breadcrumbs and structure view, tuning contents (#267)

=== 0.26.15

- fixing equals check for disabled injected languages (#266)

=== 0.26.14

- fixing NullPointerException in settings processing (#266)
- supporting pass-through inline content

=== 0.26.13

- update to asciidoctorj-diagram:1.5.18
- breadcrumb support in editor

=== 0.26.12 (preview, available from Github releases)

- supporting blanks in block attributes (#255)

=== 0.26.11 (preview, available from Github releases)

- adding support for GRAPHVIZ_DOT environment variable (#261)
- adding support for statement completion (ctrl-shift-enter) (#263)
- language injection can now is now enabled by default and can be disabled for specific languages, and will be disabled when the block has an `include::[]` (#255)
- includes are now parsed and highlighted inside code blocks (#255)

=== 0.26.10 (preview, available from Github releases)

- Experimental highlighting in code blocks (#255, #262)

=== 0.26.9 (preview, available from Github releases)

- upgrading gradle and JetBrains plugin; now use `gradlew runIde` to start the plugin in development mode
- allow user to switch left/right and upper/lower in split view (#136)
- add syntax highlighter to support `\link:file[]` (thanks to @bbrenne) (#259)
- add syntax highlighter to support attribute:value and {attribute reference} (thanks to @bbrenne) (#260)

=== 0.26.8 (preview, available from Github releases)

- default file encoding for JRuby now UTF-8 if set file encoding is not supported by JRuby (#174)

=== 0.26.7

- fixing error in tree structure; improving test capabilities for parsing (#174)

=== 0.26.6 (preview, available from Github releases)

- improved brace matcher
- ensure that block IDs are part of next section when folding (#174)

=== 0.26.5 (preview, available from Github releases)

- decouple read action from event thread to avoid error from IDE (#204)
- highlighting for lexical quotes
- parsing referenced file from reference (#204)

=== 0.26.4 (preview, available from Github releases)

- Support for relative path links in preview (#256)

=== 0.26.3 (preview, available from Github releases)

- allow folding of sections and blocks (#174)

=== 0.26.2 (preview, available from Github releases)

- allow horizontal split view via settings (#136)

=== 0.26.1 (preview, available from Github releases)

- adding color settings for syntax highlighting (#254)

=== 0.26.0 (preview, available from Github releases)

- support for anchors, block ids and references including linking and refactoring (#252)

=== 0.25.14

- making linking of documents work for standard includes (#204)
- improved formatting when blank lines are edited, also handling spaces at the end of a line (#248)

=== 0.25.13

- support partitial parsing in lexer to avoid flipping formatting in IntelliJ (#248)

=== 0.25.12 (preview, available from Github releases)

- adding additional rules for constrained formatting (#248)

=== 0.25.11

- moving from jruby-complete to jruby dependency like AsciidoctorJ did for 2.0 (#250)

=== 0.25.10 (preview, available from Github releases)

- improved syntax highlighting for block IDs and references, suppressing message "possible invalid reference" (#249)
- show error message why preview wasn't rendered in preview (#251)

=== 0.25.9

- adding quote handler (#242)
- Tuning highlighting for mono and bullet lists (#244)
- Activating brace highlighting for mono/italic/bold (#244)

=== 0.25.8 (preview, available from Github releases)

- Tuning highlighting italic/bold/mono, adding brace matcher in text (#244)

=== 0.25.7 (preview, available from Github releases)

- Updating to AsciidoctorJ v2.0.0 that includes Asciidoctor 2.0.8
- adding highlighting for italic/bold/mono (#244)
- adding brace matcher for attributes

=== 0.25.6 (preview, available from Github releases)

- Updating to AsciidoctorJ v2.0.0-RC.2 that includes Asciidoctor 2.0.6
- Improved parsing of warnings and errors created by Asciidoctor

=== 0.25.5 (preview, available from Github releases)

- Addding error highlight in tree view

=== 0.25.4 (preview, available from Github releases)

- restart annotation processing for current file once it gets focused or settings change (#225)

=== 0.25.3 (preview, available from Github releases)

- improve offset calculation for .asciidoctorconfig files (#225)

=== 0.25.2 (preview, available from Github releases)

- annotate the file in the editor instead of logging to console for asciidoctor messages (#225)

=== 0.25.1 (preview, available from Github releases)

- Fixing preview line calculation when using .asciidoctorconfig-files
- Updating to AsciidoctorJ v2.0.0-RC.1 that includes Asciidoctor 2.0.2

=== 0.25.0 (preview, available from Github releases)

- Updating to AsciidoctorJ v1.7.0-RC.1 that includes Asciidoctor 2.0.1 and Asciidoctor Diagram 1.5.16

=== 0.24.4

- Fixing preview line calculation when using .asciidoctorconfig-files

=== 0.24.3

- Filter out problematic pass-through JavaScript with Twitter being the first candidate (#235)

=== 0.24.2 (preview, available from Github releases)

- Support JDK11 as of IntelliJ 2019.1 EAP (#238)

=== 0.24.1

- Upgrade to AsciidoctorJ 1.6.2 and JRuby 9.2.6.0 (it's still backed by Asciidoctor 1.5.8)
- Upgrade to asciidoctor diagram 1.5.12
- Additional logging to analyze errors (#236)

=== 0.24.0

- Upgrade to AsciidoctorJ 1.6.1 and JRuby 9.2.5.0 (it's still backed by Asciidoctor 1.5.8)
- Upgrade to asciidoctor diagram 1.5.11
- Updated parser for old style multiline headings  to be more specific (#233)
- Added description for old style heading inspection (#233)

=== 0.23.2

- Resource cleanup for Asciidoctor Ruby Extensions (#220)

=== 0.23.1 (preview, available from Github releases)

- Updated file icon with less intrusive icon, also introducing SVG for icons (#230)
- Editor notification to switch to JetBrains 64bit JDK (#189)
- Tuning support for Asciidoctor Ruby Extensions (#220)

=== 0.23.0 (preview, available from Github releases)

- EXPERIMENTAL: Support Asciidoctor Ruby Extensions when placed in _.asciidoctor/lib_ (#220)

=== 0.22.0

- Update to AsciidoctorJ 1.5.8.1
- Workaround for incompatible plugins (#226)
- Toggle softwraps only available in context menu of AsciiDoc documents (#227)
- Recognize list continuations plus block instead of marking them as old style headings (#228)
- EXPERIMENTAL: supporting _.asciidoctorconfig_ configuration files

=== 0.21.4

- Add official asciidoctor logo (#219)
- Add soft wrap to tool bar (#221)
- Editor Toolbar show status of toggles
- Update to Asciidoctor Diagram 1.5.10 (#215)

=== 0.21.3

- upgrade to MathJAX 2.4.7 (as bundled in AsciidoctorJ 1.5.7)

=== 0.21.2

- Regression: show title of document again (#217)

=== 0.21.1

- allow attributes to be pre-defined in plugin settings (#216)

=== 0.21.0 (preview, available from Github releases)

- Update to AsciidoctorJ 1.5.7 and Asciidoctor Diagram 1.5.9
- Treat "line must be non negative" only as a warning (#212)

=== 0.20.6

- Display all PlantUML graphics as PNG for preview (#170)

=== 0.20.5

- Adding hiDPI support for JavaFX preview (#125)

=== 0.20.4

- Requiring 2017.1 as minimum for this plugin (#207)

=== 0.20.3 (preview, available from Github releases)

- Avoiding deadlock on JavaFX initialization (#207)
- Requiring 2017.2 as minimum for this plugin

=== 0.20.2

- Dejavu fonts now display chinese characters within tables (#203)

=== 0.20.1

- Upgrading to asciidoctorj-diagram 1.5.8
- Dejavu fonts now display chinese characters (#203)

=== 0.20.0

- Add MathJax support in JavaFX preview #201
- JavaFX preview is now the default for new installations of the plugin
- Include DejaVu fonts for improved and consistent preview #184

=== 0.19.2

- Fix NullPointerExceptions when used with IntelliJ Language Injection and Fragment Editor #194

=== 0.19.1

- Support inspections to convert markdown and old style AsciiDoc headings to modern AsciiDoc headings #185
- JRuby runtime updated to 9.1.8.0 to work with recent JDK versions (still, internal JetBrains JRE is the only supported version) #187

=== 0.19.0

- Support Icon fonts (thanks to @matthiasbalke) / #182
- Update to asciidoctorj-1.5.6 (aka asciidoctor-1.5.6.1) and asciidoctorj-diagram-1.5.4.1
- Support "search everywhere" (double Shift) and "goto by name - Symbol..." (Ctrl+Shift+Alt+N) for all AsciiDoc section headings - just enter a part of the heading
- Support Markdown style sections (starting with '#') in syntax highlighting

=== 0.18.2 (preview, available from Github releases)

- Headings in Darcula theme preview are now light grey for better readability

=== 0.18.1

- Improved handling for non-printable characters in syntax highlighting

=== 0.18.0 (preview, available from Github releases)

- Update to asciidoctor 1.5.5/asciidoctor-diagram 1.5.4
- Capture Asciidoctor messages on stdout/stderr and write them to IDE notifications
- Close files when images are shown in preview
- Set focus in editor when re-opening file
- Fix "line must be non negative" error when clicking on preview

=== 0.17.3

- Make click-on-link-to-open and click-on-preview-to-set-cursor in JavaFX preview compatible with Java 8 u111+
- Formatting actions from the toolbar should not throw exceptions when triggered at the beginning or end of the document

=== 0.17.2

- Plugin is now build using the https://gradle.org/[Gradle] and https://github.com/JetBrains/gradle-intellij-plugin[gradle-intellij-plugin]
This should make contributing and releasing easier. Thanks Jiawen Geng!
- Asciidoctor's temporary files are now created in a temporary folder per opened document. Thanks @agorges!

=== 0.17.1 (preview, available from Github releases)

- Improved handling of trailing spaces in syntax highlighting.
- Fixed code/preview sync for nested HTML (i.e. NOTE)

=== 0.17.0 (preview, available from Github releases)

- Updated block parsing to support two styles of headings.
- Block starts and ends are need to be aligned in length and shape when parsed.

=== 0.16.4

- Improved darcula support for JavaFX. More block types are using proper dark background and light text colors.

=== 0.16.3

- Theme in preview can be switched from light to darcula independent of IDE theme

=== 0.16.2

- Handling of Linux and MacOS file names for image preview in JavaFX

=== 0.16.1

- Added darcula theme for JavaFX preview
- Clicking on JavaFX preview will set cursor position in editor (thanks to @kastork for the idea)

=== 0.15.4

- setScene now called from FxThread instead of AWT thread to avoid blocking GUI on MacOS

=== 0.15.3

- Initialization message appears only during initialization
- No error message if user switches to a setup where JavaFX preview is no longer available.

=== 0.15.2 (preview, available from Github releases)

- fixed detection of Mac 64 JVM to be able to activate JavaFX preview
- click-on-url for JavaFX improved, when slow-loading external images are referenced

=== 0.15.1 (preview, available from Github releases)

- revised constrained/unconstrained detection
- Fix problem in syntax highlighting leading to PSI Parser Exceptions
- refreshing images on JavaFX only if their content has changed to save memory consumption
- Limiting JavaFX preview to 64bit platforms due to problems especially with Windows OpenJDK 32bit (as default on Windows).

=== 0.15.0 (preview, available from Github releases)

- correct usage of constrained/unconstrained AsciiDoc formatting
- JavaFX Preview will automatically scroll to the cursor position of the editor
- JavaFX preview will automatically open links in the systems's default browser
- Caching rendering instances of Asciidoctor for better performance

IntelliJ 15 (including AppCode 3.3, CLion 1.2, DataGrip 1.0, PhpStorm 10, PyCharm 5, RubyMine 8, WebStorm 11) is the new minimum version required for this release.