# A2uiTestSurface

## Functions summary

|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable https://developer.android.com/reference/kotlin/androidx/a2ui/compose/ui/testing/A2uiTestSurface.composable#A2uiTestSurface(androidx.a2ui.model.processor.A2uiSurfaceModel,androidx.compose.ui.Modifier,kotlin.Function1,kotlin.Function2)( surface: https://developer.android.com/reference/kotlin/androidx/a2ui/model/processor/A2uiSurfaceModel, modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier, onLoading: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, onError: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (https://developer.android.com/reference/kotlin/androidx/a2ui/model/protocol/A2uiException, https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` A test utility composable that mounts the root component of the specified `https://developer.android.com/reference/kotlin/androidx/a2ui/model/processor/A2uiSurfaceModel` to allow testing individual components or entire surfaces in isolation. |

## Functions

### A2uiTestSurface

Artifact: [androidx.a2ui.compose:compose-ui-testing](https://developer.android.com/jetpack/androidx/releases/a2ui-compose) [View Source](https://cs.android.com/search?q=file:androidx/a2ui/compose/ui/testing/A2uiTestSurface.kt+function:A2uiTestSurface)

```
@Composable
fun A2uiTestSurface(
    surface: A2uiSurfaceModel,
    modifier: Modifier = Modifier,
    onLoading: @Composable (Modifier) -> Unit = {},
    onError: @Composable (A2uiException, Modifier) -> Unit = { exception, _ ->
        throw AssertionError("A2UI test surface failed to render: ${exception.message}", exception)
    }
): Unit
```

A test utility composable that mounts the root component of the specified `https://developer.android.com/reference/kotlin/androidx/a2ui/model/processor/A2uiSurfaceModel` to allow testing individual components or entire surfaces in isolation.

This composable observes the reactive state of the root component within the `https://developer.android.com/reference/kotlin/androidx/a2ui/compose/ui/testing/package-summary#A2uiTestSurface(androidx.a2ui.model.processor.A2uiSurfaceModel,androidx.compose.ui.Modifier,kotlin.Function1,kotlin.Function2)`. It handles transitions between loading, error, and success states using the provided `https://developer.android.com/reference/kotlin/androidx/a2ui/compose/ui/testing/package-summary#A2uiTestSurface(androidx.a2ui.model.processor.A2uiSurfaceModel,androidx.compose.ui.Modifier,kotlin.Function1,kotlin.Function2)` and `https://developer.android.com/reference/kotlin/androidx/a2ui/compose/ui/testing/package-summary#A2uiTestSurface(androidx.a2ui.model.processor.A2uiSurfaceModel,androidx.compose.ui.Modifier,kotlin.Function1,kotlin.Function2)` slots, and automatically provides the catalog's readiness evaluator to the composition.

By default, if the root component fails to evaluate (for example, due to a schema validation error or an unknown component type), this composable throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-assertion-error/index.html`. This ensures that tests fail predictably and explicitly expose the underlying `https://developer.android.com/reference/kotlin/androidx/a2ui/model/protocol/A2uiException`.

```kotlin
import androidx.a2ui.compose.ui.A2uiCatalog
import androidx.a2ui.compose.ui.testing.A2uiComponentPayload
import androidx.a2ui.compose.ui.testing.A2uiComponentStub
import androidx.a2ui.compose.ui.testing.A2uiTestController
import androidx.a2ui.compose.ui.testing.A2uiTestSurface
import androidx.a2ui.model.protocol.A2uiException.A2uiRuntimeException
import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.platform.testTag
import androidx.compose.ui.test.assertIsDisplayed
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.onNodeWithText
import androidx.compose.ui.test.v2.runComposeUiTest

runComposeUiTest {
    val controller =
        A2uiTestController(
            catalog = A2uiCatalog("test_catalog", emptyList()),
            initialComponents = listOf(A2uiComponentPayload("root")),
            componentStubs =
                listOf(
                    A2uiComponentStub.withId("root") { _, modifier ->
                        BasicText("Success Root", modifier = modifier.testTag("root_tag"))
                    }
                ),
        )
    val surface = controller.start()

    setContent {
        // Mount a test A2UI surface for a given surface model with custom loading and error UIs
        A2uiTestSurface(
            surface = surface,
            onLoading = { modifier ->
                BasicText("Loading...", modifier = modifier.testTag("loading_tag"))
            },
            onError = { exception, modifier ->
                BasicText("Error: ${exception.message}", modifier = modifier.testTag("error_tag"))
            },
        )
    }

    onNodeWithTag("root_tag").assertIsDisplayed()
    onNodeWithText("Success Root").assertIsDisplayed()

    // Simulate an error arriving for the root component
    controller.failComponent("root", A2uiRuntimeException("Simulated crash"))
    controller.waitForIdle()

    // Verify the surface transitions to the onError callback
    onNodeWithTag("error_tag").assertIsDisplayed()
    onNodeWithText("Error: Simulated crash").assertIsDisplayed()
}
```

| Parameters |
|---|---|
| `surface: https://developer.android.com/reference/kotlin/androidx/a2ui/model/processor/A2uiSurfaceModel` | The `https://developer.android.com/reference/kotlin/androidx/a2ui/model/processor/A2uiSurfaceModel` to render, typically returned by `https://developer.android.com/reference/kotlin/androidx/a2ui/compose/ui/testing/A2uiTestController#start()` or obtained from `https://developer.android.com/reference/kotlin/androidx/a2ui/compose/ui/testing/A2uiTestController#surface()`. |
| `modifier: https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier = Modifier` | The `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` to be applied to the root component's layout. |
| `onLoading: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = {}` | A composable to display while the component is resolving its payload or waiting for dynamic data bindings to become ready. By default, nothing is displayed during loading. |
| `onError: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (https://developer.android.com/reference/kotlin/androidx/a2ui/model/protocol/A2uiException, https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html = { exception, _ -> throw AssertionError("A2UI test surface failed to render: ${exception.message}", exception) }` | A composable to display if the component encounters a schema validation or runtime error. By default, this throws an `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-assertion-error/index.html` to fail the active test. |