84

What's the difference between maven modules junit-jupiter-api and junit-jupiter-engine? Is it necessary to include both dependencies in build.gradle?

Do I need to provide both dependencies?

testCompile("org.junit.jupiter:junit-jupiter-engine:${junitVersion}")
testCompile("org.junit.jupiter:junit-jupiter-api:${junitVersion}")

Or only one dependency is enough?

testCompile("org.junit.jupiter:junit-jupiter-engine:${junitVersion}")

And do I need to add a dependency on junit-vintage-engine?

Improve this question
1
  • Minor improvement: The recommendation of the JUnit team is to use testRuntime for both engines. Commented Jan 27, 2018 at 19:21

5 Answers 5

Reset to default
87

tl;dr

testImplementation(platform("org.junit:junit-bom:6.0.0-RC1"))
testImplementation("org.junit.jupiter:junit-jupiter")
testImplementation("org.junit.vintage:junit-vintage-engine")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")

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.

In Maven syntax:

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

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

In your project, you will also end up with:

  • junit-platform-commons-5.13.4.jar
  • junit-platform-engine-5.13.4.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.

In Maven syntax:

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

Gradle

The equivalent in Gradle, in the now-recommended Kotlin DSL (syntax), in a build.gradle.kts file:

dependencies {
    // JUnit
    testImplementation(platform("org.junit:junit-bom:6.0.0-RC1"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testImplementation("org.junit.vintage:junit-vintage-engine")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

Gradle 9, JUnit 6

You may want to see this Answer and this Answer](https://stackoverflow.com/a/79746408/642706) of mine covering the use of the new Gradle 9 with the new JUnit 6 on Java 24 and Java 25 respectively.

Improve this answer
Sign up to request clarification or add additional context in comments.

2 Comments

This is the best answer, in my opinion.
According to the official samples (junit.org/junit5/docs/current/user-guide/…) I suggest to handle the versions in the JUnit BOM (Bill Of Material): "org.junit:junit-bom"
63

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.

Improve this answer

4 Comments

You don't need to add both as jupiter-api is a transitive dependency of jupiter-engine.
In 5.5.1 version, I am able to write and run junit tests with the "junit-jupiter-api" only.
@gaurav, yes, that's covered in this part of my answer Note: in JUnit 5.4 this is simplified, see this answer for more details.
@glytching, but @Gaurav (and I) is using junit-jupiter-api only, not junit-jupiter
14

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

Improve this answer

1 Comment

Now simplified in JUnit 5.4 and later to simply <artifactId>junit-jupiter</artifactId>.
3

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.

Improve this answer

Comments

0

If you want to run the tests using the Junit 5, you will only need the junit-jupiter-api. If you use the junit-jupiter-engine along with, your tests will broke and will not run.

I'm not sure why it was placed, but, the previous answer informs that you will need to use the both is incorrect.

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.