A2uiTestSurface

Functions summary

Unit
@Composable
A2uiTestSurface(
    surface: A2uiSurfaceModel,
    modifier: Modifier,
    onLoading: @Composable (Modifier) -> Unit,
    onError: @Composable (A2uiException, Modifier) -> Unit
)

A test utility composable that mounts the root component of the specified A2uiSurfaceModel to allow testing individual components or entire surfaces in isolation.

Functions

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 A2uiSurfaceModel to allow testing individual components or entire surfaces in isolation.

This composable observes the reactive state of the root component within the surface. It handles transitions between loading, error, and success states using the provided onLoading and onError 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 AssertionError. This ensures that tests fail predictably and explicitly expose the underlying A2uiException.

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: A2uiSurfaceModel

The A2uiSurfaceModel to render, typically returned by A2uiTestController.start or obtained from A2uiTestController.surface.
modifier: Modifier = Modifier

The Modifier to be applied to the root component's layout.
onLoading: @Composable (Modifier) -> Unit = {}

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: @Composable (A2uiException, Modifier) -> Unit = { 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 AssertionError to fail the active test.