Golden File Testing

The term golden file refers to a master image that is considered the true rendering of a given widget, state, application, or other visual representation you have chosen to capture.

Note

To learn more about Golden file testing refer to Testing Fundamentals video about Using Golden Files to Verify Pixel-Perfect Widgets or to the Flutter matchesGoldenFile documentation.

Tag golden tests

Golden tests should be tagged to make it easier to run them separately from other tests.

Good ✅

testWidgets(
  'render matches golden file',
  tags: TestTag.golden,
  (WidgetTester tester) async {
    await tester.pumpWidget(MyWidget());

    await expectLater(
      find.byType(MyWidget),
      matchesGoldenFile('my_widget.png'),
    );
  },
);

Bad ❗️

testWidgets('render matches golden file', (WidgetTester tester) async {
  await tester.pumpWidget(MyWidget());

  await expectLater(
    find.byType(MyWidget),
    matchesGoldenFile('my_widget.png'),
  );
});

Tip

You should avoid using magic strings to tag tests. Instead, use constants to tag tests. This helps to avoid typos and makes it easier to refactor.

Configure your golden test tag

To configure a golden test tag across multiple files (or an entire package), create a dart_test.yaml file and add the tag configuration:

tags:
  golden:
    description: "Tests that compare golden files."

Note

Learn more about all the dart_test.yaml configuration options in the Dart Test Configuration documentation.

You can then run the tests with the tag golden in isolation, or quickly update the golden files with the --update-goldens flag:

flutter test --tags golden # Run only golden tests
flutter test --tags golden --update-goldens # Update golden files