What are golden tests in Flutter?
Short Answer
Golden tests render a widget and compare a screenshot of it pixel-for-pixel against a previously-approved reference image ('golden file'), catching unintended visual regressions that logic-based widget tests can't detect.
A normal widget test checks things like 'does this text exist' — it says nothing about whether the widget actually looks right. matchesGoldenFile() in a widget test renders the widget, captures it as an image, and compares it byte-for-byte against a stored PNG. The first run generates the golden file (via flutter test --update-goldens); subsequent runs fail if rendering has changed, requiring a human to review whether the change was intentional or a real regression.
Golden tests are sensitive to font rendering and platform differences, so teams typically run them in CI on a consistent environment to avoid false failures.
Code Example
testWidgets('button matches golden', (tester) async {
await tester.pumpWidget(const MaterialApp(home: MyButton()));
await expectLater(
find.byType(MyButton),
matchesGoldenFile('goldens/my_button.png'),
);
});Common Mistakes
- ×Running golden tests locally on a different OS/font setup than CI, causing constant false failures from anti-aliasing differences.
- ×Blindly re-generating goldens without reviewing the visual diff first — this can silently accept a real regression.