goldenFileComparator top-level property

GoldenFileComparator goldenFileComparator
getter/setter pair

Compares pixels against those of a golden image file.

This comparator is used as the backend for matchesGoldenFile.

When using flutter test, a comparator implemented by LocalFileComparator is used if no other comparator is specified. It treats the golden key as a relative path from the test file's directory. It will then load the golden file's bytes from disk and perform a pixel-for-pixel comparison of the decoded PNGs, returning true only if there's an exact match.

When using flutter test --update-goldens, the LocalFileComparator updates the files on disk to match the rendering.

When using flutter run, the default comparator (TrivialComparator) is used. It prints a message to the console but otherwise does nothing. This allows tests to be developed visually on a real device.

Callers may choose to override the default comparator by setting this to a custom comparator during test set-up (or using directory-level test configuration).

For example, some projects may wish to install a comparator with tolerance levels for allowable differences:
link 
void main() {
  testWidgets('matches golden file with a 0.01 tolerance', (WidgetTester tester) async {
    final GoldenFileComparator previousGoldenFileComparator = goldenFileComparator;
    goldenFileComparator = _TolerantGoldenFileComparator(
      Uri.parse('test/my_widget_test.dart'),
      precisionTolerance: 0.01,
    );
    addTearDown(() => goldenFileComparator = previousGoldenFileComparator);

    await tester.pumpWidget(const ColoredBox(color: Color(0xff00ff00)));

    await expectLater(
      find.byType(ColoredBox),
      matchesGoldenFile('my_golden.png'),
    );
  });
}

class _TolerantGoldenFileComparator extends LocalFileComparator {
  _TolerantGoldenFileComparator(
    super.testFile, {
    required double precisionTolerance,
  })  : assert(
        0 <= precisionTolerance && precisionTolerance <= 1,
        'precisionTolerance must be between 0 and 1',
        ),
        _precisionTolerance = precisionTolerance;

  /// How much the golden image can differ from the test image.
  ///
  /// It is expected to be between 0 and 1. Where 0 is no difference (the same image)
  /// and 1 is the maximum difference (completely different images).
  final double _precisionTolerance;

  @override
  Future<bool> compare(Uint8List imageBytes, Uri golden) async {
    final ComparisonResult result = await GoldenFileComparator.compareLists(
      imageBytes,
      await getGoldenBytes(golden),
    );

    final bool passed = result.passed || result.diffPercent <= _precisionTolerance;
    if (passed) {
      result.dispose();
      return true;
    }

    final String error = await generateFailureOutput(result, golden, basedir);
    result.dispose();
    throw FlutterError(error);
  }
}

See also:

  • flutter_test for more information about how to configure tests at the directory-level.

Implementation

GoldenFileComparator goldenFileComparator = const TrivialComparator._();