Package org.gradle.api.tasks.testing

# Interface TestFilter

public interface TestFilter
Allows filtering tests for execution. Class-based and non-class-based tests are filtered using the same selection logic. Classes can be selected by their simple, fully qualified names or partial matches on class name or package. Methods can be selected by their full names, containing class or partial matches. Non-class-based tests are converted to package-like names using the relative path from their test definition directory. Some examples:

       apply plugin: 'java'

       test {
           filter {
              //specific test class, this can match 'SomeTest' class and corresponding method under any package
              includeTestsMatching("SomeTest")
              includeTestsMatching("SomeTest.someTestMethod*")

              //specific test class
              includeTestsMatching("org.gradle.SomeTest")

              //specific test class and method
              includeTestsMatching("org.gradle.SomeTest.someSpecificFeature")
              includeTest("org.gradle.SomeTest", "someTestMethod")

              //specific test method, use wildcard
              includeTestsMatching("*SomeTest.someSpecificFeature")

              //specific test class, wildcard for packages
              includeTestsMatching("*.SomeTest")

              //all classes in package, recursively
              includeTestsMatching("com.gradle.tooling.*")

              //all integration tests, by naming convention
              includeTestsMatching("*IntegTest")

              //only ui tests from integration tests, by some naming convention
              includeTestsMatching("*IntegTest*ui")

              //exclude a specific test by its name
              excludeTestsMatching("*canDoSomethingSpecific")
              //excluding tests by name also works for test names which have spaces
              excludeTestsMatching("*can do something specific")
           }
       }

Since:
  1.10 General information about filtering. Special notes about filtering non-class-based tests.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TestFilter`
  `excludeTest(String className, String methodName)`
  Excludes a test method specified by test class name and method name.
  `TestFilter`
  `excludeTestsMatching(String testNamePattern)`
  Appends a test name pattern to the exclusion filter.
  `SetProperty<String>`
  `getExcludePatterns()`
  Returns the excluded test name patterns.
  `Property<Boolean>`
  `getFailOnNoMatchingTests()`
  Defines whether the task should fail if no matching tests where found.
  `SetProperty<String>`
  `getIncludePatterns()`
  Returns the included test name patterns.
  `default Property<Boolean>`
  `getIsFailOnNoMatchingTests()`
  Used for Kotlin source compatibility.
  `TestFilter`
  `includeTest(String className, String methodName)`
  Add a test method specified by test class name and method name.
  `TestFilter`
  `includeTestsMatching(String testNamePattern)`
  Appends a test name pattern to the inclusion filter.
  `TestFilter`
  `setExcludePatterns(String... excludePatterns)`
  Sets the test name patterns to be excluded in the filter.
  `void`
  `setFailOnNoMatchingTests(boolean failOnNoMatchingTests)`
  Let the test task fail if a filter configuration was provided but no test matched the given configuration.
  `TestFilter`
  `setIncludePatterns(String... includePatterns)`
  Sets the test name patterns to be included in the filter.

- ## Method Details

  - ### includeTestsMatching

    TestFilter includeTestsMatching(String testNamePattern)
    Appends a test name pattern to the inclusion filter. Wildcard '*' is supported, either test method name or class name is supported. Examples of test names: "com.foo.FooTest.someMethod", "com.foo.FooTest", "*FooTest*", "com.foo*". See examples in the docs for `TestFilter`.
    Parameters:
      `testNamePattern` - test name pattern to include, can be class or method name, can contain wildcard '*'
    Returns:
      this filter object

  - ### excludeTestsMatching

    TestFilter excludeTestsMatching(String testNamePattern)
    Appends a test name pattern to the exclusion filter. Wildcard '*' is supported, either test method name or class name is supported. Examples of test names: "com.foo.FooTest.someMethod", "com.foo.FooTest", "*FooTest*", "com.foo*", "*someTestMethod". See examples in the docs for `TestFilter`.
    Parameters:
      `testNamePattern` - test name pattern to exclude, can be class or method name, can contain wildcard '*'
    Returns:
      this filter object
    Since:
      5.0

  - ### getIncludePatterns

    @Input SetProperty<String> getIncludePatterns()
    Returns the included test name patterns. They can be class or method names and may contain wildcard '*'.
    Returns:
      included test name patterns

  - ### setIncludePatterns

    TestFilter setIncludePatterns(String... includePatterns)
    Sets the test name patterns to be included in the filter. Wildcard '*' is supported. Replaces any existing test name patterns.
    Parameters:
      `includePatterns` - class or method name patterns to set, may contain wildcard '*'
    Returns:
      this filter object

  - ### getExcludePatterns

    @Input SetProperty<String> getExcludePatterns()
    Returns the excluded test name patterns. They can be class or method names and may contain wildcard '*'.
    Returns:
      included test name patterns
    Since:
      5.0

  - ### setExcludePatterns

    TestFilter setExcludePatterns(String... excludePatterns)
    Sets the test name patterns to be excluded in the filter. Wildcard '*' is supported. Replaces any existing test name patterns.
    Parameters:
      `excludePatterns` - class or method name patterns to set, may contain wildcard '*'
    Returns:
      this filter object
    Since:
      5.0

  - ### includeTest

    TestFilter includeTest(String className, String methodName)
    Add a test method specified by test class name and method name.
    Parameters:
      `className` - the class name of the test to execute
      `methodName` - the method name of the test to execute. Can be null.
    Returns:
      this filter object

  - ### excludeTest

    TestFilter excludeTest(String className, String methodName)
    Excludes a test method specified by test class name and method name.
    Parameters:
      `className` - the class name of the test to exclude
      `methodName` - the method name of the test to exclude. Can be null.
    Returns:
      this filter object
    Since:
      5.0

  - ### getFailOnNoMatchingTests

    @Input Property<Boolean> getFailOnNoMatchingTests()
    Defines whether the task should fail if no matching tests where found. The default is true.

  - ### setFailOnNoMatchingTests

    void setFailOnNoMatchingTests(boolean failOnNoMatchingTests)
    Let the test task fail if a filter configuration was provided but no test matched the given configuration.
    Parameters:
      `failOnNoMatchingTests` - whether a test task should fail if no test is matching the filter configuration.

  - ### getIsFailOnNoMatchingTests

    @Internal default Property<Boolean> getIsFailOnNoMatchingTests()
    Used for Kotlin source compatibility. use `getFailOnNoMatchingTests()` instead.