Skip to content
javahacks.dev
JUnit

JUnit 5 Architecture Explained Platform Jupiter and Vintage

JUnit 5 is a Platform, an engine called Jupiter and a Vintage engine for old tests. See how they fit together and why it explains most setup errors.

5 min read
Summarize in AI
Flat illustration of a JUnit test run with one failing test, with the JUnit5, Jenkins, Selenium, GitHub Actions and Cucumber logos.

When a build runs zero tests, or a JUnit 4 runner reports "No runnable methods" against a class you wrote with JUnit 5, the cause is nearly always the architecture. JUnit 5 deliberately split the old monolithic library into parts with separate jobs. Knowing the three parts turns those errors from mysteries into a single question: which engine is on the classpath? The tutorial that gets you started is JUnit 5 for beginners, and the framework tour is in the JUnit 5 handbook.

The three parts

PartRoleYou touch it when
JUnit PlatformLaunching and discovery; the TestEngine APIConfiguring a build tool or an IDE
JUnit JupiterThe annotations and the engine that runs themWriting tests
JUnit VintageAn engine for JUnit 3 and 4 testsMigrating old code

The Platform does not run tests itself. It asks each registered TestEngine to discover tests and execute them, then collects the results. That is why one mvn test can run Jupiter and Vintage tests in the same build.

Engines are the extension point

A test engine is a class registered through Java's ServiceLoader. Jupiter and Vintage are two; others exist for other styles:

Text
junit-platform-launcher   discovers engines and drives them
  junit-jupiter-engine    runs @Test from org.junit.jupiter.api
  junit-vintage-engine    runs @Test from org.junit (JUnit 4)
  (third-party engines)   run Spock, Cucumber, property-based tests

A build tool, such as Surefire or Gradle, uses the launcher. An IDE does too. If the engine for your annotations is missing from the test runtime classpath, the launcher finds nothing to run and reports zero tests, which is the silent failure in tests not running in Maven.

The artifacts you declare

ArtifactWhat it gives you
junit-jupiter-apiAnnotations and assertions, for compiling tests
junit-jupiter-engineThe engine, for running them
junit-jupiter-params@ParameterizedTest
junit-jupiterThe three above in one aggregate
junit-vintage-engineThe JUnit 4 engine
junit-platform-launcherThe launcher, which Gradle needs at runtime

A project that depends on the aggregate artifact gets everything needed. The split into API and engine exists so that test code compiles against a small stable API while the engine can change underneath.

What Vintage is for

Vintage runs org.junit.Test classes on the Platform, which lets a large JUnit 4 suite migrate one class at a time. Two caveats. A Jupiter class run by a JUnit 4 runner produces the "No runnable methods" error, and Spring Boot dropped Vintage from its default test starter in 2.4, so an upgrade silently stops running JUnit 4 tests until you add it back.

What changed in JUnit 6

JUnit 6 keeps the Platform, Jupiter and Vintage design and the org.junit.jupiter.api package, so a Jupiter test compiles unchanged. Visible differences are that all three parts share one version number, the minimum Java version is 17, and some long-deprecated APIs were removed. If your tests only use the annotations in this series, the upgrade is a version bump.

List the engines a build really has

Which engines run is decided by what is on the test runtime classpath, and a quick program prints them using the same discovery that the launcher uses:

java
public class ListEngines {
    public static void main(String[] args) {
        ServiceLoader.load(org.junit.platform.engine.TestEngine.class)
                .forEach(e -> System.out.println(e.getId() + " " + e.getClass().getName()));
    }
}

Run it with the test classpath, for example from a JUnit test or a Maven exec goal. A build that prints junit-jupiter runs Jupiter tests, and one that prints junit-vintage as well also runs JUnit 4 tests. A module that prints nothing runs no tests, and that explains the Tests run: 0 line. The same information appears at the start of the Surefire debug output.

Keep every JUnit artifact on one version

The platform, Jupiter and Vintage have separate version numbers, and the aggregate junit-bom aligns them. Import it once and leave the version off each dependency:

XML
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.junit</groupId>
            <artifactId>junit-bom</artifactId>
            <version>5.12.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

A mismatch between the launcher and an engine, for example Jupiter 5.12 with a platform launcher at 1.9, fails with NoSuchMethodError or OutOfMemoryError-free but confusing JUnitException: TestEngine with ID 'junit-jupiter' failed to discover tests. The BOM prevents it. Spring Boot's parent POM already manages these versions, so a project on Boot only declares spring-boot-starter-test.

Running without a build tool

The console launcher runs a test class from the command line, which shows the platform at work with no Maven or Gradle in the way:

Shell
java -jar junit-platform-console-standalone-1.12.0.jar \
  execute --class-path target/test-classes:target/classes \
  --select-class dev.javahacks.OrderServiceTest

The output prints the engine tree and the results per test. A class that is not found, or an engine that does not appear in the tree, is visible here without any plugin settings to blame. The same launcher API is what IDEs call, so a result that differs between the IDE and the build points to a difference in classpath and not in JUnit.

Writing your own engine

An engine is a class that implements TestEngine, with a discover and an execute method, registered through a service file. Cucumber, ArchUnit and jqwik are engines, and each takes over the discovery of tests of its own kind. The benefit for a project is that one launcher runs examples, property-based tests and unit tests together and reports them in one tree. A custom engine is rare in application code, and it is useful to know that the extension point exists, because it explains why a BDD tool runs from a normal mvn test.

SymptomArchitecture question to ask
Tests run: 0Is an engine on the runtime classpath?
No runnable methodsIs a JUnit 4 runner reading a Jupiter class?
Jupiter tests ignored, JUnit 4 tests runIs the Vintage engine present without Jupiter?
TestEngine ... failed to discover testsDo the platform and engine versions match?
A test runs in the IDE and not in the buildDo both use the same classpath and launcher?

Why the split pays off for tooling

The platform, engine and API split is what lets IDEs, build tools and test frameworks evolve separately. An IDE talks to the launcher and does not need to know about Jupiter. A build tool starts the launcher and reports results from any engine. A new test style arrives as an engine, with no change to Maven or Gradle. That is why a tool like jqwik runs from the usual commands.

For a project, the practical result is stability: upgrading a build plugin rarely changes how tests run, and upgrading Jupiter rarely requires a new plugin, as long as the launcher version is compatible.

Where the architecture matters less

For day-to-day test writing you only see Jupiter. The Platform matters when you build tooling, write a custom engine, or debug a setup. The JUnit user guide has the official diagram of the modules and the Platform launcher API documents programmatic launching.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.