Testowanie komponentów i platform A2UI

Biblioteka testowa androidx.a2ui.compose:compose-ui-testing udostępnia interfejsy API do testowania, które korzystają z wzorca kontrolera typowego dla bibliotek testowych Jetpack, takich jak TestNavHostController w przypadku biblioteki Navigation.

W przeciwieństwie do standardowych komponentów Jetpack Compose, które przyjmują statyczne parametry i emitują interfejs, komponenty A2UI są kontekstowe. Są one oparte na A2uiComponentScope, które służy do oceny dynamicznych wiązań danych, wysyłania działań wychodzących do agenta, zapisywania danych w dwukierunkowych wiązaniach danych i rozszerzania dynamicznych szablonów podrzędnych.

Interfejsy API do testowania upraszczają konfigurację testów, udostępniając rzeczywiste instancje A2uiMessageProcessor i uruchamiając ich współprogramy powiązane ze środowiskiem testowym Compose.

Odizolowane komponenty

Możesz sprawdzić, czy poszczególne komponenty rozwiązują swoje dane, wysyłają działania i są prawidłowo renderowane w motywie systemu projektowania:

@Test
fun button_resolvesStubChildAndDispatchesAction() = runComposeUiTest {
    // 1. Create the test controller
    val controller = A2uiTestController(
        // Provide a catalog containing the component under test
        catalog = CustomComponentCatalog,
        // Configure the component under test with concrete properties
        initialComponents = listOf(
            A2uiComponentPayload(
                id = "root",
                type = "Button",
                properties = mapOf(
                    "child" to "btn_text",
                    "variant" to "primary",
                    "action" to mapOf(
                        "event" to mapOf(
                            "name" to "submit_form",
                            "context" to mapOf("username" to mapOf("path" to "/user/name")),
                        ),
                    ),
                ),
            ),
            A2uiComponentPayload("btn_text"),
        ),
        // Stub the required child component
        componentStubs = listOf(
            A2uiComponentStub.withId("btn_text") { _, modifier ->
                Text("Submit", modifier = modifier)
            },
        ),
        // Provide initial dynamic data
        initialData = mapOf("user" to mapOf("name" to "Test User")),
    )

    // 2. Start background processing and initialize the surface
    val surface = controller.start()

    // 3. Mount the UI
    setContent {
        A2uiTestSurface(surface)
    }

    // 4. Interact using standard Compose UI semantics
    onNodeWithText("Submit").performClick()

    // 5. Wait for Compose and A2UI background processes to settle
    waitForIdle()
    controller.waitForIdle()

    // 6. Assert outbound actions were correctly evaluated and intercepted
    val action = controller.dispatchedActions.single() as A2uiEventAction
    assertEquals("submit_form", action.eventName)
    assertEquals("Test User", action.context["username"])
}

Stany powierzchniowe

Możesz przetestować hosty platform, takie jak A2uiSurface, w tym ich stany i przejścia:

@Test
fun surface_displaysLoading_thenTransitionsToContent() = runComposeUiTest {
    // 1. Create an empty controller to simulate a pending network request
    val controller = A2uiTestController(
        catalog = CustomComponentCatalog,
        // Pre-register a stub for the expected root component type
        componentStubs = listOf(
            A2uiComponentStub.withType("RootLayout") { _, modifier ->
                Text("Content Ready", modifier = modifier)
            },
        ),
    )
    val surface = controller.start()

    // 2. Mount the surface UI
    setContent {
        A2uiSurface(surfaceModel = surface)
    }

    // 3. Assert the loading placeholder is active
    onNode(hasProgressBarRangeInfo(ProgressBarRangeInfo.Indeterminate)).assertExists()

    // 4. Simulate the agent pushing the layout payload over the network
    controller.updateComponent(
        id = "root",
        type = "RootLayout",
        properties = emptyMap(),
    )

    // 5. Wait for the data layer and animation to settle
    controller.waitForIdle()
    waitForIdle()

    // 6. Assert the loading state is gone and content is visible
    onNode(hasProgressBarRangeInfo(ProgressBarRangeInfo.Indeterminate)).assertDoesNotExist()
    onNodeWithText("Content Ready").assertIsDisplayed()
}

Powiązanie dwukierunkowe

Możesz testować komponenty, takie jak pola tekstowe, które zapisują dane w modelu danych podczas danych wejściowych użytkownika, i weryfikować reaktywne aktualizacje, gdy agent zmienia model danych:

@Test
fun textField_writesToDataModelAndReactsToAgent() = runComposeUiTest {
    val controller = A2uiTestController(
        catalog = CustomComponentCatalog,
        initialComponents = listOf(
            A2uiComponentPayload(
                id = "root",
                type = "TextField",
                properties = mapOf(
                    "label" to "Username",
                    "value" to mapOf("path" to "/form/username"),
                ),
            ),
        ),
        initialData = mapOf("form" to mapOf("username" to "Initial")),
    )
    val surface = controller.start()

    setContent {
        A2uiTestSurface(surface)
    }

    // 1. User interaction updates the global DataModel locally
    onNodeWithText("Initial").performTextReplacement("LocallyTyped")
    waitForIdle()

    // 2. Assert the component wrote back to the DataModel
    assertEquals("LocallyTyped", controller.getData<String>("/form/username"))

    // 3. Simulate the agent pushing a data update for the same path
    controller.updateData("/form/username", "ServerOverridden")
    controller.waitForIdle()

    // 4. Assert the component reactively updated the UI
    onNodeWithText("ServerOverridden").assertIsDisplayed()
}

Komponenty z szablonowymi elementami podrzędnymi

Możesz testować komponenty zaprojektowane do wyświetlania kolekcji dzieci zdefiniowanych za pomocą szablonów A2UIChildList:

@Test
fun column_rendersDynamicChildTemplates() = runComposeUiTest {
    val controller = A2uiTestController(
        catalog = CustomComponentCatalog,
        initialData = mapOf(
            "catalog" to mapOf(
                "products" to listOf(
                    mapOf("title" to "Camera"),
                    mapOf("title" to "Laptop"),
                ),
            ),
        ),
        initialComponents = listOf(
            A2uiComponentPayload(
                id = "root",
                type = "Column",
                properties = mapOf(
                    "children" to mapOf(
                        "path" to "/catalog/products",
                        "componentId" to "product_template",
                    ),
                ),
            ),
            // Bind the initial properties for the dynamically instantiated
            // template stub.
            A2uiComponentPayload(
                id = "product_template",
                properties = mapOf("title" to mapOf("path" to "title")),
            ),
        ),
        componentStubs = listOf(
            A2uiComponentStub.withId(id = "product_template") { props, modifier ->
                val titleProp = remember { A2uiProperty.dynamicString("title") }
                val title = props.bind(titleProp) ?: "Unknown"
                Text(text = "Stubbed: $title", modifier = modifier)
            },
        ),
    )
    val surface = controller.start()
    setContent { A2uiTestSurface(surface) }

    // Verify the template was instantiated twice with relative data
    onNodeWithText("Stubbed: Camera").assertExists()
    onNodeWithText("Stubbed: Laptop").assertExists()

    // Simulate appending a new item to the data model array
    controller.updateData("/catalog/products/-", mapOf("title" to "Tablet"))
    controller.waitForIdle()

    // Verify the Column dynamically instantiated a new child stub
    onNodeWithText("Stubbed: Tablet").assertExists()
}

Rezerwy błędów w przypadku błędów agenta

Możesz sprawdzić, czy platformy i komponenty radzą sobie z błędami agenta, takimi jak halucynacje:

@Test
fun surface_displaysErrorFallback_onAgentHallucination() = runComposeUiTest {
    val controller = A2uiTestController(catalog = CustomComponentCatalog)
    val surface = controller.start()

    // 1. Mount the surface orchestrator with error boundaries
    setContent { A2uiSurface(surfaceModel = surface) }

    // 2. Simulate an agent hallucinating a broken component layout
    controller.failComponent(
        id = "root",
        exception = A2uiException.A2uiValidationException(
            message = "HallucinatedType",
            path = "/components/root"
        ),
    )
    controller.waitForIdle()

    // 3. Assert the surface displayed the fallback error state
    onNodeWithText("Failed to load: HallucinatedType").assertIsDisplayed()

    // 4. Assert the core layer dispatched an error to the server
    val errorMsg = controller.outboundErrors.single()
    assertEquals("VALIDATION_FAILED", errorMsg.code)
}

Progresywne renderowanie

Możesz przetestować stany pośrednie, w których komponent nadrzędny został wczytany, ale komponenty podrzędne są nadal w stanie oczekiwania:

@Test
fun progressiveRendering_parentRendersWhileChildIsPending() = runComposeUiTest {
    // 1. Mount the parent, omitting the child instance
    val controller = A2uiTestController(
        catalog = CustomComponentCatalog,
        initialComponents = listOf(
            A2uiComponentPayload(
                id = "root",
                type = "Button",
                properties = mapOf(
                    "child" to "delayed_text_id",
                    "action" to mapOf("event" to mapOf("name" to "click")),
                ),
            ),
        ),
    )
    val surface = controller.start()
    setContent {
        A2uiTestSurface(surface)
    }

    // 2. Initial state: parent is rendered, child displays loading state
    onNodeWithText("Submit").assertDoesNotExist()
    onNode(hasProgressBarRangeInfo(ProgressBarRangeInfo.Indeterminate)).assertExists()

    // 3. Simulate arrival of the child component
    controller.updateComponent(
        id = "delayed_text_id",
        type = "Text",
        properties = mapOf("text" to "Submit"),
    )
    controller.waitForIdle()

    // 4. Assert that progressive rendering completed
    onNode(hasProgressBarRangeInfo(ProgressBarRangeInfo.Indeterminate)).assertDoesNotExist()
    onNodeWithText("Submit").assertIsDisplayed()
}

Szczegóły implementacji

W kolejnych sekcjach znajdziesz informacje o zastępowaniu komponentów, weryfikacji schematu i synchronizacji korutyn w ramach testowych.

Biblioteka testowa udostępnia te główne interfejsy API:

• A2uiTestController: Funkcje konstruktora rozszerzenia i główny interfejs kontrolera testu.
• A2uiComponentStub: elementy zastępcze i zastąpienia dla komponentów podrzędnych i katalogowych.
• A2uiTestSurface: Lekka funkcja typu „composable”, która montuje powierzchnię testową.

Zastępowanie komponentów a standardowe symulowanie

Aby wyeliminować złożone zewnętrzne platformy do tworzenia atrap, komponenty podrzędne i zależności zewnętrzne są pomijane przy użyciu atrap interfejsu (A2uiComponentStub). Funkcja A2uiComponentStub.withId przechwytuje konkretne wystąpienie komponentu według identyfikatora, a funkcja A2uiComponentStub.withType zastępuje renderowanie całego typu katalogu.

Szybka weryfikacja schematu

Platforma testowa wymusza synchronicznie umowę protokołu A2UI. Gdy kontroler inicjuje lub aktualizuje komponenty, uruchamia A2uiCoreSchemaValidator w odniesieniu do podanych ładunków. Jeśli ustawiona zostanie nieprawidłowa właściwość, np. brakujące pole wymagane lub niezgodność typu, test natychmiast się zakończy i wyświetli się błąd A2uiValidationException.

Synchronizacja współprogramów

A2uiTestController.start włącza się w kontekst współprogramu testowego dostarczony przez runComposeUiTest(). Wyodrębnia currentCoroutineContext(), mapuje pętle w tle na odłączony Job i automatycznie anuluje się po zakończeniu bloku testowego, zapobiegając zawieszaniu się testów. waitForIdle() czeka na zakończenie wszystkich oczekujących korutyn w tle.