write-unit-tests

---
name: write-unit-tests
description: Use when writing or modifying unit tests in the Alkaa project — triggers on tasks like "add a test", "write tests for X", "test this ViewModel", "cover this use case with tests", or "add unit test coverage".
---

# Write Unit Tests

## Overview

Unit tests in Alkaa are multiplatform-first, fake-based, and structured around a single scenario per test. Tests live in `commonTest` and run fastest via `./gradlew desktopTest`.

## Structure

- **Given / When / Then** — Use comments to separate the three blocks in every test → see `references/TEST_EXAMPLES.md`
- **Backtick names** — Start with `test if` or `check if`, describe the specific condition and expected outcome
- **One scenario per test** — Split side effects, error paths, and edge cases into separate tests
- **Fakes only** — Never mocks for domain interfaces → see `references/FAKE_PATTERNS.md` for all three fake patterns
- **CoroutinesTestDispatcher** — Delegate `by CoroutinesTestDispatcherImpl()` for any coroutine-using test class → see `references/TEST_EXAMPLES.md`
- **ViewModel test setup** → see `references/TEST_EXAMPLES.md`
- **Use case / repository test setup** → see `references/TEST_EXAMPLES.md`

## Naming

```
✅ `test if when load tasks fails the error state is returned`
✅ `test if task is updated as completed`
✅ `test if category without name is not added`
❌ testUpdateTask()
❌ test1()
```

## Rules

| Rule | Details |
|------|---------|
| **Fakes over mocks** | Only use mocks for Android/Framework types you cannot interface (e.g., `Context`) |
| **CoroutinesTestDispatcher** | Delegate `by CoroutinesTestDispatcherImpl()` for any coroutine-using test class |
| **ViewModel at field level** | Construct ViewModel at field level, not inside `@BeforeTest` |
| **`runTest` for suspend** | Use `= runTest { }` for all suspend test bodies |
| **`flow.first()`** | Collect current state with `flow.first()` |
| **`require()` for narrowing** | Use `require(state is X)` before accessing state-specific properties |
| **`@BeforeTest` cleanup** | Call `clean()` on every fake to reset state between tests |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Using mocks for domain interfaces | Create a fake implementing the interface |
| Forgetting `CoroutinesTestDispatcher` delegation | Add `by CoroutinesTestDispatcherImpl()` |
| Testing multiple scenarios in one test | Split into separate `@Test` functions |
| Skipping `@BeforeTest` cleanup | Add `setup()` calling `clean()` on every fake |
| Constructing ViewModel in `@BeforeTest` | Construct at field level so it shares dispatcher context |
| Omitting Given/When/Then comments | Always add the three comment blocks |
| Vague test names like `testUpdate()` | Rename to describe the scenario and expected outcome |

## Related Skills

- **ViewModel tests** → use `write-viewmodel` skill for ViewModel construction patterns
- **UI behavior tests** → use `write-ui-tests` skill
- **Full user flow tests** → use `write-e2e-tests` skill

More agent context in igorescodro/alkaa

11 other files this repository gives its agents.