Replace MockCommand framework-testing examples with practical pattern

- Show real DataService with command using get_it for dependencies
- MockDataService implements DataService and overrides with MockCommand
- DataManager listens to service command and maintains own state
- Demonstrate both queued results (with loadData) and manual simulation
- Full dependency injection pattern throughout
- Remove 400+ lines of framework behavior testing bloat

Author: escamoteur

code_samples/test/command_it/mock_command_example_test.dart

@@ -1,113 +1,150 @@
 import 'package:command_it/command_it.dart';
 import 'package:flutter_test/flutter_test.dart';
+import 'package:get_it/get_it.dart';
+
+final getIt = GetIt.instance;
+
+// Stub for example
+class Item {
+  final String id;
+  final String name;
+  Item(this.id, this.name);
+}
+
+class ApiClient {
+  Future<List<Item>> search(String query) async {
+    await Future.delayed(Duration(milliseconds: 100));
+    return [Item('1', 'Result for $query')];
+  }
+}
 
 // #region example
-/// Example service that uses a command (for dependency injection in tests)
+/// Real service with actual command
 class DataService {
-  final Command<void, List<String>> loadCommand;
+  late final loadCommand = Command.createAsync<String, List<Item>>(
+    (query) => getIt<ApiClient>().search(query),
+    initialValue: [],
+  );
+}
 
-  DataService({required this.loadCommand});
+/// Mock service for testing - overrides command with MockCommand
+class MockDataService implements DataService {
+  @override
+  late final loadCommand = _mockCommand;
 
-  void loadData() {
-    loadCommand.run();
+  final _mockCommand = MockCommand<String, List<Item>>(
+    initialValue: [],
+  );
+
+  // Control methods make tests readable and maintainable
+  void simulateLoading() {
+    _mockCommand.startExecution();
+  }
+
+  void simulateSuccess(List<Item> data) {
+    _mockCommand.endExecutionWithData(data);
+  }
+
+  void simulateError(String message) {
+    _mockCommand.endExecutionWithError(message);
   }
 }
 
-void main() {
-  group('MockCommand Examples', () {
-    test('Queue results with CommandResult', () async {
-      final mockLoadCommand = MockCommand<void, List<String>>(
-        initialValue: [],
-      );
-
-      // Queue results for the next execution using CommandResult
-      mockLoadCommand.queueResultsForNextExecuteCall([
-        CommandResult<void, List<String>>(
-            null, ['Item 1', 'Item 2', 'Item 3'], null, false),
-      ]);
+// Code that depends on DataService
+class DataManager {
+  DataManager() {
+    // Listen to service command and update local state
+    getIt<DataService>().loadCommand.isRunning.listen((running, _) {
+      _isLoading = running;
+    });
 
-      // Inject into service
-      final service = DataService(loadCommand: mockLoadCommand);
+    getIt<DataService>().loadCommand.listen((data, _) {
+      _currentData = data;
+    });
+  }
 
-      // Trigger the command
-      service.loadData();
+  bool _isLoading = false;
+  bool get isLoading => _isLoading;
 
-      // Verify the command was called
-      expect(mockLoadCommand.executionCount, 1);
+  List<Item> _currentData = [];
+  List<Item> get currentData => _currentData;
 
-      // Verify the result
-      expect(mockLoadCommand.value, ['Item 1', 'Item 2', 'Item 3']);
-    });
+  Future<void> loadData(String query) async {
+    getIt<DataService>().loadCommand(query);
+  }
+}
 
-    test('Manually control execution states', () {
-      final mockCommand = MockCommand<void, String>(
-        initialValue: '',
-      );
+void main() {
+  group('MockCommand Pattern', () {
+    test('Test manager with mock service - success state', () async {
+      final mockService = MockDataService();
+      getIt.registerSingleton<DataService>(mockService);
 
-      // Initially not running
-      expect(mockCommand.isRunning.value, false);
+      final manager = DataManager();
 
-      // Start execution manually
-      mockCommand.startExecution();
-      expect(mockCommand.isRunning.value, true);
+      final testData = [Item('1', 'Test Item')];
 
-      // Complete execution with data
-      mockCommand.endExecutionWithData('loaded data');
-      expect(mockCommand.isRunning.value, false);
-      expect(mockCommand.value, 'loaded data');
-    });
+      // Queue result for the next execution
+      mockService._mockCommand.queueResultsForNextExecuteCall([
+        CommandResult<String, List<Item>>('test', testData, null, false),
+      ]);
 
-    test('Simulate error scenarios', () {
-      final mockCommand = MockCommand<void, String>(
-        initialValue: '',
-      );
+      // Execute the command through the manager
+      await manager.loadData('test');
 
-      CommandError? capturedError;
-      mockCommand.errors.listen((error, _) => capturedError = error);
+      // Wait for listener to fire
+      await Future.delayed(Duration.zero);
 
-      // Simulate error with String message (not Exception)
-      mockCommand.startExecution();
-      mockCommand.endExecutionWithError('Network error');
+      // Verify success state
+      expect(manager.isLoading, false);
+      expect(manager.currentData, testData);
 
-      expect(capturedError?.error.toString(), contains('Network error'));
-      expect(mockCommand.isRunning.value, false);
+      // Cleanup
+      await getIt.reset();
     });
 
-    test('Complete execution without data (void commands)', () {
-      final mockCommand = MockCommand<void, void>(
-        initialValue: null,
-        noReturnValue: true,
-      );
-
-      var executionCompleted = false;
-      mockCommand.results.listen((result, _) {
-        if (!result.isRunning && !result.hasError) {
-          executionCompleted = true;
-        }
+    test('Test manager with mock service - error state', () async {
+      final mockService = MockDataService();
+      getIt.registerSingleton<DataService>(mockService);
+
+      final manager = DataManager();
+
+      CommandError? capturedError;
+      mockService.loadCommand.errors.listen((error, _) {
+        capturedError = error;
       });
 
-      mockCommand.startExecution();
-      mockCommand.endExecutionNoData();
+      // Simulate error without using loadData
+      mockService.simulateError('Network error');
+
+      // Wait for listener to fire
+      await Future.delayed(Duration.zero);
 
-      expect(executionCompleted, true);
-      expect(mockCommand.isRunning.value, false);
+      // Verify error state
+      expect(manager.isLoading, false);
+      expect(capturedError?.error.toString(), contains('Network error'));
+
+      // Cleanup
+      await getIt.reset();
     });
 
-    test('Track execution count', () {
-      final mockCommand = MockCommand<String, void>(
-        initialValue: null,
-        noReturnValue: true,
-      );
+    test('Real service works as expected', () async {
+      // Register real dependencies
+      getIt.registerSingleton<ApiClient>(ApiClient());
+      getIt.registerSingleton<DataService>(DataService());
+
+      final manager = DataManager();
+
+      // Test with real service
+      await manager.loadData('flutter');
 
-      expect(mockCommand.executionCount, 0);
+      await Future.delayed(Duration(milliseconds: 150));
 
-      mockCommand.run('test1');
-      expect(mockCommand.executionCount, 1);
-      expect(mockCommand.lastPassedValueToExecute, 'test1');
+      expect(manager.currentData.isNotEmpty, true);
+      expect(manager.currentData.first.name, contains('flutter'));
 
-      mockCommand.run('test2');
-      expect(mockCommand.executionCount, 2);
-      expect(mockCommand.lastPassedValueToExecute, 'test2');
+      // Cleanup
+      await getIt.reset();
     });
   });
 }

docs/documentation/command_it/testing.md

@@ -139,37 +139,9 @@ test('ErrorFilter routes errors correctly', () async {
 
 ## MockCommand
 
-### Using MockCommand
+For testing code that depends on commands, use the built-in `MockCommand` class to create controlled test environments. The pattern below shows how to create a real manager with actual commands, then a mock version for testing.
 
-For testing code that depends on commands, use the built-in `MockCommand` class instead of creating real commands:
-
-```dart
-import 'package:command_it/command_it.dart';
-
-test('Service uses command correctly', () async {
-  // Create a mock command
-  final mockLoadCommand = MockCommand<void, List<String>>(
-    initialValue: [],
-  );
-
-  // Queue results for the next execution
-  mockLoadCommand.queueResultsForNextExecuteCall([
-    CommandResult<void, List<String>>(null, ['Item 1', 'Item 2', 'Item 3'], null, false),
-  ]);
-
-  // Inject into service
-  final service = DataService(loadCommand: mockLoadCommand);
-
-  // Trigger the command
-  service.loadData();
-
-  // Verify the command was called
-  expect(mockLoadCommand.executionCount, 1);
-
-  // Verify the result
-  expect(mockLoadCommand.value, ['Item 1', 'Item 2', 'Item 3']);
-});
-```
+<<< @/../code_samples/test/command_it/mock_command_example_test.dart#example
 
 **Key MockCommand methods:**
 
@@ -180,62 +152,22 @@ test('Service uses command correctly', () async {
 - **`endExecutionWithError(String message)`** - Complete execution with an error
 - **`executionCount`** - Track how many times the command was executed
 
-**Testing loading states:**
-
-```dart
-test('UI shows loading indicator', () async {
-  final mockCommand = MockCommand<void, String>(
-    initialValue: '',
-  );
-
-  final loadingStates = <bool>[];
-  mockCommand.isRunning.listen((running, _) => loadingStates.add(running));
-
-  // Start execution manually
-  mockCommand.startExecution();
-  expect(mockCommand.isRunning.value, true);
-
-  // Complete execution
-  mockCommand.endExecutionWithData('loaded data');
-  expect(mockCommand.isRunning.value, false);
-
-  expect(loadingStates, [false, true, false]);
-});
-```
-
-**Testing error scenarios:**
-
-```dart
-test('UI shows error message', () {
-  final mockCommand = MockCommand<void, String>(
-    initialValue: '',
-  );
-
-  CommandError? capturedError;
-  mockCommand.errors.listen((error, _) => capturedError = error);
-
-  // Simulate error
-  mockCommand.startExecution();
-  mockCommand.endExecutionWithError('Network error');
-
-  expect(capturedError?.error.toString(), contains('Network error'));
-});
-```
-
-**Benefits of MockCommand:**
+**This pattern demonstrates:**
 
-- ✅ No async delays - tests run faster
-- ✅ Full control over execution state
-- ✅ Verify execution count
-- ✅ Queue multiple results for sequential calls
-- ✅ Test loading, success, and error states independently
-- ✅ No need for real business logic in tests
+<ul style="list-style: none; padding-left: 0;">
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ Real service with actual command using get_it for dependencies</li>
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ Mock service implements real service and overrides command with MockCommand</li>
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ Control methods make test code readable and maintainable</li>
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ Manager uses get_it to access service (full dependency injection)</li>
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ Tests register mock service to control command behavior</li>
+  <li style="padding-left: 1.5em; text-indent: -1.5em;">✅ No async delays - tests run instantly</li>
+</ul>
 
 **When to use MockCommand:**
 
-- Testing widgets that observe commands
-- Testing services that coordinate multiple commands
-- Unit testing command-dependent code
+- Testing code that depends on commands without async delays
+- Testing loading, success, and error state handling
+- Unit testing services that coordinate commands
 - When you need precise control over command state transitions
 
 ## See Also