[rfw, ci] Regenerate goldens, manually roll #4835 (#4862)

This PR updates the goldens for `package:rfw`.

This PR also:

* Modifies `run_tests.sh` so it forwards all its command-line parameters
to the inner `test_coverage.dart` bin. (This enables passing
`--update-goldens` without much fuss.)
* Updates the documentation on how to update goldens in the package.

Author: ditman

.ci/flutter_master.version

@@ -1 +1 @@
-c175cf87a6a3d797fdc3f81cbd54419f639cd3d9
+685ce14b2d0f4046bd596842208d0c17f9a21e57

packages/rfw/.gitignore

@@ -1,3 +1,6 @@
+# Ignore golden test failure files
+test/failures/*.png
+
 # Miscellaneous
 *.class
 *.log

packages/rfw/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.0.15
+
+* Updates README.md to point to the CONTRIBUTING.md file.
+* Introduces CONTRIBUTING.md, and adds more information about golden testing.
+
 ## 1.0.14
 
 * Adds pub topics to package metadata.

packages/rfw/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing
+
+If you run into any problems, please file a [new
+bug](https://github.com/flutter/flutter/issues/new?labels=p:%20rfw,package,P2).
+Rather than waiting for a fix, we encourage you to consider submitting
+a PR yourself. See our [contributing
+guide](https://github.com/flutter/packages/blob/master/CONTRIBUTING.md)
+for details.
+
+Adding more widgets to `lib/flutter/core_widgets.dart` and
+`lib/flutter/material_widgets.dart` is welcome.
+
+When contributing code, ensure that `flutter test --coverage; lcov
+--list coverage/lcov.info` continues to show 100% test coverage, and
+update `test_coverage/bin/test_coverage.dart` with the appropriate
+expectations to prevent future coverage regressions. (That program is
+run by `run_tests.sh`.)
+
+## Tests
+
+To run the tests, use `flutter test`.
+
+To run the web tests, use `flutter test --platform=chrome`. If there
+is code that only runs on the web target, mark each such line by
+ending it with the string `// dead code on VM target`. This will
+exclude that line from the coverage calculation.
+
+Golden tests are only run against the Flutter master channel and only
+run on Linux, since minor rendering differences are expected on
+different platforms and on different versions of Flutter.
+
+## Golden test failures
+
+When golden tests fail, several files will be created in a `test/failures`
+directory.
+
+The suffix of each file briefly describes its contents:
+
+* `_masterImage`: The current golden against which comparisons are being made.
+* `_testImage`: The image generated by this run of the test.
+* `_isolatedDiff`: An image where only the pixels that differ between the
+  master and test images are rendered.
+* `_maskedDiff`: An image where the pixels that differ between the master and
+  test images are rendered in black (isolatedDiff + maskedDiff = testImage).
+
+Check the `_testImage` and the `Diff`s and see if the changes are valid. From
+time to time, a new dithering or anti-aliasing algorithm will land in Flutter
+that will invalidate a bunch of goldens, but not really break the rendering.
+
+In this case, you may update the golden files.
+
+### Updating golden files
+
+Once you've validated that the new goldens are correct, you may update them by
+calling `run_tests.sh --update-goldens`.
+
+That command updates the reference golden images in the `test/goldens` directory.
+
+Read more about Golden matching [in `package:flutter_test` API docs][package-test].
+
+[package-test]: https://api.flutter.dev/flutter/flutter_test/matchesGoldenFile.html

packages/rfw/README.md

@@ -965,29 +965,4 @@ concerns on iOS, anyway).
 
 ## Contributing
 
-If you run into any problems, please file a [new
-bug](https://github.com/flutter/flutter/issues/new?labels=p:%20rfw,package,P2).
-Rather than waiting for a fix, we encourage you to consider submitting
-a PR yourself. See our [contributing
-guide](https://github.com/flutter/packages/blob/master/CONTRIBUTING.md)
-for details.
-
-Adding more widgets to `lib/flutter/core_widgets.dart` and
-`lib/flutter/material_widgets.dart` is welcome.
-
-When contributing code, ensure that `flutter test --coverage; lcov
---list coverage/lcov.info` continues to show 100% test coverage, and
-update `test_coverage/bin/test_coverage.dart` with the appropriate
-expectations to prevent future coverage regressions. (That program is
-run by `run_tests.sh`.)
-
-To run the tests, use `flutter test`.
-
-To run the web tests, use `flutter test --platform=chrome`. If there
-is code that only runs on the web target, mark each such line by
-ending it with the string `// dead code on VM target`. This will
-exclude that line from the coverage calculation.
-
-Golden tests are only run against the Flutter master channel and only
-run on Linux, since minor rendering differences are expected on
-different platforms and on different versions of Flutter.
+See [CONTRIBUTING.md](https://github.com/flutter/packages/blob/main/packages/rfw/CONTRIBUTING.md)

packages/rfw/pubspec.yaml

@@ -2,7 +2,7 @@ name: rfw
 description: "Remote Flutter widgets: a library for rendering declarative widget description files at runtime."
 repository: https://github.com/flutter/packages/tree/main/packages/rfw
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+rfw%22
-version: 1.0.14
+version: 1.0.15
 
 environment:
   sdk: ">=3.0.0 <4.0.0"

packages/rfw/run_tests.sh

@@ -9,4 +9,5 @@
 
 set -e
 pushd test_coverage; dart pub get; popd
-dart --enable-asserts test_coverage/bin/test_coverage.dart
+set -x
+dart --enable-asserts test_coverage/bin/test_coverage.dart "$@"

packages/rfw/test/goldens/argument_decoders_test.containers.png

@@ -57,8 +57,13 @@ Future<void> main(List<String> arguments) async {
 
   final ProcessResult result = Process.runSync(
     'flutter',
-    <String>['test', '--coverage'],
+    <String>[
+      'test',
+      '--coverage',
+      if (arguments.isNotEmpty) ...arguments,
+    ],
   );
+
   if (result.exitCode != 0) {
     print(result.stdout);
     print(result.stderr);