Golden tests for UI in Flutter

Introduction

Golden tests help you check if your app's screen looks right. They compare your UI to a saved picture to catch mistakes early.

When you want to make sure a button or screen looks the same after changes.

When you add new UI features and want to avoid breaking old designs.

When you fix bugs and want to confirm the UI stays correct.

When you want to test different screen sizes or themes visually.

When you want to automate UI checks in your app development.

Syntax

Flutter

testWidgets('description', (WidgetTester tester) async {
  await tester.pumpWidget(MyWidget());
  await expectLater(
    find.byType(MyWidget),
    matchesGoldenFile('goldens/my_widget.png'),
  );
});

testWidgets runs a UI test.

matchesGoldenFile compares the widget to a saved image file.

Examples

This test checks if the button looks like the saved image.

Flutter

testWidgets('Button looks correct', (tester) async {
  await tester.pumpWidget(MaterialApp(home: ElevatedButton(onPressed: () {}, child: Text('Tap'))));
  await expectLater(find.byType(ElevatedButton), matchesGoldenFile('goldens/button.png'));
});

This test compares the whole screen widget to the golden file.

Flutter

testWidgets('Screen matches golden', (tester) async {
  await tester.pumpWidget(MyScreen());
  await expectLater(find.byType(MyScreen), matchesGoldenFile('goldens/screen.png'));
});

Sample App

This test shows a simple text widget and compares it to a saved golden image named 'text_widget.png'.

Flutter

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('Simple Text widget golden test', (WidgetTester tester) async {
    await tester.pumpWidget(const MaterialApp(
      home: Scaffold(
        body: Center(
          child: Text('Hello Golden Test'),
        ),
      ),
    ));

    await expectLater(
      find.byType(Text),
      matchesGoldenFile('goldens/text_widget.png'),
    );
  });
}

Important Notes

Golden files are images saved in your project to compare UI snapshots.

Run tests with flutter test and update golden files with flutter test --update-goldens if UI changes are intentional.

Keep golden files in a dedicated folder like goldens/ for organization.

Summary

Golden tests compare your UI to saved images to catch visual bugs.

They are useful for checking buttons, screens, and themes.

Use matchesGoldenFile inside testWidgets to write golden tests.

Practice

1. What is the main purpose of a golden test in Flutter UI testing?

easy

A. To compare the current UI rendering with a saved image to detect visual changes

B. To test the performance speed of UI animations

C. To check if the UI code compiles without errors

D. To verify the network requests made by the UI

Solution

1. Step 1: Understand the purpose of golden tests

   Golden tests compare the UI's current look to a saved image to find visual differences.

2. Step 2: Eliminate unrelated options

   Performance, compilation, and network checks are not the focus of golden tests.

3. Final Answer:

   To compare the current UI rendering with a saved image to detect visual changes -> Option A

4. Quick Check:

   Golden test purpose = Visual comparison [OK]

Hint: Golden tests check UI images, not code or speed [OK]

Common Mistakes:

• Confusing golden tests with performance tests
• Thinking golden tests check code syntax
• Assuming golden tests verify network calls

2. Which Flutter test function is used to compare a widget's UI to a golden file?

easy

A. runApp(widget).toMatchGolden('golden.png')

B. expect(widget, equals('golden.png'))

C. testWidgets('golden test', () => expect(widget, isTrue))

D. expectLater(widget, matchesGoldenFile('golden.png'))

Solution

1. Step 1: Identify the correct golden test syntax

   The function expectLater with matchesGoldenFile is the standard way to compare UI to a golden image.

2. Step 2: Check other options for correctness

   Options B, C, and D use incorrect or non-existent syntax for golden tests.

3. Final Answer:

   expectLater(widget, matchesGoldenFile('golden.png')) -> Option D

4. Quick Check:

   Golden test syntax = expectLater + matchesGoldenFile [OK]

Hint: Use expectLater with matchesGoldenFile for golden tests [OK]

Common Mistakes:

• Using expect instead of expectLater
• Missing matchesGoldenFile matcher
• Trying to call golden test on runApp directly

3. Given this Flutter golden test snippet:

testWidgets('Button golden test', (tester) async {
  await tester.pumpWidget(MyButton());
  await expectLater(find.byType(MyButton), matchesGoldenFile('button.png'));
});

What will happen if the current button UI differs visually from 'button.png'?

medium

A. The test will throw a syntax error

B. The test will fail indicating a visual mismatch

C. The test will pass regardless of UI differences

D. The test will skip without running

Solution

1. Step 1: Understand golden test behavior on mismatch

   If the rendered UI does not match the saved golden image, the test fails to alert visual changes.

2. Step 2: Verify other options

   Passing despite differences, syntax errors, or skipping are not expected behaviors here.

3. Final Answer:

   The test will fail indicating a visual mismatch -> Option B

4. Quick Check:

   Golden test mismatch = test failure [OK]

Hint: Golden test fails if UI differs from saved image [OK]

Common Mistakes:

• Expecting test to pass despite UI changes
• Confusing runtime errors with test failures
• Thinking golden tests skip on mismatch

4. Identify the error in this golden test code snippet:

testWidgets('Screen golden test', (tester) async {
  await tester.pumpWidget(MyScreen());
  expect(find.byType(MyScreen), matchesGoldenFile('screen.png'));
});

medium

A. Using expect instead of expectLater for matchesGoldenFile

B. Missing await before tester.pumpWidget

C. Incorrect widget type passed to find.byType

D. Golden file name should be a full path

Solution

1. Step 1: Check the matcher usage

   Golden tests require expectLater with matchesGoldenFile to work asynchronously.

2. Step 2: Validate other parts

   Await is correctly used with pumpWidget, widget type is correct, and relative file names are allowed.

3. Final Answer:

   Using expect instead of expectLater for matchesGoldenFile -> Option A

4. Quick Check:

   Golden test needs expectLater, not expect [OK]

Hint: Use expectLater, not expect, with matchesGoldenFile [OK]

Common Mistakes:

• Using expect instead of expectLater
• Forgetting async/await on pumpWidget
• Assuming golden file needs full absolute path

5. You want to write a golden test for a button that changes color based on theme. Which approach ensures your golden test covers both light and dark themes correctly?

hard

A. Skip golden tests for theme changes and rely on manual testing

B. Write one golden test with default theme only, assuming dark theme looks similar

C. Write separate golden tests pumping the button with light and dark theme widgets and compare to separate golden files

D. Use a single golden file and toggle theme at runtime without repumping widget

Solution

1. Step 1: Understand theme impact on UI

   Light and dark themes can change colors significantly, so testing both separately is needed.

2. Step 2: Evaluate testing approaches

   Separate tests with repumping widgets under each theme and comparing to distinct golden files ensures accurate visual checks.

3. Final Answer:

   Write separate golden tests pumping the button with light and dark theme widgets and compare to separate golden files -> Option C

4. Quick Check:

   Test each theme separately with distinct golden files [OK]

Hint: Test light and dark themes separately with different golden files [OK]

Common Mistakes:

• Assuming one golden file covers all themes
• Not repumping widget after theme change
• Skipping golden tests for theme variations