skip to content

How do you run a single test class or a single test method from the command line with Gradle?

level: juniorimportance: must knowfreq 70%

answer

  1. `--tests` on the Test task
  2. FQN for class, Class.method for method
  3. repeatable = OR
  4. quote to protect wildcards
  5. sugar over filter{} block

basics

~10 s

Use the --tests flag on the test task: ./gradlew test --tests 'com.example.MyTest' runs one class, and ./gradlew test --tests 'com.example.MyTest.myMethod' runs one method.

solid answer

~30 s

Gradle's `Test` task accepts a `--tests` command-line option that filters which tests execute. You pass a fully-qualified class name to run a single class, or `Class.method` to run a single method. For example `./gradlew test --tests 'com.example.OrderServiceTest'` or `./gradlew test --tests 'com.example.OrderServiceTest.placesOrder'`. The pattern is matched against the test class's fully-qualified name and the method name. The flag is repeatable — passing several `--tests` options is an OR (any matching test runs). It works during local iteration to avoid running the whole suite. Quoting the argument protects wildcards and special characters from the shell.

code

bash · 8 lines
bash
# single class
./gradlew test --tests 'com.example.OrderServiceTest'

# single method
./gradlew test --tests 'com.example.OrderServiceTest.placesOrder'

# multiple (OR)
./gradlew test --tests 'com.example.FooTest' --tests 'com.example.BarTest'

go deeper

for a junior

Recall the exact syntax: --tests 'FQN' for a class and --tests 'FQN.method' for a method.

for a middle

Mention it's repeatable (OR), targets a specific Test task, and is sugar over the filter{} block.

for a senior

Explain matching is against the FQN/method name and relate it to includeTestsMatching plus empty-match failure behavior.

for a principal

Frame it as a developer-iteration affordance vs. CI-level selection strategy and where committed filters belong instead.

## What `--tests` does Gradle's built-in `Test` task (the `test` task created by the `java`/`kotlin` plugins) wraps a JVM test engine (JUnit Platform, JUnit 4, or TestNG). When you run `./gradlew test`, every discovered test runs. The `--tests` command-line option lets you narrow that set for fast local feedback. ## Syntax - **Single class:** `./gradlew test --tests 'com.example.OrderServiceTest'` - **Single method:** `./gradlew test --tests 'com.example.OrderServiceTest.placesOrder'` - **Repeatable (OR):** `./gradlew test --tests 'a.FooTest' --tests 'b.BarTest'` The value before the last dot is treated as the class's fully-qualified name; the segment after it (when it isn't part of a package/class) is the method name. Patterns are matched against the **fully-qualified class name** and the **method name**, not the file path. ## Why quote it The argument can contain `*` wildcards and `.` separators. Wrapping it in single quotes prevents your shell (bash/zsh) from glob-expanding `*` against files in the current directory before Gradle ever sees the string. ## Relationship to `test.filter` The CLI flag is sugar over the same machinery as the build-script `test { filter { includeTestsMatching(...) } }` block. The CLI option is **additive over any include patterns** already configured and is meant for transient, local runs — you don't commit it. ```bash # run one class ./gradlew test --tests 'com.example.OrderServiceTest' # run one method ./gradlew test --tests 'com.example.OrderServiceTest.placesOrder' ``` ## Gotchas - If nothing matches, the run can **fail** with "No tests found for given includes" unless you allow empty matching. - The flag targets a specific `Test` task; if you have multiple test tasks (e.g. `integrationTest`), name that task instead: `./gradlew integrationTest --tests '...'`.

  • What does the pattern match against — the file name or the class name?
    The fully-qualified class name and the method name, not the source file path. So a test in `src/test/kotlin/.../OrderServiceTest.kt` is matched as `com.example.OrderServiceTest`.
  • What happens if you pass two --tests options?
    They are combined as a logical OR: any test matching any of the supplied patterns runs.

saying these in an interview costs you the question

  • Saying you pass the file path or .kt/.java file name instead of the FQN.
  • Claiming --tests can only run a whole class and never a single method.

context

resolving links…