How to Run JUnit Tests from the Command Line

From the root of an existing project, use its build wrapper: ./mvnw test for Maven or ./gradlew test for Gradle. On Windows, use mvnw.cmd test or gradlew.bat test. If the project has no wrapper, use the installed mvn test or gradle test. These commands compile and run tests using the project’s configured dependencies and test engine.

For direct JUnit Platform execution, use the standalone Console Launcher JAR, but only after test classes are compiled and their runtime dependencies are available. The Platform is the execution layer; Jupiter and Vintage are engines that discover and run Jupiter and JUnit 4 tests respectively. See the official JUnit User Guide for version-specific setup.

1. Identify the project and JUnit version

Start at the repository root and check which build files exist:

pom.xml usually indicates Maven.
build.gradle or build.gradle.kts usually indicates Gradle.
mvnw / mvnw.cmd or gradlew / gradlew.bat is the project wrapper.

Prefer the wrapper when it is present. It selects the project’s Maven or Gradle distribution, while the project still needs a compatible Java runtime. Check java -version and inspect the build file or dependency report to identify the JUnit major version and engine.

JUnit 6 requires Java 17 or newer. That requirement does not automatically apply to JUnit 5 projects; use the project’s declared JUnit version and Java toolchain. JUnit artifacts should be version-aligned, commonly with the JUnit BOM. Spring Boot projects often have JUnit versions managed by Spring Boot, so check that setup before adding another BOM. See the JUnit Maven build support and Gradle build support guidance.

2. Run the whole test suite with Maven

From the directory containing pom.xml, run:

./mvnw test

If the wrapper is missing but Maven is installed:

mvn test

On Windows, run mvnw.cmd test from Command Prompt or PowerShell, or mvn test when Maven is installed. Maven’s Surefire plugin runs tests in the test phase; integration tests may be bound to a later phase or handled by Failsafe, depending on the project. Check the project’s plugin configuration before assuming test includes every integration test.

Run one Maven test class or method

Surefire commonly supports selecting a class with -Dtest:

./mvnw -Dtest=MyTest test

For a method, a common Surefire pattern is:

./mvnw -Dtest=MyTest#myTestMethod test

Selection details depend on the Surefire version and project configuration. If a selector finds nothing, verify the class name, package, test naming conventions, and plugin version; consult the official Surefire single-test documentation.

3. Run the whole test suite with Gradle

From the project root, run:

./gradlew test

Without a wrapper, use gradle test. On Windows, use gradlew.bat test or the installed gradle test.

For Jupiter or other JUnit Platform tests, the Gradle test task must use the Platform and a test engine must be on the test runtime classpath. Groovy DSL in build.gradle:

tasks.test {
    useJUnitPlatform()
}

Kotlin DSL in build.gradle.kts:

tasks.test {
    useJUnitPlatform()
}

The task syntax is the same in these examples; dependency declarations and other build configuration differ between Groovy and Kotlin DSL. Check the build file for the project’s actual test dependencies and toolchain.

Run selected tests with Gradle

Gradle can filter tests by class or method using the test task’s filter options. For example, pass a test name pattern:

./gradlew test --tests 'com.example.MyTest'
./gradlew test --tests 'com.example.MyTest.myTestMethod'

Quote patterns so the shell does not interpret special characters. For tags or engine selection, configure useJUnitPlatform in the build script and use the corresponding Platform options supported by the project’s Gradle version. Refer to the official Gradle testing documentation for the exact filter syntax and configuration.

4. Run tests with the standalone JUnit Console Launcher

Use this route when you need to invoke the JUnit Platform directly, such as in a small setup without a Maven or Gradle test task. The standalone JAR bundles the Console Launcher’s own dependencies; it does not compile your project or include your application’s test runtime dependencies.

Download the standalone artifact that matches the project’s JUnit Platform version from the official Console Launcher guide. Replace the placeholder below with that aligned version. Compile the test classes first and include their output directories and any required application or test libraries in the classpath.

java -jar junit-platform-console-standalone-<aligned-version>.jar execute --scan-classpath

Select one test class explicitly to distinguish a selector or classpath problem from a scanning problem:

java -jar junit-platform-console-standalone-<aligned-version>.jar execute \
  --select-class com.example.MyTest

When using the JAR to launch tests compiled elsewhere, a classpath must be provided. For a Unix-like shell, a basic example is:

java -jar junit-platform-console-standalone-<aligned-version>.jar execute \
  --class-path 'target/test-classes:target/classes:path/to/dependency.jar' \
  --scan-classpath

Replace the example paths and add every required runtime dependency. On Windows, Java classpaths use semicolons rather than colons, and PowerShell or Command Prompt quoting may differ. Avoid copying the Unix classpath unchanged into a Windows shell.

The Console Launcher documents exit status 1 for a failed test or container. An empty discovery run can return 0 unless --fail-if-no-tests is used; with that option, no discovered tests returns 2. Use it in automation where an empty run must fail instead of looking successful. Check the current guide because launcher options can vary by version.

5. Configure the right engine and dependencies

JUnit Platform, Jupiter, and Vintage serve different roles:

JUnit Platform: the foundation used by build integrations and the Console Launcher to discover and execute tests.
Jupiter: the engine for JUnit Jupiter tests.
Vintage: the engine that lets JUnit 4 tests run on the JUnit Platform.

A build can compile test source yet discover no tests if the needed engine is absent from the test runtime classpath. Jupiter tests need the Jupiter engine. JUnit 4 tests run through Platform-based execution need JUnit 4 and the Vintage engine. Align related JUnit artifacts with the JUnit BOM unless a framework such as Spring Boot already manages those versions. Avoid mixing arbitrary versions of Platform, Jupiter, and Vintage.

6. Troubleshooting: command runs but tests do not

Symptom	Likely cause	What to check or change
`mvn` or `gradle` is not found	The tool is not installed or is not on PATH.	Use the repository wrapper if present: `./mvnw`, `./gradlew`, `mvnw.cmd`, or `gradlew.bat`.
Build succeeds but reports zero tests	Wrong source directory or naming, an active filter excludes tests, scanning uses the wrong classpath, or no test engine is available.	Run from the repository root; inspect test source sets, class and method names, build filters, and test runtime dependencies. With the Console Launcher, try `--select-class` and then correct the scan or classpath.
JUnit 4 tests are missing from Platform execution	The Vintage engine is missing.	Add a compatible Vintage engine to test runtime dependencies and align it with the project’s JUnit Platform version.
Jupiter tests compile but are not discovered	The Jupiter engine may be absent, or Gradle may not be configured for the JUnit Platform.	Ensure the engine is on the test runtime classpath and, for Gradle, configure `useJUnitPlatform()`.
Unsupported Java version or class-file error	The Java runtime launching the tests is older than the project or JUnit version requires.	Check `java -version`, the configured toolchain, and the JUnit major version. JUnit 6 requires Java 17 or newer.
Dependency resolution or linkage errors	Conflicting JUnit versions or incomplete runtime dependencies.	Inspect dependency management, align JUnit artifacts with the BOM, or use the versions managed by Spring Boot. For direct launcher use, include project dependencies in the classpath.
Console Launcher cannot load a selected class	The class is not compiled, its package name is wrong, or its output directory is missing from the classpath.	Compile tests first, use the fully qualified class name, and add test and main output directories plus non-JUnit dependencies.
Tests pass locally but not in CI	CI may use a different working directory, JDK, environment, or build configuration.	Use the project wrapper, print the Java version in the job log, run from the repository root, and check environment-dependent test setup and filters.

7. Performance, reliability, and cost

There is no universally fastest command: Maven, Gradle, and direct launcher execution depend on the project’s compilation, dependency resolution, test setup, and configuration. The wrapper is usually the most reproducible entry point for a repository because it selects the declared build-tool distribution. Build caches and parallel execution can change behavior and should be configured deliberately; do not assume a faster run has executed the same work. For reliable automation, use a nonzero failure status and make empty test discovery fail where appropriate, for example with the Console Launcher’s --fail-if-no-tests. Java, JUnit, Maven, and Gradle are software tools; this workflow has no required ScreenshotNeo purchase or paid dependency.

8. A compact CI checklist

Run from the repository root.
Use the checked-in wrapper where available.
Confirm the CI JDK satisfies the project toolchain and JUnit version.
Confirm the expected engine is present: Jupiter for Jupiter tests, Vintage for JUnit 4 on the Platform.
Check that no command-line or build-script filter excludes tests.
Make an empty discovery result fail when that would otherwise produce a false green.
Keep dependency versions under the project’s BOM or framework dependency management.

Or skip the browser setup

For a different developer task—capturing a website screenshot from a terminal or script—ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF. Use the API documentation for the available parameters and formats.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides screenshot tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.

FAQ

Can I run a JUnit test without Maven or Gradle?

Yes. Use the standalone JUnit Console Launcher, provided the test classes are already compiled and the complete runtime classpath is available.

Why did an empty test run exit successfully?

Some discovery setups treat zero tests as a successful run. For direct Console Launcher use, --fail-if-no-tests makes empty discovery return a failure status.

Do JUnit 5 tests need Java 17?

Not solely because they use JUnit 5. Java 17 is the minimum for JUnit 6; check the project’s own JUnit version and Java toolchain requirements.