mirror of
https://github.com/flutter/flutter.git
synced 2026-02-20 02:29:02 +08:00
Golden Doc Updates (#39082)
This commit is contained in:
Kate Lovett
GitHub
parent
0ed3242a63
commit
c8af729d1c
@ -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 |  |
|
||||
/// | Difference |  |
|
||||
/// | Test image after modification |  |
|
||||
///
|
||||
/// 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 |  |
|
||||
/// | testName_testImage.png |  |
|
||||
/// | testName_isolatedDiff.png |  |
|
||||
/// | testName_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].
|
||||
///
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user