# Implementation Plan: 001-Comprehensive-Testing-Foundation

## Overview

| Field | Value |
|-------|-------|
| **Spec ID** | 001 |
| **Title** | Comprehensive Testing Foundation |
| **Status** | Ready for Implementation |
| **Estimated Effort** | ~40 hours (5 days) |
| **Priority** | High |
| **Dependencies** | None (foundational) |

## Related Documents

- **PRD**: `product-requirements.md` - Business requirements and acceptance criteria
- **SDD**: `solution-design.md` - Technical architecture and patterns

## Implementation Phases

### Phase 1: Foundation Setup (4 hours)
**Goal**: Establish test infrastructure and activate existing templates

| Task | Description | Files | Est. Time |
|------|-------------|-------|-----------|
| 1.1 | Extend `test_mocks.dart` with additional mock classes | `test/fixtures/test_mocks.dart` | 1h |
| 1.2 | Add `TestDataFactory` methods for all entities | `test/fixtures/test_mocks.dart` | 1h |
| 1.3 | Create directory structure for all test categories | `test/core/`, `test/data/`, `test/domain/`, `test/presentation/` | 30m |
| 1.4 | Verify CI/CD workflow runs correctly | `.github/workflows/test.yml` | 30m |
| 1.5 | Register repository with Codecov (if needed) | External: codecov.io | 1h |

**Acceptance Criteria**:
- [ ] `flutter test` runs without errors
- [ ] All mock classes needed for Phase 2 are defined
- [ ] Test directory structure matches `lib/` structure

---

### Phase 2: Core Layer Tests (8 hours)
**Goal**: Achieve 80% coverage on core utilities and constants

| Task | Description | Files | Est. Time |
|------|-------------|-------|-----------|
| 2.1 | JSON parsing utility tests | `test/core/utils/json_parsing_test.dart` | 2h |
| 2.2 | Currency parsing utility tests | `test/core/utils/currency_utils_test.dart` | 1h |
| 2.3 | Permission constants tests | `test/core/constants/permission_constants_test.dart` | 2h |
| 2.4 | API interceptor tests | `test/core/network/api_interceptors_test.dart` | 2h |
| 2.5 | Exception hierarchy tests | `test/core/errors/exceptions_test.dart` | 1h |

**Test Count**: ~30 tests

**Acceptance Criteria**:
- [ ] All `_parseDouble`, `_parseInt` edge cases tested
- [ ] Permission `canAccess` logic 100% covered
- [ ] Auth interceptor 403 handling tested
- [ ] All exception types instantiation tested

---

### Phase 3: Domain Layer Tests (6 hours)
**Goal**: Achieve 90% coverage on entity computed properties

| Task | Description | Files | Est. Time |
|------|-------------|-------|-----------|
| 3.1 | Store entity tests | `test/domain/entities/store_test.dart` | 1h |
| 3.2 | QueueItem entity tests | `test/domain/entities/queue_item_test.dart` | 1h |
| 3.3 | WorkbookNote visibility tests | `test/domain/entities/workbook_note_test.dart` | 1h |
| 3.4 | WorkbookTaskItem state tests | `test/domain/entities/workbook_task_item_test.dart` | 1h |
| 3.5 | TodayPerformance computed tests | `test/domain/entities/today_performance_test.dart` | 1h |
| 3.6 | CompletedBuy calculations tests | `test/domain/entities/completed_buy_test.dart` | 1h |

**Test Count**: ~40 tests

**Acceptance Criteria**:
- [ ] Progress bar calculations tested (0%, 50%, 100%, edge cases)
- [ ] Note visibility with date ranges tested
- [ ] Task status state machine tested
- [ ] Division-by-zero guards verified

---

### Phase 4: Data Layer Tests (8 hours)
**Goal**: Achieve 85% coverage on mappers and model parsing

| Task | Description | Files | Est. Time |
|------|-------------|-------|-----------|
| 4.1 | Store mapper tests | `test/data/models/mappers/store_mapper_test.dart` | 45m |
| 4.2 | StoreDetail mapper tests | `test/data/models/mappers/store_detail_mapper_test.dart` | 45m |
| 4.3 | QueueItem mapper tests | `test/data/models/mappers/queue_item_mapper_test.dart` | 45m |
| 4.4 | CompletedBuy mapper tests | `test/data/models/mappers/completed_buy_mapper_test.dart` | 45m |
| 4.5 | BuyerStats mapper tests | `test/data/models/mappers/buyer_stats_mapper_test.dart` | 45m |
| 4.6 | WorkbookNote mapper tests | `test/data/models/mappers/workbook_note_mapper_test.dart` | 45m |
| 4.7 | WorkbookComment mapper tests | `test/data/models/mappers/workbook_comment_mapper_test.dart` | 45m |
| 4.8 | TodayPerformance mapper tests | `test/data/models/mappers/today_performance_mapper_test.dart` | 45m |
| 4.9 | Task mapper tests | `test/data/models/mappers/task_mapper_test.dart` | 45m |
| 4.10 | TaskGroup mapper tests | `test/data/models/mappers/task_group_mapper_test.dart` | 30m |
| 4.11 | WorkbookTaskList mapper tests | `test/data/models/mappers/workbook_task_list_mapper_test.dart` | 45m |

**Test Count**: ~55 tests (5 per mapper)

**Acceptance Criteria**:
- [ ] All 11 mappers tested
- [ ] Null field handling verified for each mapper
- [ ] Number-as-string parsing tested
- [ ] Currency string stripping tested

---

### Phase 5: Presentation Layer Tests (10 hours)
**Goal**: Achieve 70% coverage on providers

| Task | Description | Files | Est. Time |
|------|-------------|-------|-----------|
| 5.1 | Convert dashboard example to real test | `test/presentation/providers/dashboard_provider_test.dart` | 1h |
| 5.2 | Auth provider tests | `test/presentation/providers/auth_provider_test.dart` | 1.5h |
| 5.3 | Permission provider tests | `test/presentation/providers/permission_provider_test.dart` | 1.5h |
| 5.4 | Store detail provider tests | `test/presentation/providers/store_detail_provider_test.dart` | 1h |
| 5.5 | Queue provider tests | `test/presentation/providers/queue_provider_test.dart` | 1h |
| 5.6 | Completed buys provider tests | `test/presentation/providers/completed_buys_provider_test.dart` | 1h |
| 5.7 | Today performance provider tests | `test/presentation/providers/today_performance_provider_test.dart` | 1h |
| 5.8 | Workbook notes provider tests | `test/presentation/providers/workbook_notes_provider_test.dart` | 1h |
| 5.9 | Today tasks provider tests | `test/presentation/providers/today_tasks_provider_test.dart` | 1h |

**Test Count**: ~45 tests (5 per provider)

**Acceptance Criteria**:
- [ ] Loading → Data → Error state transitions tested
- [ ] Dashboard auth error caching (30s) tested
- [ ] Family providers tested with different parameters
- [ ] Refresh functionality tested

---

### Phase 6: Integration Tests (4 hours)
**Goal**: End-to-end flow validation

| Task | Description | Files | Est. Time |
|------|-------------|-------|-----------|
| 6.1 | Convert auth flow example to real test | `test/integration/auth_flow_integration_test.dart` | 2h |
| 6.2 | Dashboard navigation integration test | `test/integration/dashboard_navigation_test.dart` | 2h |

**Test Count**: ~10 tests

**Acceptance Criteria**:
- [ ] Auth flow from key entry to dashboard tested
- [ ] Navigation with permission guards tested
- [ ] Error recovery flow tested

---

## Implementation Order

```
Phase 1 (Foundation) ──┬──> Phase 2 (Core)
                       │
                       └──> Phase 3 (Domain)

Phase 2 + 3 Complete ──┬──> Phase 4 (Data/Mappers)
                       │
                       └──> Phase 5 (Presentation)

Phase 4 + 5 Complete ────> Phase 6 (Integration)
```

**Parallel Opportunities**:
- Phase 2 (Core) and Phase 3 (Domain) can run in parallel
- Phase 4 (Data) and Phase 5 (Presentation) can run in parallel
- Phase 6 requires all others complete

---

## Success Metrics

| Metric | Target | Verification |
|--------|--------|--------------|
| Total Tests | 150+ | `flutter test --reporter=expanded \| grep -c "✓"` |
| Overall Coverage | 60% | `flutter test --coverage && genhtml` |
| Core Coverage | 80% | lcov report filtering |
| Domain Coverage | 90% | lcov report filtering |
| CI Pipeline | Green | GitHub Actions status |
| Test Duration | < 30s | `flutter test` timing |

---

## Risk Mitigation

| Risk | Mitigation | Contingency |
|------|------------|-------------|
| Async test flakiness | Use proper `await` patterns | Add retry logic |
| Mock setup complexity | Centralized `test_mocks.dart` | Split by domain if too large |
| Coverage threshold too strict | Start with 60%, increase over time | Adjust in CI config |
| Generated code in coverage | Already excluded in CI | Verify exclusion patterns |

---

## Quick Reference Commands

```bash
# Run all tests
flutter test

# Run with coverage
flutter test --coverage

# Run specific test file
flutter test test/core/utils/json_parsing_test.dart

# Run tests matching pattern
flutter test --name "parseDouble"

# Generate HTML coverage report
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

# Run tests in CI mode (verbose)
flutter test --reporter=expanded
```

---

## Checklist for Implementation Start

Before starting implementation, verify:

- [ ] Flutter SDK 3.38.3 installed
- [ ] `flutter pub get` runs successfully
- [ ] `flutter test` runs (even if only smoke test passes)
- [ ] GitHub Actions workflow file exists at `.github/workflows/test.yml`
- [ ] Existing test files are readable:
  - [ ] `test/fixtures/test_mocks.dart`
  - [ ] `test/presentation/providers/dashboard_provider_test_example.dart`
  - [ ] `test/integration/auth_flow_integration_test_example.dart`

---

## Notes for Implementer

1. **Prioritize high-value tests first**: Permission system, JSON parsing, auth flow
2. **Follow existing patterns**: Use `dashboard_provider_test_example.dart` as template
3. **Don't skip teardown**: Always use `addTearDown(container.dispose)`
4. **Test both paths**: Happy path AND error handling for each component
5. **Keep tests fast**: No network calls, no file I/O in unit tests
6. **Name tests descriptively**: Test name should describe what's being verified

---

*This implementation plan is ready for execution via `/start:implement 001`*