/flutter-test

description: Run Flutter/Dart tests, report failures, and incrementally fix test issues. Covers unit, widget, golden, and integration tests.

Flutter Test

This command runs the Flutter test suite and reports results. When failures occur, it diagnoses and fixes issues incrementally.

What This Command Does

1. **Run Tests**: Execute `flutter test` (or scope to changed files) 2. **Parse Failures**: Identify failing tests by type and cause 3. **Fix Incrementally**: One failure at a time where possible 4. **Verify**: Re-run after each fix 5. **Report**: Show coverage summary and remaining failures

When to Use

Use `/flutter-test` when:

• After implementing a feature to verify nothing broke
• After running `/flutter-build` to ensure tests pass
• To check test coverage on new code
• When a specific test file is failing
• Before submitting a PR

Commands Run

# Run all tests
flutter test 2>&1

# Run with coverage
flutter test --coverage 2>&1

# Run specific test file
flutter test test/unit/domain/usecases/get_user_test.dart 2>&1

# Run tests matching a name pattern
flutter test --name "CartBloc" 2>&1

# Run integration tests (requires device/emulator)
flutter test integration_test/ 2>&1

# Update golden files when intentional visual changes are made
flutter test --update-goldens 2>&1

Example Session

User: /flutter-test

Agent:
# Flutter Test Run

## Test Execution

$ flutter test 00:05 +42 -2: Some tests failed.

FAILED: test/unit/data/user_repository_test.dart UserRepository getById returns null when user not found Expected: null Actual: User(id: 'test-id', name: 'Test User')

FAILED: test/widget/cart_page_test.dart CartPage shows empty state when cart is empty Expected: exactly one widget with text 'Your cart is empty' Found: no widget with text 'Your cart is empty'

## Fix 1: Repository Test

File: test/unit/data/user_repository_test.dart
Failure: `getById` returns a user when it should return null for missing ID

Root cause: Test setup adds a user with ID 'test-id' but queries with 'missing-id'.
Fix: Updated test to query with 'missing-id' — setup was correct, query was wrong.

$ flutter test test/unit/data/user_repository_test.dart 1 test passed.

## Fix 2: Widget Test

File: test/widget/cart_page_test.dart
Failure: Empty state text widget not found

Root cause: Empty state message was renamed from 'Your cart is empty' to 'Cart is empty' in the widget.
Fix: Updated test string to match current widget copy.

$ flutter test test/widget/cart_page_test.dart 1 test passed.

## Final Run

$ flutter test --coverage All 44 tests passed. Coverage: 84.2% (target: 80%)

## Summary

| Metric | Value |
|--------|-------|
| Total tests | 44 |
| Passed | 44 |
| Failed | 0 |
| Coverage | 84.2% |

Test Status: PASS ✓
````

## Common Test Failures

| Failure | Typical Fix |
|---------|-------------|
| `Expected: <X> Actual: <Y>` | Update assertion or fix implementation |
| `Widget not found` | Fix finder selector or update test after widget rename |
| `Golden file not found` | Run `flutter test --update-goldens` to generate |
| `Golden mismatch` | Inspect diff; run `--update-goldens` if change was intentional |
| `MissingPluginException` | Mock platform channel in test setup |
| `LateInitializationError` | Initialize `late` fields in `setUp()` |
| `pumpAndSettle timed out` | Replace with explicit `pump(Duration)` calls |

## Related Commands

- `/flutter-build` — Fix build errors before running tests
- `/flutter-review` — Review code after tests pass
- `tdd-workflow` skill — Test-driven development workflow

## Related

- Agent: `agents/flutter-reviewer.md`
- Agent: `agents/dart-build-resolver.md`
- Skill: `skills/flutter-dart-code-review/`
- Rules: `rules/dart/testing.md`