Flutter Robot Pattern Tests

Flutter Testing Standards

by HoangNguyen0403 · MIT license · ★ 569 on GitHub

Write unit, widget, and integration tests with robot patterns, widget keys, and Patrol in Flutter. Use when implementing test behavior; defer CI-only configuration without test changes.

---
name: flutter-testing
description: Write unit, widget, and integration tests with robot patterns, widget keys, and Patrol in Flutter. Use when implementing test behavior; defer CI-only configuration without test changes.
metadata:
  triggers:
    files:
    - '**/test/**.dart'
    - '**/integration_test/**.dart'
    - '**/robots/**.dart'
    - 'lib/core/keys/**.dart'
    keywords:
    - test
    - patrol
    - robot
    - WidgetKeys
    - patrolTest
    - blocTest
    - mocktail

Overview

The Four Pillars provide a qualitative reasoning framework to assess test value: - Protection against Regressions ($P$): Catches real defects; evaluated qualitatively or via mutation kill score. A test that passes when defects exist has zero protection. - Resistance to Refactoring ($R$): Decoupled from implementation details; zero false alarms on internal refactorings or domain additions. Tests coupled to private state or mock sequences score low on resistance. - Fast Feedback ($F$): Executes in milliseconds; rapid local TDD feedback loop. - Maintainability ($M$): Clean AAA structure, fluent test data builders when setup repetition obscures intent, high readability, zero boilerplate…

Manual install (npx, ZIP)

Claude Codenpx skills add HoangNguyen0403/agent-skills-standard --skill flutter-testing -g -a claude-code

Claude Code (degit)npx degit HoangNguyen0403/agent-skills-standard/skills/flutter/flutter-testing#develop ~/.claude/skills/flutter-testing

Claude.ai / desktopZip the folder and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md5.3 KB

Read SKILL.md here

HoangNguyen0403/develop1 file shown

SKILL.md5.3 KB

Browse every file on GitHub↗

SKILL.md

Show the full text81 lines

flutter-testing/SKILL.md81 lines · 5.3 KB

PreviewCode

Outline

RawView on GitHub

Flutter Testing Standards

Priority: P0 (CRITICAL)

The Four-Pillar Test Value Framework

The Four Pillars provide a qualitative reasoning framework to assess test value:

Protection against Regressions ($P$): Catches real defects; evaluated qualitatively or via mutation kill score. A test that passes when defects exist has zero protection.
Resistance to Refactoring ($R$): Decoupled from implementation details; zero false alarms on internal refactorings or domain additions. Tests coupled to private state or mock sequences score low on resistance.
Fast Feedback ($F$): Executes in milliseconds; rapid local TDD feedback loop.
Maintainability ($M$): Clean AAA structure, fluent test data builders when setup repetition obscures intent, high readability, zero boilerplate duplication.

Avoid calculating or inventing arbitrary numeric scores (e.g. $P \times R \times F \times M$) statically without measured mutation or runtime evidence.

Core Rule Anchors

[MOB-TEST-01] Tripartite Naming: Name tests Method_Scenario_ExpectedBehavior.
[MOB-TEST-02] BLoC State Invariant Rule: Assert state transitions using isA<State>().having(...) predicates; BAN full copyWith mirrors.
[MOB-TEST-03] Entity Invariant & Serialization Rule: Test calculations, validations, domain invariants, and non-trivial serialization/parsing or error mapping. BAN testing generated code, trivial getters/setters, props, or echo tests (expect(item.discount, equals(5))) where the test merely repeats literal assignments.
[MOB-TEST-04] Contract Testing Rule: Repositories and data sources must be tested for contract compliance, golden JSON parsing, and error mapping. BAN 1:1 pass-through mock echoing (when(() => dataSource.get()).thenAnswer((_) async => x); expect(await repo.get(), x)).
[MOB-TEST-05] Bug-First Regression Lock: Every PR fixing a bug ticket or with title fix(...) must introduce a failing test reproducing the defect before fixing it.

Core Rules

Test Pyramid: Unit > Widget > Integration.
Naming: Follow [MOB-TEST-01] (Method_Scenario_ExpectedBehavior).
AAA: Arrange, Act, Assert in all tests.
Isolated Builders: Fluent builders when setup complexity warrants (OrderBuilder); avoid brittle shared global mocks.
File Placement: _integration_test.dart ONLY in integration_test/.
Robot-First: All UI assertions/interactions via Robot pattern (extending BaseRobot) — never raw find.*/expect() in test body. Use WidgetKeys constants from lib/core/keys/.
Negative Assertions: Add expectXxxNotVisible() in robot only when absence is part of the business contract (e.g. restricted action hidden), not blanket pairs for unrelated content.
Widget Testing & Mocking: Setup with TestWrapper.init() and tester.pumpLocalizedWidget(...). Register mock BLoCs with GetIt in setUpAll; stub state and stream in setUp (use whenListen and settle: false for loading/transition states). Prohibit any().
Integration Testing: Use patrolTest with IntegrationAuthHelper.loginOrSkip($) for auth flows and native interactions ($.native.*).

Anti-Patterns & Banned Smells

[MOB-TEST-01] Vague names: Banish non-descriptive names (testCart).
[MOB-TEST-02] Brittle state mirrors: Ban 30-property copyWith trees in blocTest; use isA<State>().having(...).
[MOB-TEST-03] Entity echo tests: Ban asserting trivial field assignments or auto-generated boilerplate (discount: 5). Meaningful serialization/parsing error handling remains valid.
[MOB-TEST-04] Pass-through mock echoing: Ban 1:1 repository-to-datasource pass-through mocks without contract assertions.
[MOB-TEST-05] Missing bug reproduction: Ban bug fix PRs without reproduction tests.
No blanket negative assertions: Avoid asserting absence of unrelated content.
No inline Key: Use WidgetKeys constant. No any(): Use typed matchers.
No local mocks: Use test/shared/. No missing bloc stub: Stub state + stream.
No test-body logic: Move find.*/expect() to robot. No raw find in integration tests.
No unchecked text casing: Verify .toUpperCase(), .tr() in source.

Verification

Repositories use fakes over mocks where appropriate.
Distinct BLoC/ViewModel behaviors covered (loading, success, error) with isA<State>().having(...).
Views with distinct UI logic tested via Robot pattern at proper layer.
Critical user flows have at least one integration test using patrolTest.
flutter test passes.

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

GetIt registration
Register the mock with GetIt in setUpAll before building the widget under test.
native interactions

1	---
2	name: flutter-testing
3	description: Write unit, widget, and integration tests with robot patterns, widget keys, and Patrol in Flutter. Use when implementing test behavior; defer CI-only configuration without test changes.
4	metadata:
5	triggers:
6	files:
7	- '/test/.dart'
8	- '/integration_test/.dart'
9	- '/robots/.dart'
10	- 'lib/core/keys/**.dart'
11	keywords:
12	- test
13	- patrol
14	- robot
15	- WidgetKeys
16	- patrolTest
17	- blocTest
18	- mocktail
19	---
20	# Flutter Testing Standards
21
22	## Priority: P0 (CRITICAL)
23
24	## The Four-Pillar Test Value Framework
25
26	The Four Pillars provide a qualitative reasoning framework to assess test value:
27	- Protection against Regressions ($P$): Catches real defects; evaluated qualitatively or via mutation kill score. A test that passes when defects exist has zero protection.
28	- Resistance to Refactoring ($R$): Decoupled from implementation details; zero false alarms on internal refactorings or domain additions. Tests coupled to private state or mock sequences score low on resistance.
29	- Fast Feedback ($F$): Executes in milliseconds; rapid local TDD feedback loop.
30	- Maintainability ($M$): Clean AAA structure, fluent test data builders when setup repetition obscures intent, high readability, zero boilerplate duplication.
31
32	Avoid calculating or inventing arbitrary numeric scores (e.g. $P \times R \times F \times M$) statically without measured mutation or runtime evidence.
33
34	## Core Rule Anchors
35
36	- `[MOB-TEST-01]` Tripartite Naming: Name tests `Method_Scenario_ExpectedBehavior`.
37	- `[MOB-TEST-02]` BLoC State Invariant Rule: Assert state transitions using `isA<State>().having(...)` predicates; BAN full copyWith mirrors.
38	- `[MOB-TEST-03]` Entity Invariant & Serialization Rule: Test calculations, validations, domain invariants, and non-trivial serialization/parsing or error mapping. BAN testing generated code, trivial getters/setters, `props`, or echo tests (`expect(item.discount, equals(5))`) where the test merely repeats literal assignments.
39	- `[MOB-TEST-04]` Contract Testing Rule: Repositories and data sources must be tested for contract compliance, golden JSON parsing, and error mapping. BAN 1:1 pass-through mock echoing (`when(() => dataSource.get()).thenAnswer((_) async => x); expect(await repo.get(), x)`).
40	- `[MOB-TEST-05]` Bug-First Regression Lock: Every PR fixing a bug ticket or with title `fix(...)` must introduce a failing test reproducing the defect before fixing it.
41
42	## Core Rules
43
44	1. Test Pyramid: Unit > Widget > Integration.
45	2. Naming: Follow `[MOB-TEST-01]` (`Method_Scenario_ExpectedBehavior`).
46	3. AAA: Arrange, Act, Assert in all tests.
47	4. Isolated Builders: Fluent builders when setup complexity warrants (`OrderBuilder`); avoid brittle shared global mocks.
48	5. File Placement: `_integration_test.dart` ONLY in `integration_test/`.
49	6. Robot-First: All UI assertions/interactions via Robot pattern (extending `BaseRobot`) — never raw `find.*`/`expect()` in test body. Use `WidgetKeys` constants from `lib/core/keys/`.
50	7. Negative Assertions: Add `expectXxxNotVisible()` in robot only when absence is part of the business contract (e.g. restricted action hidden), not blanket pairs for unrelated content.
51	8. Widget Testing & Mocking: Setup with `TestWrapper.init()` and `tester.pumpLocalizedWidget(...)`. Register mock BLoCs with `GetIt` in `setUpAll`; stub `state` and `stream` in `setUp` (use `whenListen` and `settle: false` for loading/transition states). Prohibit `any()`.
52	9. Integration Testing: Use `patrolTest` with `IntegrationAuthHelper.loginOrSkip($)` for auth flows and `native interactions` (`$.native.*`).
53
54	## Anti-Patterns & Banned Smells
55
56	- `[MOB-TEST-01]` Vague names: Banish non-descriptive names (`testCart`).
57	- `[MOB-TEST-02]` Brittle state mirrors: Ban 30-property `copyWith` trees in `blocTest`; use `isA<State>().having(...)`.
58	- `[MOB-TEST-03]` Entity echo tests: Ban asserting trivial field assignments or auto-generated boilerplate (`discount: 5`). Meaningful serialization/parsing error handling remains valid.
59	- `[MOB-TEST-04]` Pass-through mock echoing: Ban 1:1 repository-to-datasource pass-through mocks without contract assertions.
60	- `[MOB-TEST-05]` Missing bug reproduction: Ban bug fix PRs without reproduction tests.
61	- No blanket negative assertions: Avoid asserting absence of unrelated content.
62	- No inline Key: Use `WidgetKeys` constant. No `any()`: Use typed matchers.
63	- No local mocks: Use `test/shared/`. No missing bloc stub: Stub `state` + `stream`.
64	- No test-body logic: Move `find.*`/`expect()` to robot. No raw find in integration tests.
65	- No unchecked text casing: Verify `.toUpperCase()`, `.tr()` in source.
66
67	## Verification
68
69	- [ ] Repositories use fakes over mocks where appropriate.
70	- [ ] Distinct BLoC/ViewModel behaviors covered (loading, success, error) with `isA<State>().having(...)`.
71	- [ ] Views with distinct UI logic tested via Robot pattern at proper layer.
72	- [ ] Critical user flows have at least one integration test using `patrolTest`.
73	- [ ] `flutter test` passes.
74
75	## Canonical response anchors
76
77	When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
78	- GetIt registration
79	- Register the mock with `GetIt` in `setUpAll` before building the widget under test.
80	- native interactions
81