flutter-testing
Use when testing Flutter code - unit tests for logic, widget tests for UI behavior, golden tests for appearance, the multi-size/text-scale/dark matrix, accessibility guidelines, test-first
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- flutter-testing
- source
- flutter/agent-plugins (BSD-3-Clause), adapted
- category
- testing
- tech_stack
- Flutter
- description
- Use when testing Flutter code - unit tests for logic, widget tests for UI behavior, golden tests for appearance, the multi-size/text-scale/dark matrix, accessibility guidelines, test-first
03 SKILL.md 正文
Flutter Testing
Overview
Test-first in Flutter (see tdd-workflow). Three layers, each for a different question: does the logic work, does the widget behave, does it look right.
Core principle: Most tests are fast unit + widget tests. Golden tests guard appearance; integration tests guard whole flows — use them sparingly.
Test layers
| Layer | Question | Tool |
|---|---|---|
| Unit | Does the controller/logic compute correctly? | flutter_test, mock the repository |
| Widget | Does the widget render state and respond to taps? | testWidgets + pumpWidget + finders |
| Golden | Does it match the approved pixels? | matchesGoldenFile |
| Integration | Does the whole flow work on a device? | integration_test |
Widget test example
testWidgets('shows error view and retries', (tester) async {
final controller = FakeTaskController()..emitError('boom');
await tester.pumpWidget(wrap(TaskListScreen(controller: controller)));
await tester.pump();
expect(find.text('boom'), findsOneWidget);
await tester.tap(find.byType(RetryButton));
await tester.pump();
expect(controller.loadCalled, isTrue); // intent reached the controller
});
Rules
- Unit-test controllers/logic without pumping a widget — that's the payoff of keeping logic out of widgets (see flutter-state-management).
- Widget tests assert observable behavior (text visible, tap triggers intent), not internal structure.
- Mock the repository/ports, not the widget under test. Prefer a hand-written fake or
mocktailper the app's convention. - Golden tests: commit the golden, review changes deliberately; regenerate only when the change is intended.
- Cover loading, data, empty, and error states — the branches most likely to ship broken.
pumpvspumpAndSettle: usepumpfor controlled frames,pumpAndSettleto drain animations — never rely on real timers.
Matrix test: size, text scale, dark mode
A widget test that only runs at the default size and text scale misses the most common mobile layout bug — overflow at larger text scales. See mobile-visual-self-review for the full size matrix and the worked PriceRow example (verified: passes at text scale 1.0 everywhere, overflows by 82px at 360×640/2.0). The shape:
tester.view.physicalSize = const Size(360, 640) * 3;
tester.view.devicePixelRatio = 3;
tester.platformDispatcher.textScaleFactorTestValue = 2.0;
addTearDown(tester.view.reset);
addTearDown(tester.platformDispatcher.clearAllTestValues);
Run this as a real testWidgets case per matrix cell for any screen/component whose layout changed — it is the failing test a layout change starts from (see tdd-first), not an afterthought bolted on once the happy path passes.
Accessibility guidelines (verified)
meetsGuideline from flutter_test/flutter/accessibility, run inside tester.ensureSemantics():
final handle = tester.ensureSemantics();
await expectLater(tester, meetsGuideline(androidTapTargetGuideline)); // 48x48
await expectLater(tester, meetsGuideline(iOSTapTargetGuideline)); // 44x44
await expectLater(tester, meetsGuideline(labeledTapTargetGuideline)); // every tappable has a label
await expectLater(tester, meetsGuideline(textContrastGuideline));
handle.dispose();
Run these against every new or changed interactive widget's test, not just a dedicated accessibility suite.
Golden test pitfalls (verified)
- Fonts: by default, text renders as box glyphs in a golden unless the app's real fonts are loaded in
flutter_test_config.dart(loadAppFonts()or equivalent) — a golden taken without that setup locks in boxes, not the real typography. Use goldens for layout/shape verification, or load the fonts first. - OS differences: text rendering and anti-aliasing differ per OS, so the same golden can legitimately differ on macOS vs Linux CI. Tag golden tests (
@Tags(['golden'])) and generate/update them on one OS consistently (match CI's). - Never
--update-goldensto make a red test green without looking at the diff first — that silently accepts a visual regression as the new baseline.
Common Mistakes
pumpWidgetfor logic that could be a plain unit test (slow, indirect).- Asserting widget-tree internals instead of visible behavior.
- No error/empty-state test.
- Golden files regenerated blindly, hiding a visual regression.
- A layout test that only runs at the default device size and text scale 1.0.
Red Flags
- The test passes before the production code exists (tests a fake).
- Every test boots the full app.
- Only the happy path is covered.
- No test exercises text scale 2.0 on a screen that changed layout.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns