package:integration_test 数据驱动修复Data-Driven Fixesfix_data 目录规范与测试全指南【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutterfix_data目录是package:integration_test维护「数据驱动修复」规则由dart fix框架消费的核心位置本文基于 packages/integration_test/lib/fix_data/README.md 完整展开先讲清它在package:integration_test仓库中的具体作用再逐条拆解目录布局、文件命名、单文件容量限制与template.yaml的复制流程随后结合 test_fixes 的黄金样例说明测试体系最后交代与 flutter 主仓库及 dart-lang/sdk 的 CI 联动约束。读完你会掌握在 integration_test 包内新增一条修复规则并完成验证测试的完整落地流程。一、背景fix_data 在 package:integration_test 中扮演什么角色package:integration_test是 Flutter 官方用于在真实设备与模拟器上运行集成测试的框架。当它自身的公开 API 发生破坏性变更时例如给某个方法移除参数、重命名成员下游使用方代码往往会出现编译错误或弃用告警。为了帮助用户平滑升级仓库在lib/fix_data/下维护了一批.yaml文件这些文件就是dart fix 框架的数据驱动修复Data-Driven Fixes规则输入。它们描述「integration_test 的公开 API 发生了什么变化」并由两个工具消费分析服务器Analysis Server在 IDE 中提供 Quick Fix代码修复建议dart fix命令行对某个文件或目录批量应用代码改写。在本仓库中fix_data目录的规则文件服务于integration_test包自身而不是给其他包作者使用的通用 SDK 设施Flutter 的数据驱动修复仅对 Flutter packages 作者开放。整个格式层面的完整定义与编写语法element / transform / change / code template 等见仓库根目录的 docs/contributing/Data-driven-Fixes.md而本文专注描述integration_test 包内的落地目录约定。二、目录结构约定一个类一个文件一类一文件夹lib/fix_data不是平铺文件而是有严格的嵌套布局。以下是本仓库当前真实结构packages/integration_test/lib/fix_data/ ├── README.md # 本文对应的说明文档 ├── template.yaml # 新增规则的模板 └── fix_integration_test/ # 按“fix_filename”命名的分组文件夹 └── fix_binding/ # 针对某个类的 fix 文件子目录 └── fix_integration_test_widgets_flutter_binding.yaml对应规则如下按类拆分每个.yaml文件只服务单一类class。当前仓库中唯一一条规则针对IntegrationTestWidgetsFlutterBinding见 fix_integration_test_widgets_flutter_binding.yaml它来自integration_test/integration_test.dart库。命名规范单个文件命名为fix_class.yaml为了让同一主题相关的类聚合所有针对独立类的规则文件还要放进名为fix_filename的分组文件夹filename对应不含fix_前缀与.yaml后缀的文件主体例如fix_integration_test_widgets_flutter_binding.yaml归属于fix_binding/文件夹。新增流程新建.yaml文件时从template.yaml复制一份填入针对的目标类即可。复制出的文件头部注释里要求替换XXX占位符注明当前文件针对哪个类、来自哪个库文件。单文件容量上限不超过 50 条规则为了可维护性README 明确要求单个.yaml文件内的修复规则数量不应超过 50 条。快速统计方式是在文件中搜索title:关键字——每个 transform 都带一个title键因此title:的命中次数即可近似代表规则条数可通过grep -c title: file类命令验证。当规则数量逼近上限时就应当考虑按类拆分成新文件。三、剖析一条真实规则移除已弃用的 timeout 参数以当前唯一一条落库规则为例完整文件内容如下节选自 fix_integration_test_widgets_flutter_binding.yamlversion: 1 transforms: # Changes made in https://github.com/flutter/flutter/pull/89952 - title: Remove timeout date: 2023-06-26 element: uris: [ integration_test.dart ] method: runTest inClass: IntegrationTestWidgetsFlutterBinding changes: - kind: removeParameter name: timeout逐字段解读version: 1数据文件格式版本必须与工具链理解的版本一致用于兼容旧文件、识别无法理解的新格式title: Remove timeoutIDE 中展示给用户的修复说明宜短而通用date变更日期采用DateTime.parse可接受的字符串格式element指明被变更的 API 元素。这里表示「integration_test.dart库中、类IntegrationTestWidgetsFlutterBinding里的方法runTest」。注意uris使用的是缩写 URI去掉package:integration_test/前缀后的integration_test.dartchanges具体变更列表removeParameter配合name: timeout表示按名字移除一个命名参数若移除的是位置参数则用index指明零基下标。为什么存在这条规则看 integration_test 包当前实现即可印证——integration_test.dart 中runTest的签名override Futurevoid runTest( Futurevoid Function() testBody, VoidCallback invariantTester, { String description , Deprecated( This parameter has no effect. Use the timeout parameter on testWidgets instead. This feature was deprecated after v2.6.0-1.0.pre., ) Duration? timeout, }) async { ... }timeout参数已被Deprecated标记且不再生效官方建议改用testWidgets的timeout参数。当用户代码调用binding.runTest(..., timeout: Duration(minutes: 30))时分析器会产生弃用告警而这条 fix 规则就能自动把timeout:命名参数从调用处删掉——这正是「在 API 首次弃用时同步补充数据驱动修复」的最佳实践。值得说明的是数据驱动修复并不要求旧 API 仍然存活即便旧元素已被彻底删除只要用户代码引用旧名产生了诊断如“方法未定义”工具同样能套用规则完成改写。因此官方鼓励在弃用期一开始就补数据弃用期的诊断会保证规则在迁移窗口内就位。四、template.yaml每条新规则的起点template.yaml 是新增修复文件的模板其注释承担了「规范即文档」的作用头部维护说明新修复请加到文件顶部、用空行与旧规则分隔并在注释中附上引入该变更的 PR 链接强制测试每条修复都必须有对应测试并回链到 fix_data 的 README 与测试说明提供格式参考链接dart 官方的>import package:integration_test/integration_test.dart; void main() { final binding IntegrationTestWidgetsFlutterBinding.ensureInitialized(); binding.runTest( () async {}, () {}, // Changes made in https://github.com/flutter/flutter/pull/89952 timeout: Duration(minutes: 30), ); }对应的黄金文件 integration_test_widgets_flutter_binding.dart.expect 中timeout: Duration(minutes: 30),这一行已被移除其余代码保持不变。本地运行测试命令在test_fixes目录内执行下述命令即可对全部 golden 对进行校验cd packages/integration_test/test_fixes dart fix --compare-to-golden--compare-to-golden会实际运行数据驱动修复并把改写结果与.expect黄金文件比对任何不一致都会使测试失败。这是维护者新增或修改 fix 规则后必须通过的本地验证步骤。一处关键的分析器配置test_fixes/analysis_options.yaml 有一处易被忽略、却至关重要的开关linter: rules: # Since these test cases live inside the integration_test package, the # lint deprecated_member_use_from_same_package is required in # order to trigger them. Customer code (which lives outside of the # integration_test package) will be triggered by the analyzer warning # deprecated_member_use, which is enabled by default. - deprecated_member_use_from_same_package注释交代了因果测试夹具本身位于integration_test包内部Dart 默认对「同包内使用弃用成员」的告警deprecated_member_use_from_same_package不会自动触发而真实客户代码位于包外靠默认开启的deprecated_member_use告警触发。为了让包内夹具也能产生触发修复的诊断这里必须显式开启该 lint——若关闭它fixture 将不产生任何诊断修复规则无从触发golden 测试就会「静默通过」而失去意义。六、结构变更的外部约束两套 CI 都会执行这些测试README 特别提醒当对lib/fix_data目录做结构性改动时影响面不限于本仓库因为dart-lang/sdk 仓库的 CI 也会运行这套 fix 测试用于确保 dart fix 文件格式本身的演进不会破坏 Flutter。具体两处挂载点dart-lang/sdk 仓库的tools/bots/flutter/analyze_flutter_flutter.sh脚本会调用 flutter 的 fix 测试本仓库的 dev/bots/test.dart 同样承担 flutter 侧 fix 测试的调度职责。因此文档要求凡可能影响analyze_flutter_flutter.sh的改动如目录重组、文件重命名、格式升级应尽可能先与该脚本维护方协调。这意味着新增fix_*.yaml文件或调整test_fixes布局时要同时保证本仓库 CI 与 dart SDK 的集成调用都不会被破坏。七、新增一条修复的完整流程小结结合前文在package:integration_test内新增/维护一条数据驱动修复的推荐路径是定位变更确认 API 变更对应文件若在弃用期则立即补规则建文件复制template.yaml到lib/fix_data/fix_filename/fix_class.yaml保持「一类一文件」取消version/transforms注释将新规则置于文件顶部并附 PR 引用注释核对容量通过title:计数确保单文件不超过 50 条超限则按类拆分新文件补测试在packages/integration_test/test_fixes镜像布局下创建.dart夹具与同名.expect黄金文件并确保deprecated_member_use_from_same_package等触发条件满足本地验证在test_fixes目录执行dart fix --compare-to-golden确认实际改写与黄金文件一致联动检查涉及目录结构或格式层面调整时评估对 dart-lang/sdkanalyze_flutter_flutter.sh与本仓库 dev/bots/test.dart 两套 CI 调用链的影响。关于数据驱动修复 YAML 的完整格式参考transform set、element 种类、七类 change、code template、variable map、fragment/import 取值等请进一步阅读仓库根目录的权威文档 docs/contributing/Data-driven-Fixes.md在 packages/integration_test/test_fixes 中可以找到所有现役规则对应的夹具与黄金文件是学习编写范式的第一手样例。【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考