gradle test: Run the Test Task with Filters
gradle test runs the unit-test suite of the test source set; --tests filters which tests run and --fail-fast stops at the first failure.
test is the task CI runs most. The two flags worth memorizing are --tests for targeting a class or method and --fail-fast for quick feedback.
What it does
The test task compiles the test source set and runs it with the configured engine (JUnit Platform, JUnit 4, or TestNG). It writes results to build/test-results and an HTML report to build/reports/tests. It is up-to-date if nothing changed, so unchanged code is not re-tested.
Common usage
./gradlew test
./gradlew test --tests "com.acme.UserServiceTest"
./gradlew test --tests "*.UserServiceTest.shouldCreate*"
./gradlew test --fail-fastFlags
| Flag | What it does |
|---|---|
| --tests <pattern> | Run only matching test classes/methods (wildcards allowed) |
| --fail-fast | Abort the task on the first failing test |
| --rerun | Re-run even if the task is up-to-date |
| -x test | Exclude tests from a larger invocation |
| --info | Log each test as it runs |
In CI
For flaky-test isolation use --tests to re-run one class. Set maxParallelForks in the test block (often to the number of vCPUs) to parallelize. Always publish build/reports/tests as an artifact so failures are inspectable after the runner is gone.
Common errors in CI
"Execution failed for task ':test'. > There were failing tests." points to the HTML report. "No tests found for given includes" means the --tests pattern matched nothing (check the package). "Test process 'Gradle Test Executor N' finished with non-zero exit value 137" is an OOM-killed worker; raise the heap in test { jvmArgs }. "Could not resolve org.junit..." is a missing test dependency.