diff --git a/docs/contributing/testing/Leak-tracking.md b/docs/contributing/testing/Leak-tracking.md new file mode 100644 index 0000000000..eede05913e --- /dev/null +++ b/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: + 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). diff --git a/packages/flutter/test/flutter_test_config.dart b/packages/flutter/test/flutter_test_config.dart index b11a72d4ea..381abc2283 100644 --- a/packages/flutter/test/flutter_test_config.dart +++ b/packages/flutter/test/flutter_test_config.dart @@ -44,6 +44,10 @@ Future testExecutable(FutureOr 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, );