Create flutter specific leak troubleshooting guidance. (#157396)

docs/contributing/testing/Leak-tracking.md

@@ -0,0 +1,63 @@
+# Leak tracking in Flutter framework
+
+Flutter Framework widget tests use [leak_tracker](https://github.com/dart-lang/leak_tracker/blob/main/doc/leak_tracking/
+OVERVIEW.md) to detect leaks from objects that have not been disposed.
+
+This page contains Flutter Framework related information.
+
+See leak_tracker documentation for
+[general leak troubleshooting](https://github.com/dart-lang/leak_tracker/blob/main/doc/leak_tracking/TROUBLESHOOT.md).
+
+Test failures cause by leaks look like this:
+
+```
+Expected: leak free
+    Actual: <Instance of 'Leaks'>
+     Which: contains leaks:
+            # The text is generated by leak_tracker.
+            # For leak troubleshooting tips open:
+            # https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Leak-tracking.md
+            notDisposed:
+              total: 1
+              objects:
+                FocusNode:
+                  test: Align smoke test
+                  identityHashCode: 82308154
+```
+
+## When is it ok to opt-out from leak tracking?
+
+In general, leak tracking should be enabled, to verify that all
+disposables are disposed.
+If a tests is opted out, the reasons should be clearly explained
+in the comments.
+
+It is ok to opt out a test when a test
+throws an exception and the code did not finalize properly.
+
+While some exceptions should be finalized properly
+and should not result in leaking objects,
+the project to make sure disposables are disposed
+in exceptional code paths was not prioritized yet.
+See [issue #157470](https://github.com/flutter/flutter/issues/157470).
+
+## Where leak tracking is configured?
+
+Leak tracker is configured in [flutter_test_config.dart](https://github.com/flutter/flutter/blob/9441f8f6c806fb0a3b7d058a40b5e59c373e6055/packages/flutter/test/flutter_test_config.dart#L45).
+
+See [leak_tracker documentation](https://github.com/dart-lang/leak_tracker/blob/main/doc/leak_tracking/TROUBLESHOOT.md)
+on how to enable/disable leak tracking for individual tests and files.
+
+## What are defaults?
+
+Leak tracking is enabled on two test shards in Flutter's testing infrastructure:
+
+- [Windows framework_tests_libraries_leak_tracking](https://github.com/flutter/flutter/blob/9441f8f6c806fb0a3b7d058a40b5e59c373e6055/.ci.yaml#L5553)
+- [Windows framework_tests_widgets_leak_tracking](https://github.com/flutter/flutter/blob/9441f8f6c806fb0a3b7d058a40b5e59c373e6055/.ci.yaml#L5640C11-L5640C56)
+
+For local testing, or for test shards configuration, to enable leak tracking for flutter tests, pass
+`--dart-define LEAK_TRACKING=true` to `flutter test`.
+
+You can see the bot's status on the [Flutter build dashboard](https://flutter-dashboard.appspot.com/#/build).
+The bots are not blocking yet.
+See [a proposal to convert them to be blocking](http://flutter.dev/go/leak-tracker-make-bots-blocking).

packages/flutter/test/flutter_test_config.dart

@@ -44,6 +44,10 @@ Future<void> testExecutable(FutureOr<void> Function() testMain) {
   if (_isLeakTrackingEnabled()) {
     LeakTesting.enable();
     LeakTracking.warnForUnsupportedPlatforms = false;
+    // Customized link to documentation on how to troubleshoot leaks,
+    // to print in the error message.
+    LeakTracking.troubleshootingDocumentationLink =
+        'https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Leak-tracking.md';
     LeakTesting.settings = LeakTesting.settings.withIgnored(
       createdByTestHelpers: true,
     );