From the root of an existing project, run its build wrapper: ./mvnw test for Maven or ./gradlew test for Gradle. On Windows, use mvnw.cmd test or gradlew.bat test. These commands use the project’s build configuration to compile and run its tests. If you need to launch JUnit directly, use the JUnit Platform Console Launcher, provided the test classes are already compiled and the runtime classpath is complete.
Choose the command for your project
Run commands from the repository root. Prefer the wrapper included with the project: it selects the build-tool distribution expected by that repository. If there is no wrapper, use the installed build tool instead.
| Route | Best fit | Typical command | What must be configured |
|---|---|---|---|
| Maven | An existing Maven project | ./mvnw test |
Maven test execution support and the appropriate JUnit engine dependencies |
| Gradle | An existing Gradle project | ./gradlew test |
The test task must use the JUnit Platform for Platform/Jupiter tests, and an engine must be on the test runtime classpath |
| Console Launcher | Direct Platform invocation, such as when there is no build task | java -jar junit-platform-console-standalone-<aligned-version>.jar execute ... |
Compiled test classes and their complete runtime classpath |
None of these routes is universally faster or better. Use the existing build system when it is configured; choose the Console Launcher when direct Platform execution or explicit test selectors suit the task. The JUnit build support guide documents Maven and Gradle support.
Run tests with Maven
- Open a terminal at the project root.
- Run
./mvnw teston macOS or Linux, ormvnw.cmd teston Windows. - If there is no Maven wrapper, run
mvn testinstead, assuming Maven is installed and available on your PATH.
Maven Surefire and Failsafe support JUnit Platform execution. The test dependency and plugin configuration must still be compatible with the project’s JUnit version. For test-scoped Jupiter dependencies and version alignment, see the JUnit build support guide. JUnit 6 needs a compatible Surefire or Failsafe release; consult the current build-support documentation rather than copying an arbitrary plugin version.
#1 Best Overall
Run one Maven test class
For Maven Surefire, a common class-selection command is ./mvnw -Dtest=MyTest test; on Windows, use mvnw.cmd -Dtest=MyTest test. Replace MyTest with the test class name. This filtering behavior depends on the Surefire version and project configuration. If it does not select the intended test, check the project’s Surefire documentation and configuration.
Run tests with Gradle
- From the project root, run
./gradlew teston macOS or Linux, orgradlew.bat teston Windows. - If the wrapper is absent, run
gradle testif Gradle is installed. - Review the task output for test discovery and failures. Gradle’s
testtask must be configured for the JUnit Platform when running Jupiter or other Platform tests.
In a Groovy DSL build.gradle, the usual Platform configuration is:
test {
useJUnitPlatform()
}For a Kotlin DSL build.gradle.kts, use Kotlin syntax instead:
Rank #2
tasks.test {
useJUnitPlatform()
}The test engine must also be available on the test runtime classpath. Gradle’s useJUnitPlatform configuration can further filter by tags or engines; see the JUnit build support guide for build support details.
Run tests directly with the JUnit Console Launcher
The Console Launcher is an executable Java application for launching the JUnit Platform from a terminal. The JUnit guide describes its standalone JAR as a fat JAR containing the launcher’s dependencies. It is not a compiler: compile the project’s tests first, and make the compiled classes and any application or third-party runtime dependencies available to the launch.
- Obtain the standalone Console Launcher artifact whose version is aligned with the project’s JUnit dependencies. Check the Console Launcher guide for the current artifact and command format.
- Run it with Java to scan the classpath:
java -jar junit-platform-console-standalone-<aligned-version>.jar execute --scan-classpathTo select one test class rather than scan broadly:
java -jar junit-platform-console-standalone-<aligned-version>.jar execute --select-class com.example.MyTestReplace the example class name with the test’s fully qualified name. For tests outside the launcher JAR, supply the compiled test and application output directories and all other required runtime dependencies on the classpath. Classpath separators differ across operating systems, so use the syntax for your shell and OS rather than copying a Unix-like classpath into Windows unchanged.
The launcher reports a failing test or container with exit status 1. An empty discovery run returns 0 by default; with --fail-if-no-tests, it returns 2 when no tests are found. In automation, that option can prevent a scan of the wrong location from appearing successful. See the Console Launcher documentation for selectors and execution details.
Check the JUnit version, Java runtime, and engine
The JUnit Platform is the execution foundation, not itself the test API. Jupiter is the JUnit programming model and engine for modern JUnit tests; Vintage provides Platform execution for JUnit 4 tests. Confirm the project’s JUnit major version and runtime before troubleshooting a command.
- JUnit 6: JUnit 6.0 requires Java 17 or newer at runtime. The JUnit team’s 6.0.0 release notes, dated September 30, 2025, state this minimum. Do not apply the JUnit 6 requirement to every JUnit 5 project.
- Jupiter tests: ensure the Jupiter engine is present on the test runtime classpath.
- JUnit 4 tests on the Platform: include JUnit 4 and the Vintage engine on the test runtime classpath.
- Version alignment: align JUnit Platform, Jupiter, and Vintage artifacts, commonly with the JUnit BOM. If Spring Boot manages dependencies, check its dependency management before adding a second BOM.
For the official descriptions of the Platform, Jupiter, and Vintage, see the JUnit overview. Spring Boot’s JUnit dependency management is covered in the JUnit Spring Boot guide.
Rank #4
Troubleshoot command-line test runs
Command not found
Check the repository root for mvnw or gradlew. If a wrapper is present, run its OS-appropriate command. Without one, install or locate Maven or Gradle and confirm its executable is on PATH.
The build succeeds but says no tests were found
- Confirm the tests are in the build tool’s configured test source set or directory and that the class and method names match the project’s discovery conventions.
- Check build-tool filters for an incorrect class, tag, or engine selection.
- Confirm that compiled test classes and the required engine are available at runtime.
- For a direct Console Launcher run, try
--select-classwith a fully qualified test class name. If that works, investigate classpath scanning or the scan location. - In automated Console Launcher runs, consider
--fail-if-no-testsso empty discovery does not return a default success status.
JUnit 4 tests are missing from a Platform run
Add or restore the Vintage engine in the test runtime dependencies, alongside JUnit 4. The Platform does not run JUnit 4 tests through Jupiter. See the JUnit guide’s JUnit 4 migration and Vintage guidance.
Java version error
Check the Java runtime actually used by the command with java -version, then compare it with the project’s configured toolchain and JUnit major version. For JUnit 6, the runtime minimum is Java 17.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
Dependency conflicts
Inspect the resolved test dependencies and align JUnit components with the JUnit BOM, unless a framework such as Spring Boot already manages those versions. Avoid mixing mismatched Platform, Jupiter, and Vintage versions.
Console Launcher cannot load a test
Verify that the test has been compiled, its output directory is on the runtime classpath, and application or third-party dependencies required by the test are also present. The standalone JAR bundles the launcher’s dependencies, not the arbitrary dependencies of your project.
Or skip the browser setup
This guide is about Java tests, not website screenshots. If you also need a screenshot from a command line or AI workflow, ScreenshotNeo is a website screenshot API and MCP server. It takes a URL in one GET request and returns an image or PDF. One-call cURL example (see the ScreenshotNeo API docs):
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
Recommended Free Tools
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
