# 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
