= Overview
:page-aliases: index.adoc, user-guide/index.adoc

The goal of this document is to provide comprehensive reference documentation for
programmers writing tests, extension authors, and engine authors as well as build tool
and IDE vendors.

ifdef::backend-html5[]
ifdef::linkToPdf[]
This document is also available as a link:{userGuidePdfFileName}[PDF download].
endif::linkToPdf[]
endif::backend-html5[]

[[what-is-junit-5]]
== What is JUnit 5?

Unlike previous versions of JUnit, JUnit 5 is composed of several different modules from
three different sub-projects.

**JUnit 5 = _JUnit Platform_ + _JUnit Jupiter_ + _JUnit Vintage_**

The **JUnit Platform** serves as a foundation for xref:advanced-topics/launcher-api.adoc[launching testing
frameworks] on the JVM. It also defines the `{TestEngine}` API for developing a testing
framework that runs on the platform. Furthermore, the platform provides a
xref:running-tests/console-launcher.adoc[Console Launcher] to launch the platform from the
command line and the xref:advanced-topics/junit-platform-suite-engine.adoc[] for running a custom test suite using
one or more test engines on the platform. First-class support for the JUnit Platform also
exists in popular IDEs (see xref:running-tests/ide-support.adoc#intellij-idea[IntelliJ IDEA],
xref:running-tests/ide-support.adoc#eclipse[Eclipse], xref:running-tests/ide-support.adoc#netbeans[NetBeans], and
xref:running-tests/ide-support.adoc#vscode[Visual Studio Code]) and build tools (see xref:running-tests/build-support.adoc#gradle[Gradle],
xref:running-tests/build-support.adoc#maven[Maven], and xref:running-tests/build-support.adoc#ant[Ant]).

**JUnit Jupiter** is the combination of the xref:writing-tests/intro.adoc#tests[programming model] and
xref:extensions/overview.adoc[extension model] for writing tests and extensions in JUnit 5. The Jupiter
sub-project provides a `TestEngine` for running Jupiter based tests on the platform.

**JUnit Vintage** provides a `TestEngine` for running JUnit 3 and JUnit 4 based tests on
the platform. It requires JUnit 4.12 or later to be present on the class path or module
path.

[[java-versions]]
== Supported Java Versions

JUnit 5 requires Java 8 (or higher) at runtime. However, you can still test code that
has been compiled with previous versions of the JDK.

[[getting-help]]
== Getting Help

Ask JUnit 5 related questions on {StackOverflow} or use the {DiscussionsQA}.

[[getting-started]]
== Getting Started

[[getting-started-junit-artifacts]]
=== Downloading JUnit Artifacts

To find out what artifacts are available for download and inclusion in your project, refer
to xref:appendix.adoc#dependency-metadata[Dependency Metadata]. To set up dependency management for your build, refer to
xref:running-tests/build-support.adoc[] and the <<getting-started-example-projects>>.

[[getting-started-features]]
=== JUnit 5 Features

To find out what features are available in JUnit 5 and how to use them, read the
corresponding sections of this User Guide, organized by topic.

* xref:writing-tests/intro.adoc#tests[Writing Tests in JUnit Jupiter]
* xref:migrating-from-junit4.adoc[Migrating from JUnit 4 to JUnit Jupiter]
* xref:running-tests/intro.adoc[]
* xref:extensions/overview.adoc[Extension Model for JUnit Jupiter]
* Advanced Topics
  - xref:advanced-topics/launcher-api.adoc[]
  - xref:advanced-topics/testkit.adoc[]

[[getting-started-example-projects]]
=== Example Projects

To see complete, working examples of projects that you can copy and experiment with, the
{junit-examples-repo}[`junit-examples`] repository is a good place to start. The
`junit-examples` repository hosts a collection of example projects based on JUnit Jupiter,
JUnit Vintage, and other testing frameworks. You'll find appropriate build scripts (e.g.,
`build.gradle`, `pom.xml`, etc.) in the example projects. The links below highlight some
of the combinations you can choose from.

* For Gradle and Java, check out the `{junit-jupiter-starter-gradle}` project.
* For Gradle and Kotlin, check out the `{junit-jupiter-starter-gradle-kotlin}` project.
* For Gradle and Groovy, check out the `{junit-jupiter-starter-gradle-groovy}` project.
* For Maven, check out the `{junit-jupiter-starter-maven}` project.
* For Ant, check out the `{junit-jupiter-starter-ant}` project.
