In November 2015 the JUnit Lambda team presented their prototype. Since then the project rebranded itself as JUnit 5 and released an alpha version in February 2016. We’ll explore it in a series of short posts:

This one discusses the JUnit 5 setup so you can write code against the new API and run tests in your IDE or with your build tool.


Most of what you will read here and more can be found in the emerging JUnit 5 user guide. Note that it is based on an alpha version and hence subject to change.

Indeed, we are encouraged to open issues or pull requests so that JUnit 5 can improve further. Please make use of this opportunity! It is our chance to help JUnit help us, so if something you see here could be improved, make sure to take it upstream.

This post will get updated when it becomes necessary. The code samples I show here can be found on GitHub.

Writing Tests

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

  • Group ID: org.junit5
  • Artifact ID: junit5-api
  • Version: 5.0.0-ALPHA

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

package org.codefx.demo.junit5;

import org.junit.gen5.api.Test;

class HelloWorldTest {

	void helloJUnit5() {
		System.out.println("Hello, JUnit 5.");


See ma, no public! Cool, right? I won’t go into it at the moment but the next post will discuss this (and other basics) so stay tuned.

Running Tests

With JUnit 5 being cutting edge, native tool support is lacking. But there are preliminaries to get everything running.

JUnit 4 Runner

A test runner called JUnit5 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.junit5
  • Artifact ID: junit4-runner
  • Version: 5.0.0-ALPHA

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.junit5
  • Artifact ID: junit5-engine
  • Version: 5.0.0-ALPHA

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

package org.codefx.demo.junit5;

import org.junit.gen5.junit4.runner.JUnit5;
import org.junit.gen5.junit4.runner.Packages;
import org.junit.runner.RunWith;

@Packages({ "org.codefx.demo.junit5" })
public class TestWithJUnit5 { }

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 @Packages-annotation interprets packages as a hierarchy so it runs all tests in all packages prefixed withorg.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 the classes annotated with @RunWith(JUnit5.class) and hence the new JUnit 5 tests.

Until true JUnit 5 support comes around, some features may not work, e.g. IDEs won’t run individual test methods. But for the time being I found this to be the most straight-forward and tool independent solution.

Build Tool Support

The JUnit team is already hard at work to implement build tool support for JUnit 5, i.e. without the detour via JUnit 4. A rudimentary Gradle plugin and Maven Surefire provider are up and running. Both projects are planned to be handed over to the respective communities at some point.

There are sample projects for both (Gradle, Maven). For more details have a look at the user guide.

Command Line For The Win!

In case all of this is too fancy for you, try the console runner, which lets you run the tests directly from the command line. To get hold of it you can download this ZIP.

Unfortunately it doesn’t work out of the box. I had to drop the junit5api andjunit5engine artifacts mentioned above into lib and edit the class path definition in the script in bin to CLASSPATH=$APP_HOME/lib/* to make it work.

Ignoring additional dependencies (e.g. on other test libraries) you can use it as follows:

# run all tests
junit-console -p ${path_to_compiled_test_classes} -a
# run a specific test
	-p ${path_to_compiled_test_classes}

Screen Shot 2016-03-06 at 21.59.30


As you might have noticed, JUnit 5 occupies a new namespace: org.junit.gen5. This 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 JUnit’s new architecture.

Test 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 junit5api, junit5engine, and junit4runnerin our project, written a first minimal test case, and ran it with as part of a JUnit 4 test suite.

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


JUnit 5 – Setup

| Java Language| 1,090 views | 0 Comments
About The Author
- Nicolai is a thirty year old boy, as the narrator would put it, who has found his passion in software development. He constantly reads, thinks, and writes about it, and codes for a living as well as for fun. Nicolai is the editor of SitePoint's Java channel, writes The Java 9 Module System with Manning, blogs about software development on, and is a long-tail contributor to several open source projects. You can hire him for all kinds of things.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>