1. Home
2. Blog
3. Migrating from JUnit 4 to JUnit 5: implementing the migration, dependencies, annotations

Implementing the migration from JUnit 4 to JUnit 5 can be done step by step and, for a period of time, you may be working with a hybrid approach for mature projects. The article will compare the needed JUnit 4 and JUnit 5 dependencies. Then, it will compare the equivalent JUnit 4 and JUnit 5 annotations.

 

1. The steps between JUnit 4 and JUnit 5

 

JUnit 5 is a new paradigm introducing a new architecture. It also introduces new packages, annotations, methods, and classes. Some JUnit 5 features are similar to JUnit 4 features; others are new, providing new capabilities. The JUnit Jupiter programming and extension model does not natively support JUnit 4 features such as rules and runners. We do not need to update all existing tests, test extensions, and custom-built test infrastructure to migrate projects to JUnit Jupiter—at least, not instantly.

 

JUnit provides a migration path with the help of the JUnit Vintage test engine; table 1 summarizes the most important steps. This offers the possibility to execute tests based on old JUnit versions using the JUnit Platform infrastructure. All classes and annotations specific to JUnit Jupiter are located in the new org.junit.jupiter base package. All classes and annotations specific to JUnit 4 are located in the old org.junit base package. So, having both JUnit 4 and JUnit 5 Jupiter in the classpath does not result in a conflict. Consequently, our projects can keep previously implemented JUnit 4 tests together with JUnit Jupiter tests. JUnit 5 and JUnit 4 can coexist until we finalize our migration, whenever that can be, and this migration can be planned and executed slowly based on the priority of the tasks and the challenges of the various steps.

 

 

Table 1 Migrating from JUnit 4 and JUnit 5

 

Main step	Comments
Replace the needed dependencies.	JUnit 4 needs a single dependency. JUnit 5 requires more dependencies, related to the features that are used. JUnit 5 uses JUnit  Vintage to work with old JUnit 4 tests.
Replace the annotations, and introduce the  new ones.	Some JUnit 5 annotations mirror the old JUnit 4 ones. Some new annotations introduce new facilities and help us write better tests.
Replace the testing classes and methods.	JUnit 5 assertions and assumptions have been moved to different classes in different packages.
Replace the JUnit 4 rules and runners with  the JUnit 5 extension model.	This step generally requires more effort than the other steps in this table. Because JUnit 4 and JUnit 5 can coexist for a long period,  however, the rules and runners can remain in the code or be replaced much later.

 

Before developing and running JUnit tests

• JUnit 4 requires Java 5 or later.
• JUnit 5 requires Java 8 or later.

 

 

Consequently, migrating from JUnit 4 to JUnit 5 can require an update of the Java version used in the project.

Tudose, Florin-Catalin Tudose

Java Champion; Java Chapter Lead; Author at Pluralsight and Manning