JUnit 6 Migration Made Easy: Step-by-Step From JUnit 5

How to Migrate From JUnit 5 to JUnit 6

To migrate from JUnit 5 to JUnit 6, upgrade Java to 17+, update all JUnit dependencies to 6.0.0, refactor deprecated APIs, and validate the suite by running all tests.

Pre-requisites

The first and foremost step to start with migration to JUnit 6 is to ensure that the existing project compiles with Java 17 or newer and Kotlin 2.2 or newer. This is essential since JUnit 6 works with the upgraded baseline versions only. Without having the project built on these, there is no point in moving forward with migration.

This also involves checking and fixing the IDE and CI config and settings for the updated versions. Once this is done, simply build the project and run the existing tests to confirm they still pass. If you need a refresher on running tests, refer to this JUnit tutorial. Then you are good to go with the next step.

Manual Migration (Dependencies Update and Code Refactor)

Once the baseline versions are upgraded, the next step of JUnit 6 migration will be to update the dependencies. You also need to refactor the code for removed or deprecated APIs and modules.

The following subsections cover the dependency changes and code-level updates required for a successful migration.

Dependencies Update

JUnit 6 consolidates multiple modules and updates dependency versions across the framework. The following changes need to be applied to your Maven or Gradle build configuration files.

Note: Run JUnit 6 tests across 3000+ real browser and OS environments at scale. Try TestMu AI Now!

Update JUnit Dependencies

Consolidate and update all the JUnit dependencies to the latest 6.0.0 (or a compatible 6.x) versions for junit-jupiter, junit-platform, and junit-vintage (if used).

For Maven, updated dependencies will look like

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>6.0.0</version>
    <scope>test</scope>
</dependency>

<!-- If you still have JUnit4 tests, include Vintage too -->
<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <version>6.0.0</version>
    <scope>test</scope>
</dependency>

For Gradle, similarly, make the changes and remove any JUnit 4 junit:junit dependency. The existing useJUnitPlatform() directive in your test block continues to work as-is with JUnit 6.

testImplementation("org.junit.jupiter:junit-jupiter:6.0.0")

Remove External Platform Jars

If you have the following platform jars added explicitly, remove them as JUnit 6 no longer supports these.

//Remove these
junit-platform-runner
junit-platform-jfr
junit-platform-suite-commons

Their content is now included directly in junit-platform-launcher.

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>6.0.0</version>
    <scope>test</scope>
</dependency>

Upgrade Build Plugins

The next step is to ensure that the versions for the Maven Surefire and Failsafe plugin are updated to 3.x or later in the build file.

Code Refactor

Once all the dependencies are updated, the next migration step would be to refactor the test code. This makes it in accordance with the removed or changed APIs and modules.

The key areas of refactoring involve annotations, Store APIs, and method ordering implementations.

Remove Deprecated Annotations/Attributes

Remove any @EnabledOnJre(JRE.JAVA_X) or @DisabledOnJre(JRE.JAVA_X) where X < 17. These annotations are now redundant as the condition will never apply below Java 17. Also, for all the range annotations, ensure to review the range, as now 17 is the default minimum value.

@DisabledOnJre(JRE.JAVA_8)  // Under Java 17, this condition never applies
void testOnlyOnJava8() { ... }

Update the @CsvFileSource usage by removing the lineSeparator attribute as JUnit 6 auto-detects line endings.

//Old JUnit 5 implementation
@ParameterizedTest
@CsvFileSource(
    resources = "/users.csv",
    numLinesToSkip = 1,
    lineSeparator = "\n"
)

//New JUnit 6 implementation
@ParameterizedTest
@CsvFileSource(
    resources = "/users.csv",
    numLinesToSkip = 1
)

Update Removed APIs

Replace the getOrComputeIfAbsent() method of ExtensionContext.Store with the updated implementation of computeIfAbsent(). Also, review and fix the code implementation if the return value was casted previously. The new method comes with nullability annotations.

// Old JUnit 5 implementation
MyType obj = store.getOrComputeIfAbsent(MyType.class);

// New JUnit 6 implementation
MyType obj = store.computeIfAbsent(MyType.class);

Also, if your suite uses the InvocationInterceptor.interceptDynamicTest() method, note that it has been removed in JUnit 6. Refactor those dynamic test interceptors using other available extension points.

Update Test Methods Ordering and Nesting

Update the test classes that have @TestMethodOrder(MethodOrderer.Alphanumeric.class) for test ordering. Use a supported orderer like MethodOrderer.MethodName.class if ordering is crucial for your execution. If not, just remove the annotation and use JUnit 6's default ordering, which is now deterministic in nature.

// Old JUnit 5 implementation
@TestMethodOrder(MethodOrderer.Alphanumeric.class)
class MyTests { ... }

// New JUnit 6 implementation with orderer
@TestMethodOrder(MethodOrderer.MethodName.class)
class MyTests { ... }

// OR

// New JUnit 6 implementation with default ordering
class MyTests { ... }

Also, if you are having JUnit 5 nested test classes in your suite, the order of nested classes may now be different. JUnit 6 now enforces a deterministic but intentionally nonobvious order. In most cases, this requires no code change but needs to be verified if a certain execution order is expected.

Finally, review your junit-platform.properties file if present. Some configuration keys related to removed modules or deprecated features may need to be updated or deleted to avoid startup warnings.

Automated Migration (OpenRewrite Recipe Approach)

For large automation suites, manually making all the changes to APIs and annotations for migrating to JUnit 6 can be time-consuming and prone to more human errors. This is where automated migration tools like OpenRewrite come to the rescue.

The OpenRewrite project provides an automated recipe that automatically reviews and refactors the entire code base for JUnit 5 to JUnit 6 migration. This recipe will

• Dependencies: Update all the Maven/Gradle dependencies by updating the baseline versions and removing deprecated modules.
• Annotations: Remove deprecated annotation attributes like lineSeparator.
• API Methods: Replace deprecated methods like getOrComputeIfAbsent with updated ones, computeIfAbsent.
• Test Ordering: Change the test method orderer implementation in test classes.
• JRE Annotations: Update or remove obsolete/redundant JRE conditional annotations based on Java 17.
• Config Properties: Delete obsolete configuration properties.

To use the OpenRewrite recipe, you would have to apply the following configuration depending on the build tool used.

Maven OpenRewrite Recipe Configuration

Step 1: Add the following to your pom.xml file.

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.openrewrite.maven</groupId>
        <artifactId>rewrite-maven-plugin</artifactId>
        <version>6.26.0</version>
        <configuration>
          <exportDatatables>true</exportDatatables>
          <activeRecipes>
            <recipe>org.openrewrite.java.testing.junit6.JUnit5to6Migration</recipe>
          </activeRecipes>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-testing-frameworks</artifactId>
            <version>3.24.0</version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>
</project>

Step 2: Execute the following Maven command to run the recipe.

mvn rewrite:run

Gradle OpenRewrite Recipe Configuration

Step 1: Add the following to your build.gradle file.

plugins {
    id("org.openrewrite.rewrite") version("latest.release")
}

rewrite {
    activeRecipe("org.openrewrite.java.testing.junit6.JUnit5to6Migration")
    setExportDatatables(true)
}

repositories {
    mavenCentral()
}

dependencies {
    rewrite("org.openrewrite.recipe:rewrite-testing-frameworks:3.24.0")
}

Step 2: Execute the following Gradle command to run the recipe.

gradle rewriteRun

This automated approach saves a lot of effort and makes the migration even quicker for larger projects. It ensures consistency and catches many small issues that would have been missed in a manual approach.

Validating Migration

After all the required dependency updates and code refactoring is done, the final step to complete the migration to JUnit 6 is to run the full suite and analyse the results.

There are three main areas to check during validation to ensure everything works correctly after migration.

• Compilation Errors: These indicate missed API changes or calls to removed methods. Error messages usually mention the missing class or method directly.
• Test Failures: Behavioural updates like CSV parsing, nested class ordering, or method ordering changes might cause previously stable tests to fail.
• IDE Warnings: New nullability warnings or deprecation alerts may appear due to JSpecify and deprecated JUnit 4. Resolve these accordingly.

Once done, run the entire suite again and validate the results. Repeat the process until every test passes, indicating that the suite is now successfully migrated and running on JUnit 6. With this, you are ready to leverage all the JUnit 6 updates and new features.

Once migrated, running JUnit 6 tests at scale becomes the next priority. For this, you can leverage platforms like TestMu AI for automation testing. It is a full stack quality engineering platform that lets teams execute Selenium-based JUnit tests across real browser and OS combinations without managing local infrastructure.

To get started, check out this guide on Selenium JUnit testing with TestMu AI.

Best Practices for JUnit 6 Migration

A few of the best practices and tips that you can follow for a quick and seamless migration from JUnit 5 to JUnit 6 are listed below.

• Verifying Third-Party Library Compatibility: Ensure libraries like Mockito, Spring Boot Test, and AssertJ support JUnit 6 and Java 17 before migrating.
• Migrating to JUnit 6 Supported Extensions: Review all JUnit 5 extensions and update them to JUnit 6 APIs, including store APIs and nullability checks.
• Test Lifecycle Annotations: Verify JUnit annotations like @BeforeAll, @BeforeEach, @AfterEach, and @AfterAll work correctly with JUnit 6 type-safety updates.
• Leveraging @Nested Test Classes: Use @Nested for logical grouping to take advantage of JUnit 6's deterministic ordering and improved readability.
• Parallel Execution and Thread-Safety: Enable parallel execution in JUnit for faster results after validating thread safety across the suite.
• Removing JUnit 4 Post-Migration: Address JUnit Vintage warnings proactively and migrate remaining JUnit 4 tests to avoid future breakage.
• Migrating Incrementally: Start with a single module or small test subset to catch issues early without breaking the full CI pipeline.
• Leveraging IDEs: Use the latest IDE versions to run, debug, and resolve JUnit 6 warnings and errors more efficiently.
• Tracking JUnit 6.x Releases: Monitor future JUnit 6.x updates for bug fixes and improvements that may require code changes.

Troubleshooting Common JUnit 6 Migration Issues

Some of the most common issues you might face during the migration to JUnit 6, along with their root cause and fix, are listed below.

Each issue includes the error details, root cause, and the recommended fix to resolve it.

Build Fails: "JUnitPlatform" or Platform Runner Classes Not Found

Issue: After migrating to JUnit 6, the project fails to compile with an error like

package org.junit.platform.runner does not exist
class JUnitPlatform cannot be found

Reason: The junit-platform-runner module is removed in JUnit 6. Hence, the class @RunWith(JUnitPlatform.class) used in JUnit 4 integration no longer exists.

Fix: Remove the dependency and any old JUnit 4 runner usage. JUnit 6 runs Jupiter tests directly via the JUnit Platform, and no runner is needed.

<artifactId>junit-platform-runner</artifactId>
@RunWith(JUnitPlatform.class)

Failure in Tests Using @CsvFileSource

Issue: Parameterized test cases that used to pass earlier are now throwing CSV parsing errors or unexpected failures after migrating to JUnit 6.

Reason: JUnit 6 has introduced FastCSV parser to enforce correct quoting and formatting. It has also removed the earlier used lineSeparator attribute.

Fix: Remove the unsupported lineSeparator attribute. Ensure that the test data CSV has a consistent delimiter and has no stray characters after closing quotes or malformed lines.

// Old JUnit 5 implementation
@CsvFileSource(resources = "/test.csv", lineSeparator = "\n")

// New JUnit 6 implementation
@CsvFileSource(resources = "/test.csv")

Failed Extensions: "getOrComputeIfAbsent Not Found"

Issue: Extensions that use the JUnit 5 Store API fail to compile with an error like below.

method getOrComputeIfAbsent does not exist

Reason: JUnit 6 has removed the old getOrComputeIfAbsent() store methods. They are replaced with computeIfAbsent() methods having nullability support to ensure type-safety.

Fix: Replace the old implementation with the updated methods and handle nullability as well.

// Old JUnit 5 implementation
// <1> returns MyType
store.getOrComputeIfAbsent(MyType.class);
// <2> returns @Nullable Object
store.getOrComputeIfAbsent("key", key -> new MyType());
// <3> returns @Nullable MyType
store.getOrComputeIfAbsent("key", key -> new MyType(), MyType.class);

// New JUnit 6 implementation
// <1> returns MyType
store.computeIfAbsent(MyType.class);
// <2> returns Object
store.computeIfAbsent("key", key -> new MyType());
// <3> returns MyType
store.computeIfAbsent("key", key -> new MyType(), MyType.class);

CI Pipeline Shows 0 Tests After Migration to JUnit 6

Issue: The suite is compiled successfully on CI, but CI shows 0 tests.

0 tests run

Reason: Either the CI or Surefire/Failsafe plugins, or both, are running on an older version. JUnit 6 fails to discover tests and run them.

Fix: Ensure that the CI is using Java 17 or newer, and Surefire/Failsafe plugin versions are updated to 3.x.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.5</version>
</plugin>

Third-Party Extensions Fail to Load or Compile

Issue: After migration, third-party extensions like Mockito, Spring Boot Test, or custom extensions throw NoSuchMethodError or ClassNotFoundException at runtime.

Reason: Older versions of third-party libraries may depend on JUnit 5 internal APIs that have been removed or changed in JUnit 6. They may also not be compiled for Java 17.

Fix: Update third-party testing libraries to their latest versions that declare JUnit 6 compatibility. Check the library's release notes or changelog for JUnit 6 support confirmation before upgrading.

Conclusion

With this, we have come to the end of this JUnit 6 migration guide. We learnt how this migration would help to evolve the suite to capitalise on all the improvements made in JUnit 6.

Remember, upgrading Java and Kotlin versions, updating build configurations, and changes to deprecated APIs, along with some minor tweaks, is all you need to do manually or with OpenRewrite for this migration to complete.

Once done, you are good to take advantage of the JUnit 6 features and create more robust automation frameworks in the Java ecosystem.

Citations

• JUnit 6 Release Notes: https://docs.junit.org/6.0.0/release-notes.html
• JUnit GitHub: https://github.com/junit-team/junit-framework/wiki/Upgrading-to-JUnit-6.0
• JUnit 6 Migration OpenRewrite Recipe: https://docs.openrewrite.org/recipes/java/testing/junit6/junit5to6migration#tags