write-e2e-tests

---
name: write-e2e-tests
description: Use when writing or modifying end-to-end tests in the Alkaa project — triggers on tasks like "add an E2E test", "write a flow test", "test this feature end-to-end", "add a test to shared module", or "cover this user journey with a test".
---

# Write E2E Tests

## Overview

E2E tests exercise full application flows through a real Koin DI graph and a live `AlkaaMultiplatformApp` Compose tree. They live in `shared/src/commonTest/kotlin/com/escodro/alkaa/` — one file per feature domain (e.g., `TaskFlowTest`, `CategoryFlowTest`).

## Structure

- **Class setup** — Extends `AlkaaTest(), KoinTest`; `@BeforeTest` calls `beforeTest()` first, then cleans DAOs → see `references/SETUP.md`
- **Entry point** — `= uiTest { }` for all tests; `= flakyUiTest { }` only for known timing-sensitive tests → see `references/SETUP.md`
- **Data seeding** — Insert directly via DAOs in `@BeforeTest` using `runTest` → see `references/SETUP.md`
- **Navigation helpers** — Private `ComposeUiTest` extension functions using content descriptions → see `references/SETUP.md`
- **Assertions** — Existence, wait helpers, selection state, semantic matchers → see `references/SETUP.md`
- **Fake dependencies** — `declare<T> { FakeImpl() }` to override external dependencies → see `references/SETUP.md`

## Naming

Descriptive, underscore-separated. Two styles:
- State-driven: `when_no_query_then_all_tasks_are_visible()`
- Action-driven: `add_and_open_task()`, `complete_task_from_list()`

No camelCase, no backtick names.

## Rules

| Rule | Details |
|------|---------|
| **`beforeTest()` first** | Call `beforeTest()` before any DAO injection or `by inject()` use |
| **`cleanTable()` in `@BeforeTest`** | Call on every DAO used to avoid state leakage between tests |
| **DAO-based seeding** | Insert test data directly via DAOs — not via use cases |
| **Content descriptions for navigation** | Navigate via content descriptions, not raw text |
| **Resource strings** | `getString(Res.string.xyz)` inside `uiTest` or `runComposeUiTest` — never hardcode |
| **Fakes over mocks** | Use `declare<T> { FakeImpl() }` for external dependencies |
| **`@AfterTest` always** | Always call `afterTest()` to stop Koin after each test |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Calling `by inject()` before `beforeTest()` | Always call `beforeTest()` first |
| Skipping `cleanTable()` | Call on every DAO to avoid state leakage |
| Using `flakyUiTest` by default | Reserve for tests with known timing sensitivity |
| Hardcoding UI strings | Use `getString(...)` inside `uiTest` or `runComposeUiTest` |
| Testing multiple flows in one test | One scenario per test |
| Missing `@AfterTest` / `afterTest()` | Always stop Koin after each test |
| Navigation via raw text | Navigate via content descriptions |
| Using mocks | Use fakes via `declare<T> { FakeImpl() }` |

More agent context in igorescodro/alkaa

11 other files this repository gives its agents.