Unverified Commit c8af729d authored by Kate Lovett's avatar Kate Lovett Committed by GitHub

Golden Doc Updates (#39082)

parent 0ed3242a
...@@ -23,6 +23,33 @@ import 'package:test_api/test_api.dart' as test_package show TestFailure; ...@@ -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 /// 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 /// need or the ability to call [WidgetTester.pump] to advance the microtask
/// queue). /// 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 { abstract class GoldenFileComparator {
/// Compares the pixels of decoded png [imageBytes] against the golden file /// Compares the pixels of decoded png [imageBytes] against the golden file
/// identified by [golden]. /// identified by [golden].
...@@ -258,14 +285,44 @@ class TrivialComparator implements GoldenFileComparator { ...@@ -258,14 +285,44 @@ class TrivialComparator implements GoldenFileComparator {
/// The default [GoldenFileComparator] implementation for `flutter test`. /// The default [GoldenFileComparator] implementation for `flutter test`.
/// ///
/// This comparator loads golden files from the local file system, treating the /// The term __golden file__ refers to a master image that is considered the true
/// golden key as a relative path from the test file's directory. /// 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, /// 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] /// 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 { class LocalFileComparator extends GoldenFileComparator {
/// Creates a new [LocalFileComparator] for the specified [testFile]. /// Creates a new [LocalFileComparator] for the specified [testFile].
/// ///
......
...@@ -297,33 +297,60 @@ Matcher coversSameAreaAs(Path expectedPath, { @required Rect areaToCompare, int ...@@ -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 /// 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 /// 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 /// The [version] is a number that can be used to differentiate historical
/// files. This parameter is optional. Version numbers are used in golden file /// golden files. This parameter is optional. Version numbers are used in golden
/// tests for package:flutter. You can learn more about these tests [here] /// file tests for package:flutter. You can learn more about these tests
/// (https://github.com/flutter/flutter/wiki/Writing-a-golden-file-test-for-package:flutter). /// [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 /// This is an asynchronous matcher, meaning that callers should use
/// [expectLater] when using this matcher and await the future returned by /// [expectLater] when using this matcher and await the future returned by
/// [expectLater]. /// [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 /// ```dart
/// await expectLater(find.text('Save'), matchesGoldenFile('save.png')); /// await expectLater(
/// await expectLater(image, matchesGoldenFile('save.png')); /// find.text('Save'),
/// await expectLater(imageFuture, matchesGoldenFile('save.png')); /// matchesGoldenFile('save.png'),
/// );
///
/// await expectLater(
/// image,
/// matchesGoldenFile('save.png'),
/// );
///
/// await expectLater(
/// imageFuture,
/// matchesGoldenFile('save.png'),
/// );
///
/// await expectLater(
/// find.byType(MyWidget),
/// matchesGoldenFile('goldens/myWidget.png'),
/// );
/// ``` /// ```
/// /// {@end-tool}
/// Golden image files can be created or updated by running `flutter test
/// --update-goldens` on the test.
/// ///
/// See also: /// 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 /// * [matchesReferenceImage], which should be used instead if you want to
/// verify that two different code paths create identical images. /// verify that two different code paths create identical images.
/// * [flutter_test] for a discussion of test configurations, whereby callers /// * [flutter_test] for a discussion of test configurations, whereby callers
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment