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.

key may be either a Uri or a String representation of a URI.

version is a number that can be used to differentiate historical golden files. This parameter is optional. Version numbers are used in golden file tests for package:flutter. You can learn more about these tests here (https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter).

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

Sample code

await expectLater(find.text('Save'), matchesGoldenFile('save.png'));
await expectLater(image, matchesGoldenFile('save.png'));
await expectLater(imageFuture, matchesGoldenFile('save.png'));

Golden image files can be created or updated by running flutter test --update-goldens on the test.

See also:

  • goldenFileComparator, which acts as the backend for this matcher.
  • matchesReferenceImage, which should be used instead if you want to verify that two different code paths create identical images.
  • flutter_test for a discussion of test configurations, whereby callers may swap out the backend for this matcher.

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}');
}