skip to content

How do you tell Gradle's Test task to run JUnit 5 (Jupiter) tests instead of the default JUnit 4 runner?

level: juniorimportance: must knowfreq 78%

answer

  1. default = JUnit 4
  2. useJUnitPlatform()
  3. Launcher drives TestEngines
  4. Jupiter engine discovers @Test
  5. one line in test { }

basics

~10 s

Call useJUnitPlatform() on the test task. By default Gradle uses the JUnit 4 runner, so you must opt into the JUnit Platform for Jupiter tests to be detected and executed.

solid answer

~40 s

Gradle's built-in `Test` task uses the JUnit 4 framework by default. To run JUnit 5 tests you switch the test framework to the JUnit Platform by calling `useJUnitPlatform()` inside the `test { }` (or `tasks.named<Test>("test")`) block. That configures Gradle to use the JUnit Platform's `Launcher` API to discover and run tests. Without it, Gradle will look only for JUnit 4 tests and your `@Test` (org.junit.jupiter.api) methods are silently skipped. You also need the Jupiter dependencies on the classpath — `org.junit.jupiter:junit-jupiter` (which pulls the API + the Jupiter engine) on `testImplementation`. With the Java plugin and modern Gradle you essentially write one line: `useJUnitPlatform()`.

code

kotlin · 3 lines
kotlin
tasks.named<Test>("test") {
    useJUnitPlatform()
}

go deeper

for a junior

Recall the single line useJUnitPlatform() and that JUnit 4 is the default.

for a middle

Explain that it switches Gradle to the Launcher API and which dependency provides the engine.

for a senior

Discuss the tag-filtering closure and the modern JvmTestSuite useJUnitJupiter() alternative.

for a principal

Frame consistent test-framework selection across a multi-module build via a convention plugin so no module forgets the opt-in.

## The default is JUnit 4 Gradle's `Test` task has historically defaulted to the **JUnit 4** test framework. JUnit 5 is built on a completely different foundation called the **JUnit Platform**, so simply adding Jupiter to the classpath is not enough — you must explicitly tell the `Test` task which framework to use. ## useJUnitPlatform() The `Test` task exposes three mutually exclusive framework selectors: - `useJUnit()` — the legacy JUnit 4 runner (the default) - `useJUnitPlatform()` — the JUnit Platform (required for JUnit 5 / Jupiter) - `useTestNG()` — TestNG Calling `useJUnitPlatform()` switches Gradle to drive tests through the JUnit Platform's `Launcher` API. The Platform then asks every registered **TestEngine** on the classpath to discover tests. The Jupiter engine (`junit-jupiter-engine`) discovers classes with `org.junit.jupiter.api.Test` methods. ## What you need on the classpath Add the aggregator `org.junit.jupiter:junit-jupiter` to `testImplementation`. That aggregator transitively brings in `junit-jupiter-api`, `junit-jupiter-params`, and `junit-jupiter-engine`. The engine is what the Platform discovers at runtime. ```kotlin plugins { java } dependencies { testImplementation("org.junit.jupiter:junit-jupiter:5.10.2") } tasks.named<Test>("test") { useJUnitPlatform() } ``` ## Modern shortcut If you declare a JVM test suite (`testing { suites { val test by getting(JvmTestSuite::class) { useJUnitJupiter() } } }`) or use a recent Spring Boot starter, the wiring and `useJUnitPlatform()` are configured for you. But knowing the explicit one-liner is the bedrock skill.

  • What happens if you forget useJUnitPlatform() but add Jupiter dependencies?
    Gradle stays on the JUnit 4 runner, so it never invokes the Jupiter engine. Your tests are not discovered and the build reports zero (or only JUnit 4) tests run — a silent no-op, not an error.
  • Can you pass configuration to useJUnitPlatform()?
    Yes — it takes an optional closure where you can filter by tags, e.g. useJUnitPlatform { includeTags("fast"); excludeTags("slow") }.

saying these in an interview costs you the question

  • Saying JUnit 5 runs by default in Gradle — it does not; JUnit 4 is the default.
  • Claiming you only need the dependency and nothing on the test task.

context

resolving links…