From ee6a693cde504d9db335344b0920b8c9e6f92896 Mon Sep 17 00:00:00 2001 From: Alberto Date: Fri, 21 Jan 2022 00:25:20 +0100 Subject: [PATCH] chore(flutter_test): updated 'matchesGoldenFile' documentation (#96194) --- AUTHORS | 2 + .../flutter_test/lib/src/_goldens_io.dart | 2 + packages/flutter_test/lib/src/goldens.dart | 2 + packages/flutter_test/lib/src/matchers.dart | 58 ++++++++++++++++++- 4 files changed, 62 insertions(+), 2 deletions(-) diff --git a/AUTHORS b/AUTHORS index c6f1a901e8..d30ad288ab 100644 --- a/AUTHORS +++ b/AUTHORS @@ -89,3 +89,5 @@ Pradumna Saraf Kai Yu Denis Grafov TheOneWithTheBraid +Alberto Miola +Twin Sun, LLC diff --git a/packages/flutter_test/lib/src/_goldens_io.dart b/packages/flutter_test/lib/src/_goldens_io.dart index cf00bad736..bb01da9359 100644 --- a/packages/flutter_test/lib/src/_goldens_io.dart +++ b/packages/flutter_test/lib/src/_goldens_io.dart @@ -49,6 +49,8 @@ import 'test_async_utils.dart'; /// | testName_isolatedDiff.png | ![An isolated pixel difference.](https://flutter.github.io/assets-for-api-docs/assets/flutter-test/goldens/widget_isolatedDiff.png) | /// | testName_maskedDiff.png | ![A masked pixel difference](https://flutter.github.io/assets-for-api-docs/assets/flutter-test/goldens/widget_maskedDiff.png) | /// +/// {@macro flutter.flutter_test.matchesGoldenFile.custom_fonts} +/// /// See also: /// /// * [GoldenFileComparator], the abstract class that [LocalFileComparator] diff --git a/packages/flutter_test/lib/src/goldens.dart b/packages/flutter_test/lib/src/goldens.dart index 3ca05fa364..fb3d54d8db 100644 --- a/packages/flutter_test/lib/src/goldens.dart +++ b/packages/flutter_test/lib/src/goldens.dart @@ -41,6 +41,8 @@ import '_goldens_io.dart' if (dart.library.html) '_goldens_web.dart' as goldens; /// | Difference | ![The pixel difference](https://flutter.github.io/assets-for-api-docs/assets/flutter-test/goldens/widget_isolatedDiff.png) | /// | Test image after modification | ![Test image](https://flutter.github.io/assets-for-api-docs/assets/flutter-test/goldens/widget_testImage.png) | /// +/// {@macro flutter.flutter_test.matchesGoldenFile.custom_fonts} +/// /// See also: /// /// * [LocalFileComparator] for the default [GoldenFileComparator] diff --git a/packages/flutter_test/lib/src/matchers.dart b/packages/flutter_test/lib/src/matchers.dart index edd4ca8a18..a5386c5d11 100644 --- a/packages/flutter_test/lib/src/matchers.dart +++ b/packages/flutter_test/lib/src/matchers.dart @@ -354,6 +354,61 @@ Matcher coversSameAreaAs(Path expectedPath, { required Rect areaToCompare, int s /// ``` /// {@end-tool} /// +/// {@template flutter.flutter_test.matchesGoldenFile.custom_fonts} +/// ## 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: +/// +/// {@tool snippet} +/// How to load a custom font for golden images. +/// ```dart +/// 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'), +/// ); +/// }); +/// ``` +/// {@end-tool} +/// +/// 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: +/// +/// {@tool snippet} +/// Loading a custom font from the flutter_test_config.dart file. +/// ```dart +/// Future testExecutable(FutureOr Function() testMain) async { +/// setUpAll(() async { +/// final fontLoader = FontLoader('SomeFont')..addFont(someFont); +/// await fontLoader.load(); +/// }); +/// +/// await testMain(); +/// }); +/// ``` +/// {@end-tool} +/// {@endtemplate} +/// /// See also: /// /// * [GoldenFileComparator], which acts as the backend for this matcher. @@ -363,8 +418,7 @@ Matcher coversSameAreaAs(Path expectedPath, { required Rect areaToCompare, int s /// 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. -AsyncMatcher -matchesGoldenFile(Object key, {int? version}) { +AsyncMatcher matchesGoldenFile(Object key, {int? version}) { if (key is Uri) { return MatchesGoldenFile(key, version); } else if (key is String) {