LocalFileComparator class Null safety
The default GoldenFileComparator implementation for flutter test
.
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. This comparator loads golden files from the local file system, treating the golden key as a relative path from the test file's directory.
This comparator performs a pixel-for-pixel comparison of the decoded PNGs, returning true only if there's an exact match. In cases where the captured test image does not match the golden file, this comparator will provide output to illustrate the difference, described in further detail below.
When using flutter test --update-goldens
, LocalFileComparator
updates the golden files on disk to match the rendering.
Local Output from Golden File Testing
The LocalFileComparator will output test feedback when a golden file test
fails. This output takes the form of differential images contained within a
failures
directory that will be generated in the same location specified
by the golden key. The differential images include the master and test
images that were compared, as well as an isolated diff of detected pixels,
and a masked diff that overlays these detected pixels over the master image.
The following images are examples of a test failure output:
File Name | Image Output |
---|---|
testName_masterImage.png | |
testName_testImage.png | |
testName_isolatedDiff.png | |
testName_maskedDiff.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:
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:
Future<void> testExecutable(FutureOr<void> Function() testMain) async {
setUpAll(() async {
final fontLoader = FontLoader('SomeFont')..addFont(someFont);
await fontLoader.load();
});
await testMain();
});
See also:
- GoldenFileComparator, the abstract class that LocalFileComparator implements.
- matchesGoldenFile, the function from flutter_test that invokes the comparator.
- Inheritance
-
- Object
- GoldenFileComparator
- LocalFileComparator
- Mixed in types
Constructors
- LocalFileComparator(Uri testFile, {Style? pathStyle})
-
Creates a new LocalFileComparator for the specified
testFile
.
Properties
Methods
-
compare(
Uint8List imageBytes, Uri golden) → Future< bool> -
Compares the pixels of decoded png
imageBytes
against the golden file identified bygolden
.override -
generateFailureOutput(
ComparisonResult result, Uri golden, Uri basedir, {String key = ''}) → Future< String> -
Writes out diffs from the ComparisonResult of a golden file test.
inherited
-
getFailureFile(
String failure, Uri golden, Uri basedir) → File -
Returns the appropriate file for a given diff from a ComparisonResult.
inherited
-
getGoldenBytes(
Uri golden) → Future< List< int> > -
Returns the bytes of the given
golden
file.protected">@protected -
getTestUri(
Uri key, int? version) → Uri -
Returns a new golden file Uri to incorporate any
version
number with thekey
.inherited -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a non-existent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
-
update(
Uri golden, Uint8List imageBytes) → Future< void> -
Updates the golden file identified by
golden
withimageBytes
.override
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited