# Interface TestSpec

@Incubating public interface TestSpec
Provides infrastructure to select which test classes, methods, and packages will be included in the test execution.

A complex example:

    TestLauncher testLauncher = projectConnection.newTestLauncher();
    testLauncher.withTestsFor(specs -> {
        specs.forTaskPath(":test")                                    // configure the test selection on the ':test' task
             .includePackage("org.pkg")                               // execute all tests declared the org.pkg package and its sub-packages
             .includeClass("com.MyTest")                              // execute the MyTest test class
             .includeMethod("com.OtherTest", Arrays.asList("verify")) // execute the OtherTest.verify() test method
             .includePattern("io.*")                                  // execute all tests matching to io.*
    }).run();

All methods on this interface (including the class and method selection) support patterns as arguments. The patterns follow the rules of test filtering.

The test execution will fail if any of the selected classes, methods, or patters have no matching tests.

Since:
  7.6

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TestSpec`
  `includeClass(String cls)`
  Adds the target test class to the test execution.
  `TestSpec`
  `includeClasses(Collection<String> classes)`
  Adds the target test classes to the test execution.
  `TestSpec`
  `includeMethod(String cls, String method)`
  Adds the target test method to the test execution.
  `TestSpec`
  `includeMethods(String cls, Collection<String> methods)`
  Adds the target test methods to the test execution.
  `TestSpec`
  `includePackage(String pkg)`
  Adds all tests declared in the target package to the test execution.
  `TestSpec`
  `includePackages(Collection<String> packages)`
  Adds all tests declared in the target packages to the test execution.
  `TestSpec`
  `includePattern(String pattern)`
  Adds all tests to the execution that matches the target pattern.
  `TestSpec`
  `includePatterns(Collection<String> patterns)`
  Adds all tests to the execution that matches the target patterns.

- ## Method Details

  - ### includePackage

    TestSpec includePackage(String pkg)
    Adds all tests declared in the target package to the test execution.

    The effect is recursive, meaning that the tests defined in sub-packages will also be executed.

    Parameters:
      `pkg` - The target package.
    Returns:
      this
    Since:
      7.6

  - ### includePackages

    TestSpec includePackages(Collection<String> packages)
    Adds all tests declared in the target packages to the test execution.
    Parameters:
      `packages` - The target packages.
    Returns:
      this
    Since:
      7.6
    See Also:
      - `includePackage(String)`

  - ### includeClass

    TestSpec includeClass(String cls)
    Adds the target test class to the test execution.

    The target class should be selected with its fully-qualified name.

    Parameters:
      `cls` - The fully-qualified name of the target class.
    Returns:
      this
    Since:
      7.6

  - ### includeClasses

    TestSpec includeClasses(Collection<String> classes)
    Adds the target test classes to the test execution.
    Parameters:
      `classes` - The fully-qualified name of the target classes.
    Returns:
      this
    Since:
      7.6
    See Also:
      - `includeClass(String)`

  - ### includeMethod

    TestSpec includeMethod(String cls, String method)
    Adds the target test method to the test execution.

    The target method should be selected with its fully-qualified class name and with the name of the method.

    Parameters:
      `cls` - The fully-qualified name of the class containing the method.
      `method` - The name of the target method.
    Returns:
      this
    Since:
      7.6

  - ### includeMethods

    TestSpec includeMethods(String cls, Collection<String> methods)
    Adds the target test methods to the test execution.
    Parameters:
      `cls` - The fully-qualified name of the class containing the method.
      `methods` - The name of the target methods.
    Returns:
      this
    Since:
      7.6
    See Also:
      - `includeMethod(String, String)`

  - ### includePattern

    TestSpec includePattern(String pattern)
    Adds all tests to the execution that matches the target pattern.

    The patterns follow the rules of test filtering.

    Parameters:
      `pattern` - the pattern to select tests.
    Returns:
      this
    Since:
      7.6

  - ### includePatterns

    TestSpec includePatterns(Collection<String> patterns)
    Adds all tests to the execution that matches the target patterns.
    Parameters:
      `patterns` - the patterns to select tests.
    Returns:
      this
    Since:
      7.6
    See Also:
      - `includePattern(String)`