matchesGoldenFileWithPixelAllowance function

MatchesGoldenFile matchesGoldenFileWithPixelAllowance(Object key, int maxPixelMismatchCount, { int? version, })

A matcher that expects given content to match the golden file referenced by key, allowing up to maxPixelMismatchCount different pixels before considering the test to be a failure.

Typically, the key is expected to be a relative file path from the given test file, to the golden file, e.g., "goldens/my-golden-name.png".

This matcher can be used by calling it in expectLater(), e.g.,

await expectLater(
  find.byType(MaterialApp),
  matchesGoldenFileWithPixelAllowance("goldens/my-golden-name.png", 20),
);

Typically, Flutter's golden system describes mismatches in terms of percentages. But percentages are difficult to depend upon. Sometimes a relatively large percentage doesn't matter, and sometimes a tiny percentage is critical. When it comes to ignoring irrelevant mismatches, it's often more convenient to work in terms of pixels. This matcher lets developers specify a maximum pixel mismatch count, instead of relying on percentage differences across the entire golden image.

Implementation

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