documentation/src/docs/asciidoc/user-guide/overview.adoc

[[overview]]
== Overview

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

[[overview-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 <<launcher-api,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
<<running-tests-console-launcher,Console Launcher>> to launch the platform from the
command line and the <<junit-platform-suite-engine>> 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 <<running-tests-ide-intellij-idea>>,
<<running-tests-ide-eclipse>>, <<running-tests-ide-netbeans>>, and
<<running-tests-ide-vscode>>) and build tools (see <<running-tests-build-gradle>>,
<<running-tests-build-maven>>, and <<running-tests-build-ant>>).

**JUnit Jupiter** is the combination of the new <<writing-tests,programming model>> and
<<extensions,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.

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

[[overview-getting-help]]
=== Getting Help

Ask JUnit 5 related questions on {StackOverflow} or chat with the community on {Gitter}.

[[overview-getting-started]]
=== Getting Started

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

To find out what artifacts are available for download and inclusion in your project, refer
to <<dependency-metadata>>. To set up dependency management for your build, refer to
<<running-tests-build>> and the <<overview-getting-started-example-projects>>.

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

* <<writing-tests, Writing Tests in JUnit Jupiter>>
* <<migrating-from-junit4, Migrating from JUnit 4 to JUnit Jupiter>>
* <<running-tests>>
* <<extensions, Extension Model for JUnit Jupiter>>
* Advanced Topics
  - <<launcher-api>>
  - <<testkit>>

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

To see complete, working examples of projects that you can copy and experiment with, the
{junit5-samples-repo}[`junit5-samples`] repository is a good place to start. The
`junit5-samples` repository hosts a collection of sample 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 `{junit5-jupiter-starter-gradle}` project.
* For Gradle and Kotlin, check out the `{junit5-jupiter-starter-gradle-kotlin}` project.
* For Gradle and Groovy, check out the `{junit5-jupiter-starter-gradle-groovy}` project.
* For Maven, check out the `{junit5-jupiter-starter-maven}` project.
* For Ant, check out the `{junit5-jupiter-starter-ant}` project.