/commands/gradle/gradle-run-single-test
gradle test --tests: run a single test class or method with Gradle
- tool
- Gradle
- versions
- Gradle 7.x, Gradle 8.x, Gradle 9.x
- os
- any
./gradlew test --tests com.acme.OrderServiceTest runs only that test class, and --tests 'com.acme.OrderServiceTest.createsOrder' only one method. The value is a filter on the fully qualified name; * works as a wildcard, a pattern that starts with an upper-case letter matches a simple class name in any package, and the option can be given several times. Use the Gradle wrapper (./gradlew, gradlew.bat on Windows) so the project's Gradle version is used.
Usage
./gradlew test --tests com.acme.OrderServiceTest # one class
./gradlew test --tests 'com.acme.OrderServiceTest.createsOrder' # one method
./gradlew test --tests 'com.acme.OrderServiceTest.creates*' # methods by pattern
./gradlew test --tests '*ServiceTest' # classes by pattern
./gradlew test --tests OrderServiceTest # simple class name, any package
./gradlew test --tests '*Order*' --tests '*Payment*' # several filters
./gradlew :service:test --tests '*OrderServiceTest' # one subproject only
./gradlew test --tests '*OrderServiceTest' --rerun # run again even if up to dateQuote patterns with * so the shell does not expand them against files in the current folder. The filter matches method names, not JUnit 5 display names; Kotlin test methods whose names contain spaces (backtick names) need quotes too.
Filter forms
| --tests value | Runs |
|---|---|
| com.acme.OrderServiceTest | Every test in that class |
| com.acme.OrderServiceTest.createsOrder | One method |
| com.acme.* | Every class in the package and its subpackages |
| *ServiceTest | Classes whose name ends with ServiceTest, in any package |
| OrderServiceTest | Simple class name (starts with upper case), any package |
| *OrderServiceTest.creates* | Methods starting with creates in matching classes |
| '*Test.test with spaces' | A method name containing spaces, quoted |
Pitfalls
- No match fails the build. When
--testsselects nothing, the task fails withNo tests found for given includes. In a multi-project build, run the task of the right subproject instead ofteston all of them, or setfilter.failOnNoMatchingTests = falsein the build script. - Up-to-date checks. Gradle may skip the task when nothing changed.
--rerunreruns just that task;--rerun-tasksreruns every task in the build and is slower. - Other test tasks.
--testsapplies to the task it follows. Integration tests in a separate task (for exampleintegrationTest) need./gradlew integrationTest --tests .... - JUnit 5 not configured. If no test ever runs, the test task probably lacks
useJUnitPlatform(); Gradle then looks for JUnit 4 tests only. - Skipping tests entirely is a different task option: see gradle build without tests.
How to confirm it worked
The HTML report in build/reports/tests/test/index.html lists the classes and methods that ran, and ./gradlew test --tests ... --info prints each test as it executes. With --console=plain, the end of the output shows the test task result and any failures.
FAQ
Why does Gradle say No tests found for given includes?
The filter matched nothing in that test task. Check the fully qualified class name, quote patterns with * or spaces, and in a multi-project build run the filter on the right project, for example ./gradlew :service:test --tests ...
Why did nothing run the second time?
The test task was up to date: same code, same filter, so Gradle reused the previous result. Add --rerun (Gradle 7.6+) or --rerun-tasks to force it.
How do I run tests with a JUnit tag?
Tags are not selected with --tests. Configure useJUnitPlatform { includeTags 'fast' } in the build script, often driven by a project property, and run ./gradlew test -PincludeTags=fast with matching logic in the script.