Sitemap
Open in app

Sign in

Medium Logo
Write
Search

Sign in

Flutter Golden Tests: Visual Regression Testing for UI

7 min read1 day ago

--

A Flutter application can pass all its unit tests and widget tests while still having visual problems.

For example:

  • A button becomes wider after a UI change.
  • A font size changes unexpectedly.
  • A card’s padding gets modified.
  • A theme update breaks dark mode.
  • An icon is misaligned.
  • A responsive layout overflows.
  • A previously correct screen looks different after a package update.

Functional tests may not catch these issues because they usually verify behavior rather than exact visual output.

This is where Golden Testing becomes useful.

Golden tests allow Flutter developers to capture a reference image of a widget and compare future renders against it.

In this article, we’ll explore Flutter Golden Tests, how to create them, manage reference images, handle responsive layouts, and integrate visual regression testing into CI/CD.

1. What Is Golden Testing?

Golden testing is a form of visual regression testing.

It captures a widget or screen as an image and compares that image against a previously approved reference image, commonly called a golden file.

For example:

First approved UI
       ↓
Capture reference image
       ↓
Golden file saved
       ↓
UI changes in future
       ↓
Capture new image
       ↓
Compare both images
       ↓
Pass or fail

If the rendered image differs beyond the configured comparison rules, the test fails.

This helps identify unexpected visual changes.

2. Golden Tests vs Widget Tests

Both are useful, but they have different purposes.

Press enter or click to view image in full size

For example, a widget test can verify that a button exists.

A golden test can verify that the button’s size, color, typography, and position match the approved design.

You should use both.

3. Flutter’s Golden Testing Support

Flutter provides built-in golden testing support through the widget testing framework.

The commonly used API is:

matchesGoldenFile()

You don’t necessarily need a third-party package to get started.

For example:

testWidgets('matches product card golden', (tester) async {
  await tester.pumpWidget(
    const MaterialApp(
      home: Scaffold(
        body: ProductCard(),
      ),
    ),
  );
  await expectLater(
    find.byType(ProductCard),
    matchesGoldenFile('goldens/product_card.png'),
  );
});

The test renders the widget and compares it with the reference image.

4. Create Your First Golden Test

Suppose you have a simple product card.

class ProductCard extends StatelessWidget {
  const ProductCard({super.key});

@override
  Widget build(BuildContext context) {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text(
              'Laptop',
              style: TextStyle(
                fontSize: 20,
                fontWeight: FontWeight.bold,
              ),
            ),
            const SizedBox(height: 8),
            const Text('₹75,000'),
            const SizedBox(height: 12),
            FilledButton(
              onPressed: () {},
              child: const Text('View Details'),
            ),
          ],
        ),
      ),
    );
  }
}

Create a test:

testWidgets('product card matches golden', (tester) async {
  await tester.pumpWidget(
    const MaterialApp(
      home: Scaffold(
        body: Center(
          child: ProductCard(),
        ),
      ),
    ),
  );

await expectLater(
    find.byType(ProductCard),
    matchesGoldenFile('goldens/product_card.png'),
  );
});

The first time you create the golden, you need to generate the reference image.

5. Generate Golden Files

Flutter supports updating golden files through the --update-goldens flag.

Run:

flutter test --update-goldens

Or target a specific test:

flutter test test/product_card_test.dart --update-goldens

The test runner generates the reference image at the path specified in matchesGoldenFile().

For example:

test/
├── features/
│   └── products/
│       ├── product_card.dart
│       └── product_card_test.dart
└── goldens/
    └── product_card.png

The golden image should be reviewed before committing it.

Never automatically accept every changed golden image without reviewing the visual differences.

6. How Golden Comparison Works

Conceptually, the test compares:

Reference Image
       +
Newly Rendered Image
       ↓
Pixel Comparison
       ↓
Difference Calculation
       ↓
Pass / Fail

A difference can occur because of:

  • Layout changes
  • Color changes
  • Font changes
  • Icon changes
  • Image changes
  • Rendering differences

Flutter’s standard golden matcher uses image comparison behavior provided by its test infrastructure.

For more advanced comparisons, you may use a dedicated visual-testing package or service.

7. Control the Test Environment

Golden tests are sensitive to rendering conditions.

The same widget may render differently because of:

  • Screen dimensions
  • Device pixel ratio
  • Font availability
  • Theme
  • Text scaling
  • Platform rendering
  • Flutter version
  • Operating system differences

For reliable results, control these conditions.

Example:

testWidgets('renders product card consistently', (tester) async {
  tester.view.physicalSize = const Size(400, 800);
  tester.view.devicePixelRatio = 1;

  addTearDown(tester.view.resetPhysicalSize);
  addTearDown(tester.view.resetDevicePixelRatio);
  await tester.pumpWidget(
    const MaterialApp(
      home: Scaffold(
        body: ProductCard(),
      ),
    ),
  );
  await expectLater(
    find.byType(ProductCard),
    matchesGoldenFile('goldens/product_card.png'),
  );
});

Keep the rendering environment consistent between golden generation and CI execution.

8. Test Different Themes

Modern Flutter applications commonly support light and dark themes.

A widget may look correct in light mode but fail visually in dark mode.

Create separate golden tests.

testWidgets('product card light theme', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      theme: ThemeData.light(),
      home: const Scaffold(
        body: ProductCard(),
      ),
    ),
  );

  await expectLater(
    find.byType(ProductCard),
    matchesGoldenFile('goldens/product_card_light.png'),
  );
});

And:

testWidgets('product card dark theme', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      theme: ThemeData.dark(),
      home: const Scaffold(
        body: ProductCard(),
      ),
    ),
  );

  await expectLater(
    find.byType(ProductCard),
    matchesGoldenFile('goldens/product_card_dark.png'),
  );
});

If your application uses a custom theme system, use the actual application themes rather than generic defaults.

9. Test Responsive Layouts

Responsive design is another excellent use case for golden tests.

For example:

Mobile
Tablet
Desktop

You can capture separate reference images for each screen size.

Example:

testWidgets('product page mobile layout', (tester) async {
  tester.view.physicalSize = const Size(390, 844);
  tester.view.devicePixelRatio = 1;

  addTearDown(tester.view.resetPhysicalSize);
  addTearDown(tester.view.resetDevicePixelRatio);
  await tester.pumpWidget(
    const MaterialApp(
      home: ProductPage(),
    ),
  );
  await expectLater(
    find.byType(ProductPage),
    matchesGoldenFile('goldens/product_page_mobile.png'),
  );
});

Create similar tests for tablet and desktop dimensions.

Avoid generating hundreds of nearly identical golden files. Select representative sizes that exercise meaningful layout breakpoints.

10. Test Text Scaling and Accessibility

A layout that looks correct at the default text size may break when users increase system text scaling.

Test larger text configurations.

Get Nisarg Ratani’s stories in your inbox

Join Medium for free to get updates from this writer.

In modern Flutter, MediaQuery can be configured using TextScaler.

For example:

MediaQuery(
  data: const MediaQueryData(
    textScaler: TextScaler.linear(1.5),
  ),
  child: const ProductPage(),
)

Capture a golden image to check:

  • Text wrapping
  • Button height
  • Card expansion
  • Overflow
  • Alignment
  • Content clipping

Golden tests can help detect visual accessibility regressions, although they do not replace screen-reader testing.

11. Test Different Widget States

A screen may have multiple visual states.

For a product list:

Loading
Success
Empty
Error
Pagination loading

Each state can have its own golden image.

For example:

goldens/
├── product_loading.png
├── product_success.png
├── product_empty.png
└── product_error.png

This is especially valuable for complex screens with conditional layouts.

12. Golden Testing with Images and Custom Fonts

Images and fonts can introduce rendering differences.

For predictable results:

  • Bundle required fonts in the test environment.
  • Avoid relying on platform-specific system fonts.
  • Use deterministic test images.
  • Avoid live network images.
  • Wait until required assets are loaded.
  • Use the same Flutter environment for generation and comparison.

If a widget uses Image.network, replace the network dependency with a controlled test image or another deterministic image source.

Golden tests should not depend on whether an external image server is available.

13. Handle Animations

Animations can make golden tests unpredictable if captured at arbitrary times.

Instead of capturing a moving animation without control, set a deterministic animation state.

For example, advance time using:

await tester.pump(
  const Duration(milliseconds: 300),
);

You can capture:

  • Initial state
  • Mid-animation state
  • Final state

For most UI regression tests, the final stable state is the most valuable.

14. Organize Golden Files

Keep golden files organized by feature.

Example:

test/
├── features/
│   ├── auth/
│   │   ├── login_page_test.dart
│   │   └── goldens/
│   │       ├── login_light.png
│   │       └── login_dark.png
│   │
│   ├── products/
│   │   ├── product_page_test.dart
│   │   └── goldens/
│   │       ├── product_loading.png
│   │       └── product_success.png
│   │
│   └── dashboard/
│       ├── dashboard_test.dart
│       └── goldens/
│           └── dashboard.png

This makes reference images easier to locate and maintain.

15. Review Golden Differences

When a golden test fails, don’t immediately update the reference image.

First identify the cause.

Ask:

  • Was the design intentionally changed?
  • Did a package update affect rendering?
  • Did a font change?
  • Is the widget using different dimensions?
  • Did a theme value change?
  • Is the test environment inconsistent?

Review the expected and actual images.

Some test configurations also generate a difference image that highlights changed pixels.

Accept the new golden only after confirming that the visual change is expected.

16. Golden Testing Packages

Flutter’s built-in support is enough for many projects.

However, third-party tools can provide additional capabilities.

Examples include:

  • alchemist — a Flutter-focused golden-testing package.
  • golden_toolkit — utilities for organizing and testing golden scenarios.
  • Visual regression platforms — services that compare screenshots and provide review workflows.

Check package maintenance, Flutter compatibility, and current APIs before adopting a dependency.

Avoid adding multiple golden-testing frameworks unless they solve different problems.

17. Golden Tests in CI/CD

Golden tests are especially useful in pull requests.

A typical workflow:

Developer creates pull request
          ↓
Static analysis
          ↓
Unit tests
          ↓
Widget tests
          ↓
Golden tests
          ↓
Compare reference images
          ↓
Pass / Fail

If a golden changes unexpectedly, the CI pipeline should fail.

The developer can then review the difference and update the reference image if the UI change is intentional.

Keep the CI rendering environment consistent with the environment used to generate golden files.

18. Common Golden Testing Mistakes

Accepting every golden update

Review visual differences before updating reference images.

Testing too many screen sizes

Choose meaningful representative dimensions.

Using live network images

Use deterministic assets.

Ignoring font differences

Bundle and load fonts consistently.

Testing animations without controlling time

Use predictable animation states.

Generating goldens on different environments

Keep Flutter, operating system, and rendering configuration consistent.

Treating golden tests as functional tests

Golden tests verify appearance, not complete interaction behavior.

Recommended Golden Testing Strategy

For a typical Flutter application, start with:

Press enter or click to view image in full size

Prioritize reusable components and screens with high visual importance.

Production Checklist

GOLDEN SETUP
✓ Golden tests configured
✓ Reference images committed
✓ Deterministic rendering environment
✓ Fonts and assets controlled

COVERAGE
✓ Reusable components
✓ Important screens
✓ Loading and error states
✓ Light and dark themes
✓ Responsive layouts
✓ Large text scaling

RELIABILITY
✓ No live network images
✓ Animations controlled
✓ Consistent device dimensions
✓ Stable Flutter environment

REVIEW
✓ Actual image reviewed
✓ Difference image inspected
✓ Intentional changes approved
✓ Unexpected changes investigated

CI/CD
✓ Golden tests run automatically
✓ Visual failures block the pipeline
✓ Reference updates reviewed

Conclusion

Golden testing helps Flutter developers catch visual regressions before they reach users.

It is especially useful for applications with reusable design systems, multiple themes, responsive layouts, and frequently changing UI.

Start with important reusable widgets and critical screens.

Combine golden tests with widget and integration tests to verify both appearance and behavior.

Flutter Golden Test
Flutter Testing
Flutter Ui
Flutter
Mobile App Development

--

--

Nisarg Ratani
Nisarg Ratani

Written by Nisarg Ratani

26 followers
2 following

Flutter & Node.js developer with 6+ years of experience. Published few articles on Medium, sharing practical insights on Flutter, Dart, and Node.js.