Flutter Framework 泄漏追踪(Leak Tracking)实战指南:让 Widget 测试自动发现未释放对象
Flutter Framework 泄漏追踪(Leak Tracking)实战指南:让 Widget 测试自动发现未释放对象
本指南以 docs/contributing/testing/Leak-tracking.md 为骨架,结合 CPF-Flutter OpenHarmony 适配仓库(flutter_flutter)中 packages/flutter 与 packages/flutter_test 的实际源码,系统讲解 Flutter Framework 的泄漏追踪机制:如何在本地一键开启、失败信息如何解读、默认行为是什么,以及何时可以安全地对单个测试豁免泄漏检查。读完本文,你将掌握一套可立即落地到日常 widget 测试中的内存泄漏检测工作流。
快速上手:一行命令开启泄漏追踪
在 Flutter Framework 的 widget 测试中开启泄漏追踪非常简单,只需在运行 flutter test 时传入一个编译期参数:
flutter test --dart-define LEAK_TRACKING=true
该参数对当前目录下的所有 testWidgets 生效。也可以改用环境变量方式(见下文“配置入口”一节),二者效果等价。
说明:本仓库是 Flutter SDK/Engine 的 OpenHarmony 适配版,上述命令适用于本地开发机上的 Framework 测试;若你在 OpenHarmony 环境下运行测试,请以本仓库 ci/scripts/run_parallel_shards.sh 中的实际调用方式为准。
泄漏追踪做了什么
Flutter Framework 的 widget 测试借助 Dart 生态的 leak_tracker 系列包来检测未被 dispose 的对象。其核心思想是:测试过程中创建的 Disposable 对象(如 FocusNode、AnimationController、各种 ChangeNotifier 等)应在测试结束前完成释放;凡是创建了却没有被释放、且仍被引用(无法被 GC 回收)的对象,都会被报告为泄漏。
在本仓库中,相关依赖声明在 packages/flutter/pubspec.yaml:
leak_tracker_flutter_testing: any
leak_tracker_testing: any
leak_tracker: any
而 flutter_test 包的 packages/flutter_test/pubspec.yaml 同样依赖 leak_tracker_flutter_testing,testWidgets 测试框架在底层与它联动(详见 packages/flutter_test/lib/src/test_compat.dart)。
解读失败信息:泄漏长什么样
开启泄漏追踪后,如果某个测试存在泄漏,失败信息大致如下:
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
逐字段解读:
notDisposed:统计“已创建但未释放”的泄漏对象。与之相对的是notGCed(已释放却仍被引用、无法被 GC 回收)。两类泄漏都会被leak_tracker区分统计。total: 1:该类别下泄漏对象总数。FocusNode:泄漏对象的运行时类型。test: Align smoke test:泄漏发生在哪个测试中。identityHashCode: 82308154:该对象的身份哈希,用于在调试器中定位具体实例。
值得留意的是,失败信息中自带的排查文档链接,正是由本仓库的测试配置注入的(见下文“配置入口”)。
配置入口:flutter_test_config.dart 源码解析
本仓库中,泄漏追踪的全局配置位于 packages/flutter/test/flutter_test_config.dart,它对 packages/flutter/test 目录下每一个测试库生效(即每个测试文件运行前都会执行其中的 testExecutable)。
开启判断的核心函数如下(flutter_test_config.dart):
bool _isLeakTrackingEnabled() {
if (kIsWeb) {
return false;
}
// The values can be different, one is compile time, another is run time.
return const bool.fromEnvironment('LEAK_TRACKING') ||
(bool.tryParse(Platform.environment['LEAK_TRACKING'] ?? '') ?? false);
}
这里揭示了两个关键事实:
- 两种开启方式:编译期参数
--dart-define LEAK_TRACKING=true通过bool.fromEnvironment读取;运行期环境变量LEAK_TRACKING=true通过Platform.environment读取。二者取“或”关系,任一为真即开启。 - Web 平台默认关闭:
kIsWeb时直接返回false,原因是 Web 引擎存在已知的泄漏场景(详见testWidgets源码中的相关注释,见 packages/flutter_test/lib/src/widget_tester.dart)。
开启后执行的具体配置(flutter_test_config.dart):
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);
}
配置要点:
LeakTesting.enable():全局启用泄漏追踪。LeakTracking.troubleshootingDocumentationLink:定制失败信息中打印的排查文档链接,这正是上面失败输出中那一行注释的来源。LeakTesting.settings.withIgnored(createdByTestHelpers: true):忽略由测试辅助工具(test helpers)创建的对象,避免测试框架自身的临时对象被误报为泄漏。
默认行为:CI 与本地默认值
上游 CI 的两个专用分片
在原版 Flutter 的测试基础设施中,泄漏追踪默认在两个 CI 分片上开启:
- Windows
framework_tests_libraries_leak_tracking - Windows
framework_tests_widgets_leak_tracking
即 Framework 的“libraries”测试与“widgets”测试各有一个专属的泄漏追踪分片。本仓库(OHOS 适配版)的 CI 采用了不同的组织方式:framework 测试的并行分片由 ci/scripts/run_parallel_shards.sh 统一启动,其中包含 framework_tests libraries 与 framework_tests widgets 等多个分片(run_parallel_shards.sh)。需要在本仓库 CI 中开启泄漏追踪时,可在对应分片的启动命令中追加 --dart-define LEAK_TRACKING=true。
本地默认值
本地运行 flutter test 时,泄漏追踪默认关闭。要让所有 widget 测试启用泄漏检查,执行:
flutter test --dart-define LEAK_TRACKING=true
或设置环境变量后运行:
export LEAK_TRACKING=true
flutter test
两种方式效果相同(源码中二者是“或”关系)。
何时可以豁免(opt-out)某个测试
总的原则是:泄漏追踪应当保持开启,以验证所有 disposable 对象都被正确释放。若确实需要对某个测试豁免,必须在注释中清晰说明原因。
唯一明确允许豁免的场景是:测试抛出了异常,导致代码路径没有正常完成 finalize。虽然从理想角度讲,异常路径中的 disposable 也应被妥善释放,但 Flutter 团队尚未将“保证异常代码路径下对象全部释放”作为优先事项(参见上游 issue #157470)。因此,这类因异常中断而“非自愿”产生的泄漏,可以豁免。
豁免的三种粒度
从 flutter_test 的源码可以看到,泄漏追踪支持不同粒度的控制:
-
按测试豁免(推荐):
testWidgets提供了实验性参数experimentalLeakTesting,将其设为LeakTrackingForTests.ignore()即可关闭单个测试的泄漏检查。相关说明见 packages/flutter_test/lib/src/widget_tester.dart:/// To turn off leak tracking just for one test, set [experimentalLeakTesting] to /// `LeakTrackingForTests.ignore()`. -
按文件/包调整全局设置:在测试文件的
main()中(注意:不要放在setUp或setUpAll里)修改LeakTesting.settings;对整个目录生效的设置则放在对应目录的flutter_test_config.dart中。 -
豁免测试辅助对象:全局配置已通过
withIgnored(createdByTestHelpers: true)忽略由测试 helpers 创建的对象。
测试生命周期中的挂钩时机
testWidgets 在每个测试执行前后都会调用泄漏追踪的挂钩:
- 测试开始时
maybeSetupLeakTrackingForTest(experimentalLeakTesting, combinedDescription); - 测试结束后
maybeTearDownLeakTrackingForTest()(见 packages/flutter_test/lib/src/widget_tester.dart)。
另外,当 LeakTesting.enabled 为真时,flutter_test 会自动在每个测试文件末尾追加一次 tearDownAll,调用 maybeTearDownLeakTrackingForAll() 汇总该文件所有测试的泄漏结果(见 packages/flutter_test/lib/src/test_compat.dart)。这保证了即使单个测试未显式校验,文件级汇总报告也不会遗漏。
仓库内测试基建:如何验证泄漏检测本身
本仓库自带了一套用于验证泄漏检测机制自身的测试,可作为理解其行为的绝佳样例。
基准测试用例集
packages/flutter_test/test/utils/memory_leak_tests.dart 定义了 memoryLeakTests 用例集,覆盖了四种典型场景:
| 用例名 | 行为 | 预期泄漏 |
|---|---|---|
no leaks |
pump 一个普通 Container |
无 |
not disposed disposable |
创建 InstrumentedDisposable 但从不释放 |
notDisposedTotal: 1 |
not GCed disposable |
释放后仍被全局 _retainer 引用 |
notGCedTotal: 1 |
leaking widget |
创建会泄漏的 StatelessLeakingWidget |
notDisposedTotal: 1、notGCedTotal: 1 |
此外还有 dispose in tear down 等用例,验证通过 addTearDown 释放对象是否能被正确识别。这些用例直观展示了 notDisposed(未释放)与 notGCed(已释放但未被 GC)两类泄漏的判定边界——这也是你排查真实泄漏时首先要区分的两种情况。
驱动这些用例的测试入口
packages/flutter_test/test/widget_tester_leaks_test.dart 是上述用例的执行入口:它启用 LeakTesting.enable(),并针对每一条用例、每一种 LeakTesting 设置组合运行 testWidgets(..., experimentalLeakTesting: settings, ...),最后通过自定义的 _verifyLeaks 校验结果(见该文件 widget_tester_leaks_test.dart)。
Framework 内的真实使用
在 packages/flutter 的各类测试中,experimentalLeakTesting: LeakTesting.settings 被广泛使用——例如 packages/flutter/test/widgets/async_lifecycle_test.dart、packages/flutter/test/material/app_test.dart、packages/flutter/test/widgets/framework_test.dart 等,用于让特定测试显式参与泄漏检查(即使全局默认未开启时也能单独验证)。当你需要为某个测试单独开启/关闭泄漏检查时,可以直接仿照这种写法。
实践建议与排查思路
- 本地开启、CI 兜底:本地开发时优先使用
flutter test --dart-define LEAK_TRACKING=true全量运行,第一时间发现新增泄漏;在 CI 中为 libraries/widgets 分片常驻开启泄漏追踪,防止回归。 - 优先排查 notDisposed:失败输出中的
notDisposed通常指向某个忘记调用dispose()的 controller、FocusNode或StreamSubscription,修复方式是在测试内显式 dispose 或通过addTearDown注册释放。 - 区分 notGCed:对象已释放却仍被全局/静态引用持有,属于引用清理问题,检查是否有静态容器或单例缓存了该对象。
- 豁免要写注释:对确需豁免的测试,用
experimentalLeakTesting: LeakTrackingForTests.ignore()关闭并注明原因(例如“该测试预期抛异常,异常路径尚未保证 finalize”),不要无理由地大范围关闭泄漏检查。 - 以本仓库源码为最终依据:本文涉及的所有行为均可直接在本仓库源码中验证——全局配置见 packages/flutter/test/flutter_test_config.dart,
testWidgets的挂钩逻辑见 packages/flutter_test/lib/src/widget_tester.dart,文件级汇总见 packages/flutter_test/lib/src/test_compat.dart。具体版本行为请以当前仓库实际代码为准。