77

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?

yanefedor
  • 2,132
  • 1
  • 21
  • 37

5 Answers5

75

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.9.1</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-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.9.1</version>
    <scope>test</scope>
</dependency>
Basil Bourque
  • 303,325
  • 100
  • 852
  • 1,154
  • 1
    This is the best answer, in my opinion. – Benoît Dubreuil May 18 '21 at 00:21
  • According to the official samples (https://junit.org/junit5/docs/current/user-guide/#overview-getting-started-example-projects) I suggest to handle the versions in the JUnit BOM (Bill Of Material): "org.junit:junit-bom" – becke-ch Nov 10 '22 at 16:55
58

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.

Community
  • 1
  • 1
glytching
  • 44,936
  • 9
  • 114
  • 120
  • 4
    You don't need to add both as `jupiter-api` is a transitive dependency of `jupiter-engine`. – hrzafer Mar 10 '19 at 02:31
  • 2
    In 5.5.1 version, I am able to write and run junit tests with the "junit-jupiter-api" only. – Gaurav Aug 01 '19 at 12:41
  • 2
    @gaurav, yes, that's covered in this part of my answer _Note: in JUnit 5.4 this is simplified, see [this answer](https://stackoverflow.com/a/55084036/8200937) for more details._ – glytching Aug 01 '19 at 13:03
  • @glytching, but @Gaurav (and I) is using `junit-jupiter-api` only, not `junit-jupiter` – Leponzo Oct 07 '21 at 21:13
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

Kasun
  • 642
  • 1
  • 7
  • 16
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.

hrzafer
  • 1,123
  • 1
  • 15
  • 35
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.

Arefe
  • 11,321
  • 18
  • 114
  • 168