= JUnit Platform Suite Engine

The Suite Engine supports the declarative selection and execution of tests from _any_ test
engine on the JUnit Platform using the xref:advanced-topics/launcher-api.adoc[].

image::junit-platform-suite-engine-diagram.svg[role=text-center]

[[setup]]
== Setup

In addition to the `junit-platform-suite-api` and `junit-platform-suite-engine` artifacts,
you need _at least one_ other test engine and its dependencies on the classpath. See
xref:appendix.adoc#dependency-metadata[Dependency Metadata] for details regarding group IDs, artifact IDs, and versions.

[[setup-required-dependencies]]
=== Required Dependencies

* `junit-platform-suite-api` in _test_ scope: artifact containing annotations needed to
  configure a test suite
* `junit-platform-suite-engine` in _test runtime_ scope: implementation of the
  `TestEngine` API for declarative test suites

NOTE: Both of the required dependencies are aggregated in the `junit-platform-suite`
artifact which can be declared in _test_ scope instead of declaring explicit dependencies
on `junit-platform-suite-api` and `junit-platform-suite-engine`.

[[setup-transitive-dependencies]]
=== Transitive Dependencies

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

[[example]]
== @Suite Example

Annotate a class with `@Suite` to have it marked as a test suite on the JUnit Platform. As
seen in the following example, selector and filter annotations can be used to control the
contents of the suite.

[source,java,indent=0]
----
include::example$java/example/SuiteDemo.java[tags=user_guide]
----

.Additional Configuration Options
NOTE: There are numerous configuration options for discovering and filtering tests in a
test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full
list of supported annotations and further details.

== @BeforeSuite and @AfterSuite

`@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a
`@Suite`-annotated class. They will be executed before and after all tests of the test
suite, respectively.

[source,java,indent=0]
----
include::example$java/example/BeforeAndAfterSuiteDemo.java[tags=user_guide]
----

[[duplicate-test-execution]]
== Duplicate Test Execution

Depending on the declared selectors, different suites may contain the same tests,
potentially with different configurations. Moreover, tests in a suite are executed in
addition to the tests executed by every other test engine, which can result in the same
tests being executed twice.

image::junit-platform-suite-engine-duplicate-test-execution-diagram.svg[role=text-center]

To prevent duplicate execution of tests within a suite, configure your build tool to
include only the `junit-platform-suite` engine, or use a custom naming pattern. For
example, name all suites `*Suite` and all tests `*Test`, and configure your build tool to
include only the former.

Alternatively, consider xref:running-tests/tags.adoc[using tags] to select specific groups of
tests.
