@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/flutter/testing/references/bloc-testing.md

@@ -0,0 +1,38 @@
+# BLoC Testing with `bloc_test`
+
+`blocTest` ensures your events trigger the correct sequence of states.
+
+## **Success Scenario**
+
+```dart
+blocTest<AuthBloc, AuthState>(
+  'emits [loading, authenticated] when login is successful',
+  build: () {
+    // Stub the repository
+    when(() => mockAuthRepo.login(any(), any()))
+        .thenAnswer((_) async => Right(mockUser));
+    return AuthBloc(mockAuthRepo);
+  },
+  act: (bloc) => bloc.add(const AuthEvent.loginPressed('test@email.com', 'pass123')),
+  expect: () => [
+    const AuthState.loading(),
+    AuthState.authenticated(mockUser),
+  ],
+  verify: (_) {
+    verify(() => mockAuthRepo.login('test@email.com', 'pass123')).called(1);
+  },
+);
+```
+
+## **Best Practices & Pitfalls**
+
+- **Do not mock based on State**: Do not use values in the BLoC state to mock data or verify calls. This is unreliable because it tracks the number of times a state is emitted (which can happen multiple times) rather than verifying the actual event trigger. Always verify the downstream Dependency/Service call in the `verify` block.
+- **Initial State verification**
+
+Always ensure your BLoC doesn't emit anything just by being created unless specified.
+
+```dart
+test('initial state is AuthState.initial', () {
+  expect(AuthBloc(mockRepo).state, const AuthState.initial());
+});
+```

package/rules/flutter/testing/references/integration-testing.md

@@ -0,0 +1,128 @@
+# Advanced Integration Testing
+
+Expert strategies for running "hard" tests (Native, Network, Time) reliably on CI.
+
+## The Core Problem
+
+Standard flutter `integration_test` struggles with:
+
+1. **Native UI**: Permission dialogs, Notifications, Dark Mode toggles.
+2. **WebViews**: Logging in via 3rd party identity providers.
+3. **Flakiness**: `pumpAndSettle` hanging on infinite animations.
+
+## Recommended Tool: Patrol
+
+[Patrol](https://pub.dev/packages/patrol) extends Flutter's testing capabilities to interact with the OS.
+
+### Why Patrol?
+
+- **Native Interactions**: `$.native.tap()` to query OS/native views.
+- **Improved Finders**: `$(#email)` instead of `find.byKey(Key('email'))`.
+- **Better Waiters**: `waitUntilVisible()` handles spinners correctly (unlike `pumpAndSettle`).
+
+### Setup
+
+1. Add dependency: `dev_dependencies: patrol: ^3.0.0`
+2. Create test file: `integration_test/app_test.dart`
+
+```dart
+import 'package:patrol/patrol.dart';
+
+void main() {
+  patrolTest(
+    'Login and accept permissions',
+    nativeAutomation: true, // Enable native controls
+    ($) async {
+      await $.pumpWidgetAndSettle(MyApp());
+
+      // 1. Flutter Interaction (Concise Syntax)
+      await $(#emailField).enterText('user@test.com');
+      await $(#passwordField).enterText('password123');
+      await $('Login').tap();
+
+      // 2. Native Interaction (The Killer Feature)
+      if (await $.native.isPermissionDialogVisible()) {
+        await $.native.grantPermissionWhenInUse();
+      }
+
+      // 3. WebViews (if needed)
+      // await $.native.tap(Selector(text: 'Accept Cookies'));
+    },
+  );
+}
+```
+
+## Strategy 1: Real Environment (End-to-End)
+
+Run tests against a real staging/dev backend to verify the full system. Do **not** mock the HTTP client in Integration Tests unless strictly necessary for hermeticity.
+
+```bash
+# Run with Patrol
+patrol test -t integration_test/app_test.dart --dart-define=ENV=staging
+```
+
+```dart
+// main.dart
+void main() {
+  final env = String.fromEnvironment('ENV', defaultValue: 'prod');
+  runApp(MyApp(config: Config.fromEnv(env)));
+}
+```
+
+## Strategy 2: Robust Waiters
+
+Avoid `pumpAndSettle()` for any screen with a `CircularProgressIndicator` or Lottie animation, as it will timeout waiting for the "animation" to settle.
+
+**Use Patrol's `waitUntilVisible`**:
+
+```dart
+// BAD
+// await $.pumpAndSettle(); // Times out if a spinner is running
+
+// GOOD
+await $('Welcome Home').waitUntilVisible(timeout: Duration(seconds: 10));
+```
+
+**Legacy (If not using Patrol)**:
+You must write a custom extension to pump frames manually.
+
+```dart
+extension PumpUntilFound on WidgetTester {
+  Future<void> pumpUntilFound(Finder finder) async {
+    while (!any(finder)) {
+      await pump(const Duration(milliseconds: 100));
+    }
+  }
+}
+```
+
+## Strategy 3: Handling Long Delays
+
+For flows involving long waits (e.g., "Verification code expires in 5 minutes"), waiting real time is impractical.
+
+**Approach**: Configure the app to use shorter durations in non-production environments.
+
+```dart
+// Code
+class TimerWidget extends StatelessWidget {
+  final Duration duration; // Configurable
+  const TimerWidget({this.duration = const Duration(minutes: 5)});
+}
+
+// Test
+await $.pumpWidget(TimerWidget(duration: Duration(seconds: 1)));
+await $('Resend Code').waitUntilVisible(); // Done instantly
+```
+
+## Strategy 4: Debugging Failures
+
+Patrol automatically handles taking screenshots on failure if configured, but you can also do it manually.
+
+```dart
+// Patrol automatically captures screenshots on failure in `patrol test` output.
+// No boilerplate needed.
+```
+
+## Related Topics
+
+[Robot Pattern](./robot-pattern.md) | [Github Actions](../../cicd/references/github-actions.md)

package/rules/flutter/testing/references/robot-pattern.md

@@ -0,0 +1,82 @@
+# Robot Pattern (Page Object Model)
+
+For maintainable widget and integration tests, decouple the "what" (business logic/asserts) from the "how" (finding widgets).
+
+## Why?
+
+- **Readability**: Tests read like user stories.
+- **Reusability**: One Robot works for both **Widget Tests** and **Integration Tests** (shared API).
+- **Resilience**: If a widget key changes, you update only the Robot, not 50 tests.
+
+## Directory Structure
+
+Place robots in `test/robots/` so they can be imported by `test/widget/` and `integration_test/` folders.
+
+```text
+test/
+  robots/
+    login_robot.dart
+  widget/
+    login_test.dart
+integration_test/
+  full_app_test.dart
+```
+
+## Example
+
+### The Robot Class (`test/robots/login_robot.dart`)
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+class LoginRobot {
+  final WidgetTester tester;
+
+  LoginRobot(this.tester);
+
+  // Finders (Private)
+  final _emailField = find.byKey(const Key('emailKey'));
+  final _passwordField = find.byKey(const Key('passwordKey'));
+  final _loginButton = find.byType(ElevatedButton);
+
+  // Actions
+  Future<void> enterEmail(String email) async {
+    await tester.enterText(_emailField, email);
+    await tester.pump();
+  }
+
+  Future<void> enterPassword(String password) async {
+    await tester.enterText(_passwordField, password);
+    await tester.pump();
+  }
+
+  Future<void> tapLogin() async {
+    await tester.tap(_loginButton);
+    await tester.pumpAndSettle();
+  }
+
+  // Assertions
+  void expectErrorShown() {
+    expect(find.text('Invalid credentials'), findsOneWidget);
+  }
+}
+```
+
+### The Test (`test/widget/login_screen_test.dart`)
+
+```dart
+testWidgets('Login failure flow', (tester) async {
+  // 1. Init
+  await tester.pumpWidget(myApp());
+  final robot = LoginRobot(tester);
+
+  // 2. Interact (Readable DSL)
+  await robot.enterEmail('bad@email.com');
+  await robot.enterPassword('wrong');
+  await robot.tapLogin();
+
+  // 3. Verify
+  robot.expectErrorShown();
+});
+```

package/rules/flutter/testing/references/unit-testing.md

@@ -0,0 +1,130 @@
+# Unit Testing Strategies
+
+Unit tests verify the smallest parts of your application (functions, methods, classes) in isolation.
+
+## Core Rules
+
+1. **Isolation**: External dependencies (API, Database, SharedPreferences) **must** be mocked.
+2. **Scope**: One test file per source file (e.g., `user_repository.dart` -> `user_repository_test.dart`).
+3. **Arrange-Act-Assert (AAA)**: Follow this structure strictly.
+
+## Advanced Techniques
+
+### 1. Test Data Builders
+
+Avoid hardcoding large objects in every test. Use a Builder pattern to generate valid default data with overrides.
+
+```dart
+class UserBuilder {
+  String _id = '1';
+  String _name = 'Default User';
+
+  UserBuilder withId(String id) {
+    _id = id;
+    return this;
+  }
+
+  User build() => User(id: _id, name: _name);
+}
+
+// Usage in test
+final user = UserBuilder().withId('99').build();
+```
+
+### 2. Mocking with Mocktail
+
+We prefer `mocktail` over `mockito` for its null-safety and simplicity.
+
+```dart
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+
+// 1. Create Mock
+class MockUserRepository extends Mock implements UserRepository {}
+
+void main() {
+  late MockUserRepository mockRepo;
+  late GetUserProfileUseCase useCase;
+
+  setUp(() {
+    mockRepo = MockUserRepository();
+    useCase = GetUserProfileUseCase(mockRepo);
+
+    // Register fallback values if needed
+    registerFallbackValue(User.empty());
+  });
+
+  // 2. Test Group
+  group('GetUserProfileUseCase', () {
+    test('should return User when repository succeeds', () async {
+      // ARRANGE
+      final user = UserBuilder().build();
+      when(() => mockRepo.getUser('1')).thenAnswer((_) async => Right(user));
+
+      // ACT
+      final result = await useCase('1');
+
+      // ASSERT
+      expect(result, Right(user));
+      verify(() => mockRepo.getUser('1')).called(1);
+    });
+
+    test('should return Failure when repository fails', () async {
+      // ARRANGE
+      when(() => mockRepo.getUser(any())).thenThrow(ServerException());
+
+      // ACT
+      final call = useCase('1');
+
+      // ASSERT
+      expect(call, throwsA(isA<ServerException>()));
+    });
+  });
+}
+```
+
+## Best Practices & Anti-Patterns (DCM)
+
+Avoid common testing mistakes identified by Dart Code Metrics.
+
+### 1. Assertions are Mandatory
+
+Never write a test that just "runs" without verifying anything.
+
+```dart
+// BAD
+test('fetchUser runs', () async {
+  await repo.fetchUser();
+  // ❌ No assertion - test passes even if logic is broken
+});
+
+// GOOD
+test('fetchUser returns data', () async {
+  final result = await repo.fetchUser();
+  expect(result, isNotNull); // ✅ Always verify result
+});
+```
+
+### 2. Use Proper Matchers
+
+Use specific matchers for better error messages.
+
+```dart
+// BAD
+expect(list.length, 1); // Message: "Expected: <1> Actual: <0>"
+
+// GOOD
+expect(list, hasLength(1)); // Message: "Expected: list with length <1> Actual: list with length <0> [...]"
+```
+
+### 3. Async Expectations
+
+When testing Streams or Futures validation, use `expectLater` to ensure the test waits.
+
+```dart
+// BAD
+expect(stream, emits(1)); // Might finish test before stream emits
+
+// GOOD
+await expectLater(stream, emits(1));
+```

package/rules/flutter/testing/references/widget-testing.md

@@ -0,0 +1,120 @@
+# Widget Testing Strategies
+
+Widget tests verify the UI and interaction of valid widgets in a simulated environment (headless).
+
+## Core Rules
+
+1. **Wrapper**: Always wrap widgets in `MaterialApp`/`CupertinoApp` to provide Theme/Navigator context.
+2. **Pump**:
+   - `pump()`: Triggers a frame.
+   - `pumpAndSettle()`: Wait for all animations to complete.
+3. **Finders**: Use semantic finders (`find.text`, `find.byKey`, `find.byType`) to locate elements.
+
+## Advanced: The Robot Pattern
+
+For complex screens, avoid scattering `find.by...` references throughout your tests. Use a **Robot** to encapsulate UI interactions.
+
+Reference: [Robot Pattern Implementation](./robot-pattern.md)
+
+### Updated Example: Testing a Login Screen
+
+```dart
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutter_bloc/flutter_bloc.dart';
+import 'package:mocktail/mocktail.dart';
+import 'robots/login_robot.dart'; // Import your robot
+
+void main() {
+  late MockAuthBloc mockAuthBloc;
+
+  setUp(() {
+    mockAuthBloc = MockAuthBloc();
+    when(() => mockAuthBloc.state).thenReturn(AuthInitial());
+  });
+
+  Widget createWidget() {
+    return MaterialApp(
+      home: BlocProvider<AuthBloc>.value(
+        value: mockAuthBloc,
+        child: LoginScreen(),
+      ),
+    );
+  }
+
+  testWidgets('shows loading indicator when state is Loading', (tester) async {
+    // ARRANGE
+    when(() => mockAuthBloc.state).thenReturn(AuthLoading());
+    final robot = LoginRobot(tester);
+
+    // ACT
+    await tester.pumpWidget(createWidget());
+
+    // ASSERT
+    robot.expectLoadingVisible();
+  });
+
+  testWidgets('triggers login event on button tap', (tester) async {
+    // ARRANGE
+    final robot = LoginRobot(tester);
+    await tester.pumpWidget(createWidget());
+
+    // ACT
+    await robot.enterEmail('test@example.com');
+    await robot.enterPassword('password123');
+    await robot.tapLogin();
+
+    // ASSERT
+    verify(() => mockAuthBloc.add(LoginSubmitted(
+      email: 'test@example.com',
+      password: 'password123'
+    ))).called(1);
+  });
+}
+```
+
+## Handling Screen Variability
+
+One of the most common mistakes is testing only on the default 800x600 surface.
+
+### 1. Multi-Screen Golden Tests
+
+Use `golden_toolkit` to verify responsive layouts across multiple devices.
+
+```dart
+testGoldens('Login Screen responsive layout', (tester) async {
+  final builder = DeviceBuilder()
+    ..overrideDevicesForAllScenarios(devices: [
+      Device.phone,
+      Device.iphone11,
+      Device.tabletPortrait,
+      Device.tabletLandscape,
+    ])
+    ..addScenario(
+      widget: LoginScreen(),
+      name: 'Default State',
+    );
+
+  await tester.pumpDeviceBuilder(builder);
+  await screenMatchesGolden(tester, 'login_screen_responsive');
+});
+```
+
+### 2. Manual Screen Resizing
+
+If not using goldens, explicitly force screen sizes to test overflows.
+
+```dart
+testWidgets('Login on small screen', (tester) async {
+  // Set Surface Size to a small phone
+  tester.binding.window.physicalSizeTestValue = Size(320, 480);
+  tester.binding.window.devicePixelRatioTestValue = 1.0;
+  addTearDown(tester.binding.window.clearPhysicalSizeTestValue);
+
+  await tester.pumpWidget(createWidget());
+
+  // Verify no overflow errors
+  expect(tester.takeException(), isNull);
+  // Using a custom finder to check if something is visible only on scroll
+  await tester.scrollUntilVisible(find.text('Login'), 50);
+});
+```

package/rules/flutter/widgets/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: Flutter UI Widgets
+description: Principles for maintainable UI components.
+metadata:
+  labels: [ui, widgets]
+  triggers:
+    files: ['**_page.dart', '**_screen.dart', '**/widgets/**']
+    keywords: [StatelessWidget, const, Theme, ListView]
+---
+
+# UI & Widgets (P1)
+
+- **State**: Use `StatelessWidget` by default. `StatefulWidget` only for local state/controllers.
+- **Composition**: Extract UI into small, atomic `const` widgets.
+- **Theming**: Use `Theme.of(context)`. No hardcoded colors.
+- **Layout**: Use `Flex` + `Gap/SizedBox`.
+- **Specialized**:
+  - `SelectionArea`: For multi-widget text selection.
+  - `InteractiveViewer`: For zoom/pan.
+  - `ListWheelScrollView`: For pickers.
+  - `IntrinsicWidth/Height`: Avoid unless strictly required.
+- **Large Lists**: Always use `ListView.builder`.
+
+```dart
+class AppButton extends StatelessWidget {
+  final String label;
+  final VoidCallback onPressed;
+  const AppButton({super.key, required this.label, required this.onPressed});
+
+  @override
+  Widget build(BuildContext context) => ElevatedButton(onPressed: onPressed, child: Text(label));
+}
+```
+
+## Related Topics
+
+performance | testing