GoldenFileComparator class abstract
Compares image pixels against a golden image file.
Instances of this comparator will be used as the backend for matchesGoldenFile.
Instances of this comparator will be invoked by the test framework in the TestWidgetsFlutterBinding.runAsync zone and are thus not subject to the fake async constraints that are normally imposed on widget tests (i.e. the need or the ability to call WidgetTester.pump to advance the microtask queue).
What is 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.
By keeping a master reference of visual aspects of your application, you can prevent unintended changes as you develop by testing against them.
Here, a minor code change has altered the appearance of a widget. A golden file test has compared the image generated at the time of the test to the golden master file that was generated earlier. The test has identified the change, preventing unintended modifications.
Sample | Image |
---|---|
Golden Master Image | ![]() |
Difference | ![]() |
Test image after modification | ![]() |
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', (WidgetTester tester) async {
// Assuming the 'Roboto.ttf' file is declared in the pubspec.yaml file
final Future<ByteData> font = rootBundle.load('path/to/font-file/Roboto.ttf');
final FontLoader fontLoader = FontLoader('Roboto')..addFont(font);
await fontLoader.load();
await tester.pumpWidget(const MyWidget());
await expectLater(
find.byType(MyWidget),
matchesGoldenFile('myWidget.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 = FontLoader('SomeFont')..addFont(someFont);
await fontLoader.load();
});
await testMain();
}
See also:
- LocalFileComparator for the default GoldenFileComparator
implementation for
flutter test
. - matchesGoldenFile, the function from flutter_test that invokes the comparator.
- Implementers
Constructors
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
compare(
Uint8List imageBytes, Uri golden) → Future< bool> -
Compares the pixels of decoded png
imageBytes
against the golden file identified bygolden
. -
getTestUri(
Uri key, int? version) → Uri -
Returns a new golden file Uri to incorporate any
version
number with thekey
. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent 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
.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Methods
-
compareLists(
List< int> test, List<int> master) → Future<ComparisonResult> -
Returns a ComparisonResult to describe the pixel differential of the
test
andmaster
image bytes provided.