write-ui-tests

---
name: write-ui-tests
description: Use when writing or modifying UI/Compose instrumented tests in the Alkaa project — triggers on tasks like "add a UI test", "test this composable", "add instrumented test", "test this screen behavior".
---

# Write UI Tests

## Overview

UI tests in Alkaa test Compose and UI behavior in isolation — not integration tests. Composables must be stateless to make testing straightforward: pass all state and callbacks as parameters, then assert on the semantic tree.

Tests live in: `features/<feature>/src/commonTest/kotlin/com/escodro/<feature>/presentation/instrumented/`

## Structure

- **Class setup** — Extends `AlkaaTest()`, `@OptIn(ExperimentalTestApi::class)` on class → see `references/SETUP.md`
- **Test body** — `= runComposeUiTest { }` for each test
- **Loading composables** — Private extension function on `ComposeUiTest`; always wrap with `AlkaaThemePreview` → see `references/SETUP.md`
- **Fakes** — Implement interface, register in Koin test module, clean in `@AfterTest` → see `references/SETUP.md`
- **Assertions** — By text, content description, or test tag; never by component ID → see `references/SETUP.md`

## Naming

Snake_case, two accepted forms:
- Standard: `test_emptyViewIsShown()`
- State-driven: `when_view_is_opened_then_empty_view_is_shown()`

No camelCase, no backtick names.

## Rules

| Rule | Details |
|------|---------|
| **Always wrap** | Wrap composable in `AlkaaThemePreview` |
| **Resource strings** | `getString(Res.string.xyz)` inside `uiTest` or `runComposeUiTest` — never hardcode |
| **One scenario per test** | Split different states into separate `@Test` functions |
| **`useUnmergedTree = true`** | When nodes are inside merged semantics |
| **`@IgnoreOnDesktop`** | For tests not applicable on desktop |
| **`@AfterTest` cleanup** | Call `clean()` on every fake |
| **Given/When/Then** | Always add the three comment blocks |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Testing a stateful composable directly | Extract a stateless Content composable and test that |
| Using mocks for domain interfaces | Create a fake implementing the interface |
| Hardcoding UI strings | Use `getString(...)` inside `uiTest` or `runComposeUiTest` |
| Testing multiple scenarios in one test | Split into separate `@Test` functions |
| Missing `@AfterTest` cleanup | Add `tearDown()` calling `clean()` on every fake |
| Forgetting `AlkaaThemePreview` wrapper | Always wrap composable |
| Omitting Given/When/Then comments | Always add the three comment blocks |

More agent context in igorescodro/alkaa

11 other files this repository gives its agents.