From e383db70877e2e15aa86cd3eb3b3d77d470de537 Mon Sep 17 00:00:00 2001
From: Alejandro Santiago <dev@alestiago.com>
Date: Wed, 3 Jul 2024 18:03:08 +0100
Subject: [PATCH] Add example of goldenFileComparator usage in widget tests
 (#150422)

As from #76337, precisely https://github.com/flutter/flutter/issues/76337#issuecomment-795486138 and https://github.com/flutter/flutter/issues/76337#issuecomment-2172941109. There is missing documentation with an example on how the [`goldenFileComparator`](https://api.flutter.dev/flutter/flutter_test/goldenFileComparator.html) can be used.

This change updates the documentation by providing an additional code snippet to the example that was already stated by the documentation.

Follows the effort made by #76337 and https://github.com/flutter/flutter/pull/150343.
---
 packages/flutter_test/lib/src/goldens.dart | 63 +++++++++++++++++++++-
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/packages/flutter_test/lib/src/goldens.dart b/packages/flutter_test/lib/src/goldens.dart
index d9ec373688..0ad3c69196 100644
--- a/packages/flutter_test/lib/src/goldens.dart
+++ b/packages/flutter_test/lib/src/goldens.dart
@@ -128,8 +128,67 @@ abstract class GoldenFileComparator {
 ///
 /// 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.
+/// configuration).
+///
+/// {@tool snippet}
+/// For example, some projects may wish to install a comparator with tolerance
+/// levels for allowable differences:
+///
+/// ```dart
+/// 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);
+///   }
+/// }
+/// ```
+/// {@end-tool}
 ///
 /// See also:
 ///