JUnit 5 – Setup

With JUnit 5 still under development, tool support is not at 100% yet and setting JUnit 5 up in your favorite one still requires a little work. Here’s how to do it in IntelliJ, Eclipse, Maven, Gradle, or, if everything else fails, on the command line.

As we speak, the work on JUnit 5 goes on. Throughout 2016 and 2017 various Milestones were published and a general availability release is planned for sometime in late summer. I am exploring the next generation of testing on the JVM with in a series of short posts:


This series is based on the pre-release version Milestone 4 and will get updated when a new milestone or the GA release gets published. Another good source is the JUnit 5 user guide. You can find all code samples on GitHub.

Writing Tests

The API for writing tests is contained in the junit-jupiter-api artifact. Including it in your project with your favorite build tool is all it takes to write tests.

  • Group ID: org.junit.jupiter
  • Artifact ID: junit-jupiter-api
  • Version: 5.0.0-M4

To have something to work with, let’s quickly create our first test:

See ma, no public! Cool, right? I won’t go into it here, check out the post on basics for more details.

Running Tests

With JUnit 5 being bleeding edge, native tool support is not ideal, yet. But there are early access implementations and workarounds to get everything running.

IDE Support

Since 2016.2 IntelliJ IDEA has basic JUnit 5 support. It is not perfect and will have to keep catching up with a moving target but it works and makes playing around with the new JUnit much easier. To run tests written against Milestone 3 you have to use 2016.3.1, for Milestone 4 it is 2017.1.2.

The Eclipse team is working on native support and it is currently targeted for Oxygen.1 (4.7.1) in September 2017. If you don’t mind a little configuration you can try it out with the Eclipse 4.7 M4 build following these steps.

Build Tool Support

The JUnit team put in some initial work to implement build tool support. A rudimentary Gradle plugin and Maven Surefire provider are up and running and there are sample projects for both (Gradle, Maven). For more details have a look at the user guide.

In the last months the Maven and the Gradle teams have taken over (Maven #1206, Gradle #1037) and we can expect both build tools to fully support JUnit 5 soon(ish).

JUnit 4 Runner

If the support for your tool of choice does not suffice, you can try a detour via JUnit 4: A test runner called JUnitPlatform can be used to run new tests as part of a JUnit 4 run. You will find it in its own artifact, which you have to add to your project:

  • Group ID: org.junit.platform
  • Artifact ID: junit-platform-runner
  • Version: 1.0.0-M4
  • Scope: test

The runner will call into the engine that actually runs the JUnit 5 tests. The engine also has its own artifact that you have to add:

  • Group ID: org.junit.jupiter
  • Artifact ID: junit-jupiter-engine
  • Version: 5.0.0-M4
  • Scope: test runtime

To run all tests in a project, it is easiest to create a test suite for them:

Note that the class has to be a regular JUnit 4 test class, i.e. it has to adhere to the common naming convention and must be public. The @SelectPackages-annotation interprets packages as a hierarchy so it runs all tests in all packages prefixed with org.codefx.demo.junit5. If you prefer, you can use the same runner directly on the JUnit 5 test classes; in that case they have to be public.

Now we’re done! Your favorite IDE and build tool will happily run the classes annotated with @RunWith(JUnitPlatform.class) and hence the new JUnit 5 tests.

Due to the detour through JUnit 4, some features may not work, e.g. IDEs won’t run individual test methods. But if the other approaches do not work for you, this can be an acceptable and tool independent solution.

Command Line For The Win!

In case all of this is too fancy for you, try the console launcher, which lets you run the tests directly from the command line. The best way to use it is to download the standalone JAR, which comes with all the required dependencies.

Ignoring dependencies (e.g. on your production code, your own extensions or other test libraries) you can then use it as follows:

To include dependencies add them to the class path after -cp. If you’re doing this in a Maven project, your command might look like this:


As you might have noticed, JUnit 5 occupies new namespaces: org.junit.jupiter, org.junit.platform, and org.junit.vintage (which we didn’t see yet). I explain their meaning in a post dedicated to JUnit’s architecture – for now this only means that there will be no conflicts when different JUnit versions are used in the same project.

Indeed, a project can contain and run tests from different versions without problems, which allows a slow migration to JUnit 5. We will revisit this topic when we’re exploring migration paths (stay tuned).

Assertion libraries like Hamcrest and AssertJ, which communicate with JUnit via exceptions, will continue to work in the new version. Check out the complete version of HelloWorldTest for an example using Mockito and AssertJ.


For our JUnit 5 setup we’ve included junit-jupiter-api, junit-jupiter-engine, and junit-platform-runner in our project, written a first minimal test case, and ran it with as part of a JUnit 4 test suite.

The next post explores the basics of how to write tests in JUnit 5.

Share & Follow

You liked this post? Then share it with your friends and followers!
And if you like what I'm writing about, why don't you follow me?

Other Posts