matchesGoldenFile function Null safety

AsyncMatcher matchesGoldenFile(
  1. Object key,
  2. {int? version}
)

Asserts that a Finder, Future<ui.Image>, or ui.Image matches the golden image file identified by key, with an optional version number.

For the case of a Finder, the Finder must match exactly one widget and the rendered image of the first RepaintBoundary ancestor of the widget is treated as the image for the widget. As such, you may choose to wrap a test widget in a RepaintBoundary to specify a particular focus for the test.

The key may be either a Uri or a String representation of a URL.

The version is a number that can be used to differentiate historical golden files. This parameter is optional.

This is an asynchronous matcher, meaning that callers should use expectLater when using this matcher and await the future returned by expectLater.

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.

The master golden image files that are tested against can be created or updated by running flutter test --update-goldens on the test.

link
Sample invocations of matchesGoldenFile. 
await expectLater(
  find.text('Save'),
  matchesGoldenFile('save.png'),
);

await expectLater(
  image,
  matchesGoldenFile('save.png'),
);

await expectLater(
  imageFuture,
  matchesGoldenFile(
    'save.png',
    version: 2,
  ),
);

await expectLater(
  find.byType(MyWidget),
  matchesGoldenFile('goldens/myWidget.png'),
);

Including Fonts

Custom fonts may render differently across different platforms, or between different versions of Flutter. For example, a golden file generated on Windows with fonts will likely differ from the one produced by another operating system. Even on the same platform, if the generated golden is tested with a different Flutter version, the test may fail and require an updated image.

By default, the Flutter framework uses a font called 'Ahem' which shows squares instead of characters, however, it is possible to render images using custom fonts. For example, this is how to load the 'Roboto' font for a golden test:

link
How to load a custom font for golden images. 
testWidgets('Creating a golden image with a custom font', (tester) async {
  // Assuming the 'Roboto.ttf' file is declared in the pubspec.yaml file
  final font = rootBundle.load('path/to/font-file/Roboto.ttf');

  final fontLoader = FontLoader('Roboto')..addFont(font);
  await fontLoader.load();

  await tester.pumpWidget(const SomeWidget());

  await expectLater(
    find.byType(SomeWidget),
    matchesGoldenFile('someWidget.png'),
  );
});

The example above loads the desired font only for that specific test. To load a font for all golden file tests, the FontLoader.load() call could be moved in the flutter_test_config.dart. In this way, the font will always be loaded before a test:

link
Loading a custom font from the flutter_test_config.dart file. 
Future<void> testExecutable(FutureOr<void> Function() testMain) async {
  setUpAll(() async {
    final fontLoader = FontLoader('SomeFont')..addFont(someFont);
    await fontLoader.load();
  });

  await testMain();
});

See also:

Implementation

AsyncMatcher matchesGoldenFile(Object key, {int? version}) {
  if (key is Uri) {
    return MatchesGoldenFile(key, version);
  } else if (key is String) {
    return MatchesGoldenFile.forStringPath(key, version);
  }
  throw ArgumentError('Unexpected type for golden file: ${key.runtimeType}');
}