Package org.gradle.tooling

## Interface TestLauncher

- All Superinterfaces:
    `ConfigurableLauncher<TestLauncher>`, `LongRunningOperation`

      public interface TestLauncher
      extends ConfigurableLauncher<TestLauncher>

  A `TestLauncher` allows you to execute tests in a Gradle build.

  If the target Gradle version is >=6.8 then you can use `TestLauncher` to execute tests from included builds. Test operation descriptors from included builds work out-of-the-box. You can target tasks from included builds by specifying the task identity path (i.e. `':included-build-name:subproject-name:taskName'`).

  However, you cannot use the methods with included builds that don't specify the target test tasks (e.g. `withJvmTestClasses()` and `withJvmTestMethods()`). Those methods configure all test tasks in the root build only.

  Since:
    2.6

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `TestLauncher` | `debugTestsOn​(int port)` | Configures test JVM to run in debug mode.
    `TestLauncher` | `forTasks​(java.lang.String... tasks)` | Sets the tasks to be executed.
    `void` | `run()` | Executes the tests, blocking until complete.
    `void` | `run​(ResultHandler<? super java.lang.Void> handler)` | Starts executing the tests.
    `TestLauncher` | `withJvmTestClasses​(java.lang.Iterable<java.lang.String> testClasses)` | Adds tests to be executed declared by class name.
    `TestLauncher` | `withJvmTestClasses​(java.lang.String... testClasses)` | Adds tests to be executed declared by class name.
    `TestLauncher` | `withJvmTestMethods​(java.lang.String testClass, java.lang.Iterable<java.lang.String> methods)` | Adds tests to be executed declared by class and methods name.
    `TestLauncher` | `withJvmTestMethods​(java.lang.String testClass, java.lang.String... methods)` | Adds tests to be executed declared by class and method name.
    `TestLauncher` | `withTaskAndTestClasses​(java.lang.String task, java.lang.Iterable<java.lang.String> testClasses)` | Adds tests to be executed declared by the container task and the class name.
    `TestLauncher` | `withTaskAndTestMethods​(java.lang.String task, java.lang.String testClass, java.lang.Iterable<java.lang.String> methods)` | Adds tests to be executed declared by the container task, class and method name.
    `TestLauncher` | `withTests​(java.lang.Iterable<? extends TestOperationDescriptor> descriptors)` | Adds tests to be executed by passing test descriptors received from a previous Gradle Run.
    `TestLauncher` | `withTests​(TestOperationDescriptor... descriptors)` | Adds tests to be executed by passing test descriptors received from a previous Gradle Run.
    `TestLauncher` | `withTestsFor​(Action<TestSpecs> testSpec)` | Adds tests to be executed declared using a fine-grained test selection API.

    - ### Methods inherited from interface org.gradle.tooling.ConfigurableLauncher

      `addArguments, addArguments, addJvmArguments, addJvmArguments, addProgressListener, addProgressListener, addProgressListener, addProgressListener, setColorOutput, setEnvironmentVariables, setJavaHome, setJvmArguments, setJvmArguments, setStandardError, setStandardInput, setStandardOutput, withArguments, withArguments, withCancellationToken, withSystemProperties`

- - ### Method Detail

    - #### withTests

          TestLauncher withTests​(TestOperationDescriptor... descriptors)

      Adds tests to be executed by passing test descriptors received from a previous Gradle Run.
      Parameters:
        `descriptors` - The OperationDescriptor defining one or more tests.
      Returns:
        this
      Since:
        2.6

    - #### withTests

          TestLauncher withTests​(java.lang.Iterable<? extends TestOperationDescriptor> descriptors)

      Adds tests to be executed by passing test descriptors received from a previous Gradle Run.
      Parameters:
        `descriptors` - The OperationDescriptor defining one or more tests.
      Returns:
        this
      Since:
        2.6

    - #### withJvmTestClasses

          TestLauncher withJvmTestClasses​(java.lang.String... testClasses)

      Adds tests to be executed declared by class name.

      This method ignores tests defined in included builds.

      Parameters:
        `testClasses` - The class names of the tests to be executed.
      Returns:
        this
      Since:
        2.6

    - #### withJvmTestClasses

          TestLauncher withJvmTestClasses​(java.lang.Iterable<java.lang.String> testClasses)

      Adds tests to be executed declared by class name.

      This method ignores tests defined in included builds.

      Parameters:
        `testClasses` - The class names of the tests to be executed.
      Returns:
        this
      Since:
        2.6

    - #### withJvmTestMethods

          TestLauncher withJvmTestMethods​(java.lang.String testClass,
                                          java.lang.String... methods)

      Adds tests to be executed declared by class and method name.

      This method ignores tests defined in included builds.

      Parameters:
        `testClass` - The name of the class containing the methods to execute.
        `methods` - The names of the test methods to be executed.
      Returns:
        this
      Since:
        2.7

    - #### withJvmTestMethods

          TestLauncher withJvmTestMethods​(java.lang.String testClass,
                                          java.lang.Iterable<java.lang.String> methods)

      Adds tests to be executed declared by class and methods name.

      This method ignores tests defined in included builds.

      Parameters:
        `testClass` - The name of the class containing the methods to execute.
        `methods` - The names of the test methods to be executed.
      Returns:
        this
      Since:
        2.7

    - #### withTaskAndTestClasses

          TestLauncher withTaskAndTestClasses​(java.lang.String task,
                                              java.lang.Iterable<java.lang.String> testClasses)

      Adds tests to be executed declared by the container task and the class name.

      Note: These tests are ignored for target Gradle version earlier than 6.1

      Parameters:
        `task` - The path of the target task.
        `testClasses` - The class names of the tests to be executed.
      Returns:
        this
      Since:
        6.1

    - #### withTaskAndTestMethods

          TestLauncher withTaskAndTestMethods​(java.lang.String task,
                                              java.lang.String testClass,
                                              java.lang.Iterable<java.lang.String> methods)

      Adds tests to be executed declared by the container task, class and method name.

      Note: These tests are ignored for target Gradle version earlier than 6.1

      Parameters:
        `task` - The path of the target task.
        `testClass` - The name of the class containing the methods to execute.
        `methods` - The names of the test methods to be executed.
      Returns:
        this
      Since:
        6.1

    - #### debugTestsOn

          TestLauncher debugTestsOn​(int port)

      Configures test JVM to run in debug mode.

      When called, the forked test JVM is launched with the following argument:

          -agentlib:jdwp=transport=dt_socket,server=n,suspend=n,address=localhost:<port>

      This means the test JVM expects a debugger at the specified port that uses a socket listening connector. If the debugger is not present then the test execution will fail.

      Invoking this method adjusts the test task to launch only one JVM. More specifically, the parallel execution gets disabled and the `forkEvery` property is set to 0.

      Parameters:
        `port` - the target port where the test JVM expects the debugger
      Returns:
        this
      Since:
        5.6

    - #### forTasks

          @Incubating
          TestLauncher forTasks​(java.lang.String... tasks)

      Sets the tasks to be executed. If no tasks are specified, the project's default tasks are executed.

      The specified tasks are ignored if the target Gradle versions is <7.6.

      Parameters:
        `tasks` - The paths of the tasks to be executed. Relative paths are evaluated relative to the project for which this launcher was created.
      Returns:
        this
      Since:
        7.6

    - #### run

          void run()
            throws TestExecutionException

      Executes the tests, blocking until complete.
      Throws:
        `TestExecutionException` - when one or more tests fail, or no tests for execution declared or no matching tests can be found.
        `UnsupportedVersionException` - When the target Gradle version does not support test execution.
        `UnsupportedBuildArgumentException` - When there is a problem with build arguments provided by `ConfigurableLauncher.withArguments(String...)`.
        `UnsupportedOperationConfigurationException` - When the target Gradle version does not support some requested configuration option.
        `BuildException` - On some failure while executing the tests in the Gradle build.
        `BuildCancelledException` - When the operation was cancelled before it completed successfully.
        `GradleConnectionException` - On some other failure using the connection.
        `java.lang.IllegalStateException` - When the connection has been closed or is closing.
      Since:
        2.6

    - #### run

          void run​(ResultHandler<? super java.lang.Void> handler)

      Starts executing the tests. This method returns immediately, and the result is later passed to the given handler.

      If the operation fails, the handler's `ResultHandler.onFailure(GradleConnectionException)` method is called with the appropriate exception. See `run()` for a description of the various exceptions that the operation may fail with.

      Parameters:
        `handler` - The handler to supply the result to.
      Throws:
        `java.lang.IllegalStateException` - When the connection has been closed or is closing.
      Since:
        2.6

    - #### withTestsFor

          @Incubating
          TestLauncher withTestsFor​(Action<TestSpecs> testSpec)

      Adds tests to be executed declared using a fine-grained test selection API.

      Clients can target tests via the `TestSpec` interface, which can configure the target test tasks as well as what tests should be executed

               TestLauncher testLauncher = projectConnection.newTestLauncher();
               testLauncher.withTestsFor(spec -> {
                   spec.forTaskPath(":test")
                       .includePackage("org.pkg")
                       .includeClass("com.TestClass")
                       .includeMethod("com.TestClass")
                       .includePattern("io.*")
               }).run();

      Note: These tests are ignored for target Gradle version earlier than 7.6.

      Parameters:
        `testSpec` - The action selecting the target tests.
      Returns:
        this
      Since:
        7.6