mindsystem-cc 3.12.0 → 3.13.1

package/mindsystem/references/mock-patterns.md

@@ -1,21 +1,7 @@
 <overview>
-Mock patterns for manual UAT testing. Mocks are temporary scaffolding to reach testable UI states. They exist only as uncommitted changes — never in commit history.
+Mock patterns for manual UAT testing. Mocks are temporary inline edits to service methods — hardcoded return values that let you reach testable UI states. They exist only as uncommitted changes, never in commit history.
 </overview>
 
-<philosophy>
-**Mocks enable testing states you can't easily reach.**
-
-Without mocks, testing "error message display" requires actually triggering server errors. Testing "premium user badge" requires a premium account. Testing "empty list placeholder" requires deleting all data.
-
-**With mocks:** Set a flag, hot reload, test the UI state.
-
-**Core principles:**
-1. **Temporary** — Mocks are stashed/discarded, never committed
-2. **Minimal** — One override file, minimal production hooks
-3. **Explicit** — Clear flags, clear toggle instructions
-4. **Removable** — Delete file + remove imports = clean
-</philosophy>
-
 <classification_framework>
 
 **Two-question framework for mock classification:**
@@ -57,19 +43,161 @@ Domain terms don't map reliably to mock types. "View recipe list" needs external
 
 </classification_framework>
 
+<mock_types>
+
+| Mock Type | Enables Testing | Inline Pattern |
+|-----------|-----------------|----------------|
+| `error_state` | Error messages, retry UI, fallback displays | Throw exception before real implementation |
+| `premium_user` | Premium badges, gated features, upgrade prompts | Return mock user object with premium fields |
+| `empty_response` | Empty states, placeholder UI, "no results" | Return empty list/null before real implementation |
+| `loading_state` | Loading spinners, skeleton screens | Add delay before real implementation |
+| `offline` | Offline UI, cached data, sync indicators | Throw network error before real implementation |
+| `transient_state` | Brief async states (loading skeletons, transitions) | Delay or never-resolve strategies (see below) |
+| `external_data` | Features depending on API data that may not exist locally | Return hardcoded data objects |
+
+</mock_types>
+
+<inline_mock_patterns>
+
+**Inline mocks edit service methods directly.** Add hardcoded return values BEFORE the real implementation. Mark with `// MOCK:` comment for cleanup tracking.
+
+**Pattern:** Early return with mock comment
+```
+// MOCK: {description} — revert after UAT
+{hardcoded return/throw}
+
+// Real implementation below...
+```
+
+**By mock_type:**
+
+**error_state** — Throw before real call:
+```dart
+// Before:
+Future<User> login(String email, String password) async {
+  final response = await _api.post('/auth/login', data: {'email': email, 'password': password});
+  return User.fromJson(response.data);
+}
+
+// After:
+Future<User> login(String email, String password) async {
+  // MOCK: force login error — revert after UAT
+  throw Exception('Invalid credentials');
+
+  final response = await _api.post('/auth/login', data: {'email': email, 'password': password});
+  return User.fromJson(response.data);
+}
+```
+
+**empty_response** — Return empty collection:
+```dart
+// Before:
+Future<List<Recipe>> getRecipes() async {
+  final response = await _api.get('/recipes');
+  return response.data.map((j) => Recipe.fromJson(j)).toList();
+}
+
+// After:
+Future<List<Recipe>> getRecipes() async {
+  // MOCK: force empty list — revert after UAT
+  return [];
+
+  final response = await _api.get('/recipes');
+  return response.data.map((j) => Recipe.fromJson(j)).toList();
+}
+```
+
+**premium_user / external_data** — Return hardcoded object:
+```dart
+// Before:
+Future<User> getCurrentUser() async {
+  final response = await _api.get('/user/me');
+  return User.fromJson(response.data);
+}
+
+// After:
+Future<User> getCurrentUser() async {
+  // MOCK: force premium user — revert after UAT
+  return User(id: 'mock-001', name: 'Test User', isPremium: true, tier: 'gold');
+
+  final response = await _api.get('/user/me');
+  return User.fromJson(response.data);
+}
+```
+
+**TypeScript equivalents follow identical pattern** — early return/throw with `// MOCK:` comment before the real implementation.
+
+</inline_mock_patterns>
+
+<transient_state_patterns>
+
+**Transient states are UI states that appear briefly during async operations.** Loading skeletons, shimmer effects, transition animations — they resolve too fast to observe and test manually.
+
+**Two strategies:**
+
+**1. Extended delay (default):**
+
+Add a configurable delay before the real data returns. The transient state stays visible long enough to test.
+
+```dart
+// MOCK: extend loading state for testing — revert after UAT
+await Future.delayed(const Duration(seconds: 5));
+
+// Real implementation continues...
+final response = await _api.get('/recipes');
+return response.data.map((j) => Recipe.fromJson(j)).toList();
+```
+
+```typescript
+// MOCK: extend loading state for testing — revert after UAT
+await new Promise(resolve => setTimeout(resolve, 5000));
+
+// Real implementation continues...
+const response = await fetch('/api/recipes');
+return response.json();
+```
+
+**When to use:** Testing that the loading UI (skeleton, spinner) displays correctly while waiting.
+
+**2. Never-resolve:**
+
+The async call never completes. The transient state stays permanently visible.
+
+```dart
+// MOCK: freeze loading state — revert after UAT
+await Completer<void>().future; // Never completes
+
+// Real implementation continues...
+```
+
+```typescript
+// MOCK: freeze loading state — revert after UAT
+await new Promise(() => {}); // Never resolves
+
+// Real implementation continues...
+```
+
+**When to use:** Testing that the loading UI itself is correct (layout, styling, animation) without it disappearing.
+
+**Choosing between strategies:**
+- Testing the transition (loading → loaded): Use extended delay (5s default)
+- Testing the loading UI appearance: Use never-resolve
+
+</transient_state_patterns>
+
 <git_stash_lifecycle>
 
 **Why stash?**
 
-Fixes must be clean commits (no mock code). But after fixing, we need mocks back to re-test. Git stash enables this:
+Fixes must be clean commits (no mock code). But after fixing, mocks need to be restored to re-test. Git stash enables this:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │ Phase 1: Setup                                              │
 ├─────────────────────────────────────────────────────────────┤
 │ 1. git stash push -m "pre-verify-work" (if dirty)          │
-│ 2. Mock Generator creates mock code (uncommitted)           │
-│ 3. User confirms mocks look correct                         │
+│ 2. Inline mocks applied to service methods (uncommitted)    │
+│ 3. Mocked files tracked in UAT.md: mocked_files: [...]     │
 └─────────────────────────────────────────────────────────────┘
                               │
                               ▼
@@ -78,7 +206,7 @@ Fixes must be clean commits (no mock code). But after fixing, we need mocks back
 ├─────────────────────────────────────────────────────────────┤
 │ 4. User tests on device with mocks active                   │
 │ 5. User reports issue                                       │
-│ 6. git stash push -m "mocks-batch-N"  ← Stash mocks        │
+│ 6. git stash push -m "mocks-batch-N" -- <mocked_files>     │
 │ 7. Fixer investigates and commits fix  ← Clean commit      │
 │ 8. git stash pop                       ← Restore mocks     │
 │ 9. User re-tests specific item                             │
@@ -89,7 +217,7 @@ Fixes must be clean commits (no mock code). But after fixing, we need mocks back
 ┌─────────────────────────────────────────────────────────────┐
 │ Phase 3: Cleanup                                            │
 ├─────────────────────────────────────────────────────────────┤
-│ 11. git stash drop                     ← Discard mocks     │
+│ 11. git checkout -- <mocked_files>     ← Revert mocks      │
 │ 12. Generate UAT fixes patch                                │
 │ 13. git stash pop (if pre-existing)    ← Restore user work │
 └─────────────────────────────────────────────────────────────┘
@@ -97,7 +225,7 @@ Fixes must be clean commits (no mock code). But after fixing, we need mocks back
 
 **Stash naming convention:**
 - `pre-verify-work` — User's original uncommitted work
-- `mocks-batch-N` — Current mock state for batch N
+- `mocks-batch-N` — Current mock state for batch N (stashed only during fix application)
 
 </git_stash_lifecycle>
 
@@ -121,222 +249,3 @@ git add <conflicted-file>
 **This is rare.** Mocks typically live in data layer, fixes often in UI layer.
 
 </conflict_resolution>
-
-<flutter_example>
-
-**Override file: `lib/test_overrides.dart`**
-
-```dart
-// Test Overrides - DELETE THIS FILE BEFORE COMMITTING
-// Used for manual UAT testing only
-
-class TestOverrides {
-  // === STATE FLAGS ===
-  static bool forcePremiumUser = false;
-  static bool forceErrorState = false;
-  static bool forceEmptyResponse = false;
-  static bool forceLoadingState = false;
-  static bool forceTransientState = false;
-
-  // === MOCK DATA ===
-  static String mockErrorMessage = 'Simulated error for testing';
-  static Duration mockLoadingDelay = const Duration(seconds: 3);
-  static Duration mockTransientDelay = const Duration(seconds: 5);
-
-  static Map<String, dynamic> mockPremiumUser = {
-    'id': 'test-user-001',
-    'name': 'Test Premium User',
-    'isPremium': true,
-    'subscriptionTier': 'gold',
-  };
-
-  // === RESET ===
-  static void reset() {
-    forcePremiumUser = false;
-    forceErrorState = false;
-    forceEmptyResponse = false;
-    forceLoadingState = false;
-    forceTransientState = false;
-  }
-}
-```
-
-**Production hook: `lib/services/user_service.dart`**
-
-```dart
-import '../test_overrides.dart';
-
-class UserService {
-  Future<User> getCurrentUser() async {
-    // TEST OVERRIDE - Remove before commit
-    if (TestOverrides.forcePremiumUser) {
-      return User.fromJson(TestOverrides.mockPremiumUser);
-    }
-
-    // Real implementation
-    final response = await _api.get('/user/me');
-    return User.fromJson(response.data);
-  }
-
-  Future<List<Item>> getItems() async {
-    // TEST OVERRIDE - Remove before commit
-    if (TestOverrides.forceEmptyResponse) {
-      return [];
-    }
-    if (TestOverrides.forceErrorState) {
-      throw Exception(TestOverrides.mockErrorMessage);
-    }
-    // TEST OVERRIDE - Extend transient state (loading skeleton stays visible)
-    if (TestOverrides.forceTransientState) {
-      await Future.delayed(TestOverrides.mockTransientDelay);
-    }
-
-    // Real implementation
-    final response = await _api.get('/items');
-    return (response.data as List).map((j) => Item.fromJson(j)).toList();
-  }
-}
-```
-
-**Toggle instructions:**
-
-```
-To enable Premium User state:
-1. Open lib/test_overrides.dart
-2. Set TestOverrides.forcePremiumUser = true
-3. Hot reload (r in terminal)
-4. Verify: User profile shows "Premium" badge
-
-To enable Error State:
-1. Open lib/test_overrides.dart
-2. Set TestOverrides.forceErrorState = true
-3. Hot reload (r in terminal)
-4. Verify: Error message appears on relevant screens
-```
-
-</flutter_example>
-
-<react_example>
-
-**Override file: `src/testOverrides.ts`**
-
-```typescript
-// Test Overrides - DELETE THIS FILE BEFORE COMMITTING
-// Used for manual UAT testing only
-
-export const testOverrides = {
-  // === STATE FLAGS ===
-  forcePremiumUser: false,
-  forceErrorState: false,
-  forceEmptyResponse: false,
-  forceLoadingState: false,
-
-  // === MOCK DATA ===
-  mockErrorMessage: 'Simulated error for testing',
-  mockLoadingDelayMs: 3000,
-
-  mockPremiumUser: {
-    id: 'test-user-001',
-    name: 'Test Premium User',
-    isPremium: true,
-    subscriptionTier: 'gold',
-  },
-
-  // === RESET ===
-  reset() {
-    this.forcePremiumUser = false;
-    this.forceErrorState = false;
-    this.forceEmptyResponse = false;
-    this.forceLoadingState = false;
-  },
-};
-```
-
-**Production hook: `src/services/userService.ts`**
-
-```typescript
-import { testOverrides } from '../testOverrides';
-
-export async function getCurrentUser(): Promise<User> {
-  // TEST OVERRIDE - Remove before commit
-  if (testOverrides.forcePremiumUser) {
-    return testOverrides.mockPremiumUser as User;
-  }
-
-  // Real implementation
-  const response = await fetch('/api/user/me');
-  return response.json();
-}
-
-export async function getItems(): Promise<Item[]> {
-  // TEST OVERRIDE - Remove before commit
-  if (testOverrides.forceEmptyResponse) {
-    return [];
-  }
-  if (testOverrides.forceErrorState) {
-    throw new Error(testOverrides.mockErrorMessage);
-  }
-
-  // Real implementation
-  const response = await fetch('/api/items');
-  return response.json();
-}
-```
-
-**Toggle instructions:**
-
-```
-To enable Premium User state:
-1. Open src/testOverrides.ts
-2. Set forcePremiumUser: true
-3. Save file (auto hot reload in dev mode)
-4. Verify: User profile shows "Premium" badge
-
-To enable Error State:
-1. Open src/testOverrides.ts
-2. Set forceErrorState: true
-3. Save file (auto hot reload)
-4. Verify: Error message appears on relevant screens
-```
-
-</react_example>
-
-<best_practices>
-
-**Do:**
-- Keep all flags in one file
-- Use descriptive flag names (`forcePremiumUser` not `flag1`)
-- Add comments marking test-only code
-- Provide reset function
-- Document toggle instructions clearly
-
-**Don't:**
-- Create complex mock infrastructure
-- Add mocks in UI components (use service layer)
-- Commit mock code (ever)
-- Create multiple override files
-- Add conditional compilation / build flags
-
-**Signs you're over-engineering:**
-- More than one override file
-- Mock code in more than 3 production files
-- Complex mock data generators
-- Mocking at multiple layers simultaneously
-
-</best_practices>
-
-<cleanup>
-
-**After UAT complete:**
-
-1. `git stash drop` — Removes mock stash permanently
-2. Delete override file if still present
-3. Remove any imports/hooks still in production code
-
-**Verification:**
-```bash
-git status  # Should show no mock-related files
-grep -r "testOverrides" src/  # Should find nothing (or only the override file itself)
-```
-
-</cleanup>