# XCTest

API Documentation: | `XCTest`

Executes XCTest tests. Test are always run in a single execution.

### Properties

Property | Description
`binaryResultsDirectory` | The root directory property for the test results in internal binary format.
`failOnNoDiscoveredTests` | Whether the task should fail if test sources are present, but no tests are discovered during test execution. Defaults to true.
`ignoreFailures` | Specifies whether the build should break when the verifications performed by this task fail.
`reports` | The reports that this task potentially produces.
`runScriptFile` | Returns test suite bundle or executable location
`testInstallDirectory` | The test suite bundle or executable location
`workingDirectory` | The working directory property for this test.

### Methods

Method | Description
`addTestListener(listener)` | Registers a test listener with this task. Consider also the following handy methods for quicker hooking into test execution: `AbstractTestTask.beforeTest(groovy.lang.Closure)`, `AbstractTestTask.afterTest(groovy.lang.Closure)`, `AbstractTestTask.beforeSuite(groovy.lang.Closure)`, `AbstractTestTask.afterSuite(groovy.lang.Closure)`
`addTestMetadataListener(listener)` | Incubating Registers a metadata listener with this task.
`addTestOutputListener(listener)` | Registers a output listener with this task. Quicker way of hooking into output events is using the `AbstractTestTask.onOutput(groovy.lang.Closure)` method.
`afterSuite(closure)` | Deprecated Adds a closure to be notified after a test suite has executed. A `TestDescriptor` and `TestResult` instance are passed to the closure as a parameter.
`afterTest(closure)` | Deprecated Adds a closure to be notified after a test has executed. A `TestDescriptor` and `TestResult` instance are passed to the closure as a parameter.
`beforeSuite(closure)` | Deprecated Adds a closure to be notified before a test suite is executed. A `TestDescriptor` instance is passed to the closure as a parameter.
`beforeTest(closure)` | Deprecated Adds a closure to be notified before a test is executed. A `TestDescriptor` instance is passed to the closure as a parameter.
`onOutput(closure)` | Deprecated Adds a closure to be notified when output from the test received. A `TestDescriptor` and `TestOutputEvent` instance are passed to the closure as a parameter.
`removeTestListener(listener)` | Unregisters a test listener with this task. This method will only remove listeners that were added by calling `AbstractTestTask.addTestListener(org.gradle.api.tasks.testing.TestListener)` on this task. If the listener was registered with Gradle using `Gradle.addListener(java.lang.Object)` this method will not do anything. Instead, use `Gradle.removeListener(java.lang.Object)`.
`removeTestOutputListener(listener)` | Unregisters a test output listener with this task. This method will only remove listeners that were added by calling `AbstractTestTask.addTestOutputListener(org.gradle.api.tasks.testing.TestOutputListener)` on this task. If the listener was registered with Gradle using `Gradle.addListener(java.lang.Object)` this method will not do anything. Instead, use `Gradle.removeListener(java.lang.Object)`.
`reports(configureAction)` | Configures the reports that this task potentially produces.
`setTestNameIncludePatterns(testNamePattern)` | Sets the test name patterns to be included in execution. Classes or method names are supported, wildcard '*' is supported. For more information see the user guide chapter on testing. For more information on supported patterns see `TestFilter`

### Script blocks

No script blocks

### Property details

#### `DirectoryProperty` `binaryResultsDirectory`

The root directory property for the test results in internal binary format.

Default:
  ``project.testResultsDir`/binary/`task.name``

#### ``Property`<`Boolean`>` `failOnNoDiscoveredTests`

Whether the task should fail if test sources are present, but no tests are discovered during test execution. Defaults to true.

#### `boolean` `ignoreFailures`

Specifies whether the build should break when the verifications performed by this task fail.

#### `TestTaskReports` `reports` (read-only)

The reports that this task potentially produces.

#### `RegularFileProperty` `runScriptFile`

Returns test suite bundle or executable location

#### `DirectoryProperty` `testInstallDirectory`

The test suite bundle or executable location

#### `DirectoryProperty` `workingDirectory`

The working directory property for this test.

### Method details

#### `void` `addTestListener`(`TestListener` listener)

Registers a test listener with this task. Consider also the following handy methods for quicker hooking into test execution: `AbstractTestTask.beforeTest(groovy.lang.Closure)`, `AbstractTestTask.afterTest(groovy.lang.Closure)`, `AbstractTestTask.beforeSuite(groovy.lang.Closure)`, `AbstractTestTask.afterSuite(groovy.lang.Closure)`

This listener will NOT be notified of tests executed by other tasks. To get that behavior, use `Gradle.addListener(java.lang.Object)`.

#### `void` `addTestMetadataListener`(`TestMetadataListener` listener)

Note: This method is incubating and may change in a future version of Gradle.

Registers a metadata listener with this task.

#### `void` `addTestOutputListener`(`TestOutputListener` listener)

Registers a output listener with this task. Quicker way of hooking into output events is using the `AbstractTestTask.onOutput(groovy.lang.Closure)` method.

#### `void` `afterSuite`(`Closure` closure)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Adds a closure to be notified after a test suite has executed. A `TestDescriptor` and `TestResult` instance are passed to the closure as a parameter.

This method is also called after all test suites are executed. The provided descriptor will have a null parent suite.

#### `void` `afterTest`(`Closure` closure)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Adds a closure to be notified after a test has executed. A `TestDescriptor` and `TestResult` instance are passed to the closure as a parameter.

#### `void` `beforeSuite`(`Closure` closure)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Adds a closure to be notified before a test suite is executed. A `TestDescriptor` instance is passed to the closure as a parameter.

This method is also called before any test suites are executed. The provided descriptor will have a null parent suite.

#### `void` `beforeTest`(`Closure` closure)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Adds a closure to be notified before a test is executed. A `TestDescriptor` instance is passed to the closure as a parameter.

#### `void` `onOutput`(`Closure` closure)

Note: This method is deprecated and will be removed in the next major version of Gradle.

Adds a closure to be notified when output from the test received. A `TestDescriptor` and `TestOutputEvent` instance are passed to the closure as a parameter.

    apply plugin: 'java'

    test {
       onOutput { descriptor, event ->
           if (event.destination == TestOutputEvent.Destination.StdErr) {
               logger.error("Test: " + descriptor + ", error: " + event.message)
           }
       }
    }

#### `void` `removeTestListener`(`TestListener` listener)

Unregisters a test listener with this task. This method will only remove listeners that were added by calling `AbstractTestTask.addTestListener(org.gradle.api.tasks.testing.TestListener)` on this task. If the listener was registered with Gradle using `Gradle.addListener(java.lang.Object)` this method will not do anything. Instead, use `Gradle.removeListener(java.lang.Object)`.

#### `void` `removeTestOutputListener`(`TestOutputListener` listener)

Unregisters a test output listener with this task. This method will only remove listeners that were added by calling `AbstractTestTask.addTestOutputListener(org.gradle.api.tasks.testing.TestOutputListener)` on this task. If the listener was registered with Gradle using `Gradle.addListener(java.lang.Object)` this method will not do anything. Instead, use `Gradle.removeListener(java.lang.Object)`.

#### `TestTaskReports` `reports`(``Action`<? super `TestTaskReports`>` configureAction)

Configures the reports that this task potentially produces.

#### `AbstractTestTask` `setTestNameIncludePatterns`(``List`<`String`>` testNamePattern)

Sets the test name patterns to be included in execution. Classes or method names are supported, wildcard '*' is supported. For more information see the user guide chapter on testing. For more information on supported patterns see `TestFilter`