AGENT SKILL

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 mocktail per 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.
  • pump vs pumpAndSettle: use pump for controlled frames, pumpAndSettle to 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-goldens to make a red test green without looking at the diff first — that silently accepts a visual regression as the new baseline.

Common Mistakes

  • pumpWidget for 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