* Add a `matchesGoldenFile()` async matcher that will match
a finder's widget's rasterized image against a golden file.
* Add support for pluggable image comparison backends
* Add a default backend that does simplistic PNG byte
comparison on locally stored golden files.
* Add support for `flutter test --update-goldens`, which will
treat the rasterized image bytes produced during the test
as the new golden bytes and update the golden file accordingly
Still TODO:
* Add support for the `flutter_test_config.dart` test config hook
* Utilize `flutter_test_config.dart` in `packages/flutter/test`
to install a backend that retrieves golden files from a dedicated
`flutter/goldens` repo
https://github.com/flutter/flutter/issues/16859
This makes it possible to substitute 'flutter run' for 'flutter test'
and actually watch a test run on a device.
For any test that depends on flutter_test:
1. Remove any import of 'package:test/test.dart'.
2. Replace `testWidgets('...', (WidgetTester tester) {`
with `testWidgets('...', (WidgetTester tester) async {`
3. Add an "await" in front of calls to any of the following:
* tap()
* tapAt()
* fling()
* flingFrom()
* scroll()
* scrollAt()
* pump()
* pumpWidget()
4. Replace any calls to `tester.flushMicrotasks()` with calls to
`await tester.idle()`.
There's a guarding API that you can use, if you have particularly
complicated tests, to get better error messages. Search for
TestAsyncUtils.
* Refactor widget test framework
Instead of:
```dart
test("Card Collection smoke test", () {
testWidgets((WidgetTester tester) {
```
...you now say:
```dart
testWidgets("Card Collection smoke test", (WidgetTester tester) {
```
Instead of:
```dart
expect(tester, hasWidget(find.text('hello')));
```
...you now say:
```dart
expect(find.text('hello'), findsOneWidget);
```
Instead of the previous API (exists, widgets, widget, stateOf,
elementOf, etc), you now have the following comprehensive API. All these
are functions that take a Finder, except the all* properties.
* `any()` - true if anything matches, c.f. `Iterable.any`
* `allWidgets` - all the widgets in the tree
* `widget()` - the one and only widget that matches the finder
* `firstWidget()` - the first widget that matches the finder
* `allElements` - all the elements in the tree
* `element()` - the one and only element that matches the finder
* `firstElement()` - the first element that matches the finder
* `allStates` - all the `State`s in the tree
* `state()` - the one and only state that matches the finder
* `firstState()` - the first state that matches the finder
* `allRenderObjects` - all the render objects in the tree
* `renderObject()` - the one and only render object that matches the finder
* `firstRenderObject()` - the first render object that matches the finder
There's also `layers' which returns the list of current layers.
`tap`, `fling`, getCenter, getSize, etc, take Finders, like the APIs
above, and expect there to only be one matching widget.
The finders are:
* `find.text(String text)`
* `find.widgetWithText(Type widgetType, String text)`
* `find.byKey(Key key)`
* `find.byType(Type type)`
* `find.byElementType(Type type)`
* `find.byConfig(Widget config)`
* `find.byWidgetPredicate(WidgetPredicate predicate)`
* `find.byElementPredicate(ElementPredicate predicate)`
The matchers (for `expect`) are:
* `findsNothing`
* `findsWidgets`
* `findsOneWidget`
* `findsNWidgets(n)`
* `isOnStage`
* `isOffStage`
* `isInCard`
* `isNotInCard`
Benchmarks now use benchmarkWidgets instead of testWidgets.
Also, for those of you using mockers, `serviceMocker` now automatically
handles the binding initialization.
This patch also:
* changes how tests are run so that we can more easily swap the logic
out for a "real" mode instead of FakeAsync.
* introduces CachingIterable.
* changes how flutter_driver interacts with the widget tree to use the
aforementioned new API rather than ElementTreeTester, which is gone.
* removes ElementTreeTester.
* changes the semantics of a test for scrollables because we couldn't
convince ourselves that the old semantics made sense; it only worked
before because flushing the microtasks after every event was broken.
* fixes the flushing of microtasks after every event.
* Reindent the tests
* Fix review comments
Previously the widgets layer only provided a concrete binding, which
makes it awkward to extend it compared to other bindings. This moves
widgets to the same style as the other layers.
In a subsequent patch I'll use this to make the tests layer saner.
