diff --git a/packages/flutter_test/lib/src/goldens.dart b/packages/flutter_test/lib/src/goldens.dart index 86e7820dcd2..39a666b2dee 100644 --- a/packages/flutter_test/lib/src/goldens.dart +++ b/packages/flutter_test/lib/src/goldens.dart @@ -23,6 +23,33 @@ import 'package:test_api/test_api.dart' as test_package show TestFailure; /// 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 | ![A golden master image](https://flutter.github.io/assets-for-api-docs/assets/flutter-test/goldens/widget_masterImage.png) | +/// | 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) | +/// +/// See also: +/// +/// * [LocalFileComparator] for the default [GoldenFileComparator] +/// implementation for `flutter test`. +/// * [matchesGoldenFile], the function from [flutter_test] that invokes the +/// comparator. abstract class GoldenFileComparator { /// Compares the pixels of decoded png [imageBytes] against the golden file /// identified by [golden]. @@ -258,14 +285,44 @@ class TrivialComparator implements GoldenFileComparator { /// The default [GoldenFileComparator] implementation for `flutter test`. /// -/// This comparator loads golden files from the local file system, treating the -/// golden key as a relative path from the test file's directory. +/// 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. +/// 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 files on disk to match the rendering. +/// 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 | ![A golden master image](https://flutter.github.io/assets-for-api-docs/assets/flutter-test/goldens/widget_masterImage.png) | +/// | testName_testImage.png | ![Test image](https://flutter.github.io/assets-for-api-docs/assets/flutter-test/goldens/widget_testImage.png) | +/// | 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) | +/// +/// See also: +/// +/// * [GoldenFileComparator], the abstract class that [LocalFileComparator] +/// implements. +/// * [matchesGoldenFile], the function from [flutter_test] that invokes the +/// comparator. class LocalFileComparator extends GoldenFileComparator { /// Creates a new [LocalFileComparator] for the specified [testFile]. /// diff --git a/packages/flutter_test/lib/src/matchers.dart b/packages/flutter_test/lib/src/matchers.dart index 16d147c59a2..9f33295997c 100644 --- a/packages/flutter_test/lib/src/matchers.dart +++ b/packages/flutter_test/lib/src/matchers.dart @@ -297,33 +297,60 @@ Matcher coversSameAreaAs(Path expectedPath, { @required Rect areaToCompare, int /// /// For the case of a [Finder], the [Finder] must match exactly one widget and /// the rendered image of the first [RepaintBoundary] ancestor of the widget is -/// treated as the image for the widget. +/// treated as the image for the widget. As such, you may choose to wrap a test +/// widget in a [RepaintBoundary] to specify a particular focus for the test. /// -/// [key] may be either a [Uri] or a [String] representation of a URI. +/// The [key] may be either a [Uri] or a [String] representation of a URI. /// -/// [version] is a number that can be used to differentiate historical golden -/// files. This parameter is optional. Version numbers are used in golden file -/// tests for package:flutter. You can learn more about these tests [here] -/// (https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter). +/// The [version] is a number that can be used to differentiate historical +/// golden files. This parameter is optional. Version numbers are used in golden +/// file tests for package:flutter. You can learn more about these tests +/// [here](https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter). /// /// This is an asynchronous matcher, meaning that callers should use /// [expectLater] when using this matcher and await the future returned by /// [expectLater]. /// -/// ## Sample code +/// ## 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. +/// +/// The master golden image files that are tested against can be created or +/// updated by running `flutter test --update-goldens` on the test. +/// +/// {@tool sample} +/// Sample invocations of [matchesGoldenFile]. /// /// ```dart -/// await expectLater(find.text('Save'), matchesGoldenFile('save.png')); -/// await expectLater(image, matchesGoldenFile('save.png')); -/// await expectLater(imageFuture, matchesGoldenFile('save.png')); -/// ``` +/// await expectLater( +/// find.text('Save'), +/// matchesGoldenFile('save.png'), +/// ); /// -/// Golden image files can be created or updated by running `flutter test -/// --update-goldens` on the test. +/// await expectLater( +/// image, +/// matchesGoldenFile('save.png'), +/// ); +/// +/// await expectLater( +/// imageFuture, +/// matchesGoldenFile('save.png'), +/// ); +/// +/// await expectLater( +/// find.byType(MyWidget), +/// matchesGoldenFile('goldens/myWidget.png'), +/// ); +/// ``` +/// {@end-tool} /// /// See also: /// -/// * [goldenFileComparator], which acts as the backend for this matcher. +/// * [GoldenFileComparator], which acts as the backend for this matcher. +/// * [LocalFileComparator], which is the default [GoldenFileComparator] +/// implementation for `flutter test`. /// * [matchesReferenceImage], which should be used instead if you want to /// verify that two different code paths create identical images. /// * [flutter_test] for a discussion of test configurations, whereby callers