Difference between junit-jupiter-api and junit-jupiter-engine

Question

JUnit Prior to Version 5.4

From the docs:

junit-jupiter-api

JUnit Jupiter API for writing tests and extensions.

junit-jupiter-engine

JUnit Jupiter test engine implementation, only required at runtime.

junit-vintage-engine

JUnit Vintage test engine implementation that allows to run vintage JUnit tests, i.e. tests written in the JUnit 3 or JUnit 4 style, on the new JUnit Platform.

So ...

• You need both junit-jupiter-api and junit-jupiter-engine to write and run JUnit5 tests
• You only need junit-vintage-engine if (a) you are running with JUnit5 and (b) your test cases use JUnit4 constructs/annotations/rules etc

JUnit from Version 5.4 Onwards

In JUnit 5.4 this is simplified, see this answer for more details.

junit-jupiter aggregator artifact

JUnit 5.4 provides much simpler Maven configuration if your intent is to write JUnit 5 tests. Simply specify the aggregate artifact named junit-jupiter.

<!-- https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter -->
<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.8.1</version>
    <scope>test</scope>
</dependency>

As an aggregate, this artifact in turn pulls the following three artifacts automatically, for your convenience:

• junit-jupiter-api (a compile dependency)
• junit-jupiter-params (a compile dependency)
• junit-jupiter-engine (a runtime dependency)

In your project, you will also end up with:

• junit-platform-commons-1.4.0.jar
• junit-platform-engine-1.4.0.jar

The above is what you need to write and run JUnit 5 tests based on the new Jupiter paradigm.

Legacy tests

If your project has JUnit 3 or 4 tests that you want to continue to run, add another dependency for the JUnit Vintage Engine, junit-vintage-engine. See tutorial by IBM.

<!-- https://mvnrepository.com/artifact/org.junit.vintage/junit-vintage-engine -->
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <version>5.8.1</version>
    <scope>test</scope>
</dependency>

Just to note, junit-jupiter-api is included as a sub-dependency in junit-jupiter-engine Maven repository. So you'll only really need to add junit-jupiter-engine to get both. I'm sure gradle is the same. https://mvnrepository.com/artifact/org.junit.jupiter/junit-jupiter-engine/5.1.1

The most accurate answer to your questions is in junit-team/junit5-samples repository. Just take a look at junit5-jupiter-starter-gradle for Gradle and junit5-jupiter-starter-maven for maven.

As you can see in both examples the only required dependency is junit-jupiter.