# TestFailureHandler

Artifact: [androidx.compose.ui:ui-test](https://developer.android.com/jetpack/androidx/releases/compose-ui) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/test/ComposeUiTestConfig.kt+class:androidx.compose.ui.test.TestFailureHandler) Added in [1.13.0-rc01](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.13.0-rc01) Common/AllAndroid/JVM
- Cmn

  ```
  fun interface TestFailureHandler
  ```

*** ** * ** ***

Handles Compose UI test failures for custom diagnostics or artifact processing.

Implementations are registered in a `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/TestFailurePolicy` within a `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/ComposeUiTestConfig` and execute in the order provided. If a handler throws an exception, the framework catches and attaches it as a suppressed exception to `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/FailureContext#error()`, ensuring the original test failure is never masked.

Handlers execute synchronously on the test thread in a post-mortem state where the Compose hierarchy, coroutine scopes, and UI registries have already been torn down. As a result, interactive testing APIs like `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/ComposeUiTest#waitForIdle()` or `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/package-summary#(androidx.compose.ui.test.SemanticsNodeInteractionsProvider).onNodeWithTag(kotlin.String,kotlin.Boolean)` cannot be called within a handler.

Because handlers execute after the test timeout has elapsed, blocking calls such as file IO or network operations can delay or stall the test runner indefinitely. Handlers that perform heavy IO should enforce their own tight timeouts or dispatch work to background threads.

```kotlin
import androidx.compose.ui.test.ComposeUiTestConfig
import androidx.compose.ui.test.FailureArtifact
import androidx.compose.ui.test.TestFailureHandler
import androidx.compose.ui.test.TestFailurePolicy
import androidx.compose.ui.test.TestFailurePolicy.CaptureMode
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.v2.runComposeUiTest
import androidx.test.platform.io.PlatformTestStorageRegistry

val customFailureHandler = TestFailureHandler { context ->
    val storage = PlatformTestStorageRegistry.getInstance()

    context.artifacts.forEach { artifact ->
        when (artifact.type) {
            FailureArtifact.Type.Screenshot -> {
                // Example: Read the screenshot bytes to upload to a custom dashboard
                // val inputStream = storage.openInputFile(artifact.fileName)
            }
            FailureArtifact.Type.UiHierarchy -> {
                // Example: Get the URI to share or process further
                // val uri = storage.getOutputFileUri(artifact.fileName)
            }
        }
    }
}

val testConfig =
    ComposeUiTestConfig(
        failurePolicy =
            TestFailurePolicy(
                screenshotCaptureMode = CaptureMode.Enabled,
                uiHierarchyCaptureMode = CaptureMode.Enabled,
                failureHandlers = listOf(customFailureHandler),
            )
    )

runComposeUiTest(config = testConfig) {
    setContent { /* Your Compose UI here */ }

    // If this assertion fails, the framework will:
    // 1. Take a screenshot
    // 2. Dump the UI hierarchy
    // 3. Call customFailureHandler.onTestFailed
    onNodeWithTag("non_existent_button").assertExists()
}
```

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/TestFailurePolicy` |   |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/FailureContext` |   |

## Summary

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/TestFailureHandler#onTestFailed(androidx.compose.ui.test.FailureContext)(context: https://developer.android.com/reference/kotlin/androidx/compose/ui/test/FailureContext)` Invoked synchronously on the test thread when a Compose UI test fails. | Cmn |

## Public functions

### onTestFailed

Cmn Added in [1.13.0-rc01](https://developer.android.com/jetpack/androidx/releases/compose-ui#1.13.0-rc01)

```
fun onTestFailed(context: FailureContext): Unit
```

Invoked synchronously on the test thread when a Compose UI test fails.

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/kotlin/androidx/compose/ui/test/FailureContext` | The `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/FailureContext` containing the root `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-throwable/index.html` and any generated `https://developer.android.com/reference/kotlin/androidx/compose/ui/test/FailureArtifact`s. |