flutter-ai-starter / rules

---
description: Testing requirements — unit, widget, provider, golden, integration
globs: ["test/**/*.dart", "lib/**/*.dart", "supabase/**/*"]
alwaysApply: false
---

# Testing requirements

**All code units below require tests.** No skipping. Use `implement-tdd` for red-green-refactor workflow.

## What must be tested

| Code unit | Test type | Tool |
|---|---|---|
| Pure function / mapper / util | Unit | `package:test` |
| Repository | Unit with fake client | `package:test` |
| ViewModel (`ChangeNotifier`) | Unit test (fake repos) | `package:test` |
| Design-system widget | Widget + golden (light + dark) | `flutter_test` |
| Screen | Widget (happy + one error path) | `flutter_test` |
| Critical flow | Integration | `integration_test` |
| Supabase table | RLS | pgTAP (when using Supabase) |

## Testing strategy (fake vs mock)

| Layer | Approach | Why |
|---|---|---|
| ViewModel unit tests | **Fake repositories** (hand-written stubs) | Test behavior through public ViewModel API |
| Repository unit tests | **Mockito** for dio / Supabase client at the boundary | Verify HTTP/query calls without real network |
| ViewModel `notifyListeners` | Optional **listener** on the ViewModel | Assert UI refresh signal only — not business logic |
| Internal private methods | **Do not test directly** | Test via public methods; refactor if untestable |

- Prefer fakes over mocks for code you own (repositories injected into ViewModels).
- Use Mockito (`generate-mocks` skill) for external I/O boundaries only.
- Never mock internal collaborators to test implementation details.

## Layout

Mirror source tree under `test/`:

```
test/
  core/...
  design_system/components/...
  features/<feature>/...
  integration/
```

## Naming

- Files: `<unit>_test.dart`
- Cases: `<unit> <does what> when <state>`

## CI expectations

- `dart format --set-exit-if-changed .`
- `flutter analyze --fatal-infos`
- `flutter test`
- `dart run build_runner build` must produce no diff when codegen is used

## Forbidden

- `skip: true` without documented reason
- Shipping new/changed code without the tests required by the table above
- Tests hitting prod Supabase or real AI vendor APIs
- Asserting behavior through private implementation details

Use the `implement-tdd` skill for red-green-refactor workflow.