skip to content

--tests Filter

4 roadmaps5 questions

Running a single class or method from the command line with wildcard patterns. Asked because it is the tightest local iteration loop Gradle offers.

on this pageshow

explore

questions

5

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…

open as a page

How do wildcard patterns work with Gradle's `--tests` flag, and what can you match with them?

level: middleimportance: must knowfreq 55%

basics

~10 s

The * wildcard matches any sequence of characters. So --tests 'com.example.*Test' runs all classes in com.example ending in Test, and --tests '*OrderTest.should*' runs methods starting with should.

open as a page

In a multi-module build with a custom `integrationTest` task, how do you use `--tests` correctly, and what pitfalls arise?

level: middleimportance: should knowfreq 40%

basics

~10 s

Attach --tests to the specific Test task you mean: ./gradlew integrationTest --tests 'com.example.FooIT'. In multi-module builds, also scope by project path (e.g. :app:test) so only the right module's task gets the filter.

open as a page

When is `--tests` the right tool versus committed filter configuration or test-suite splitting, and how does that shape a team's local-vs-CI test strategy?

level: seniorimportance: should knowfreq 25%

basics

~20 s

--tests is a transient, local-iteration tool you type by hand to run a focused subset. Durable selection (which suites run, tags, splits) belongs in the build script or CI config, not in an ad-hoc CLI flag.

open as a page

A developer runs `./gradlew test --tests 'com.example.FooTest'` twice and the second run reports UP-TO-DATE without executing the test. Why, and how do they force it to run?

level: seniorimportance: should knowfreq 35%

basics

~10 s

The test task is up-to-date because no inputs changed, so Gradle skips it. Force a re-run with --rerun-tasks (or cleanTest, or in newer Gradle the task's --rerun option).

open as a page