matchesGoldenFile function

AsyncMatcher matchesGoldenFile (dynamic key, { 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'),
);

See also:

Implementation

AsyncMatcher matchesGoldenFile(dynamic 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}');
}