本技能用于指导在 Dart 测试中正确使用 expect 与 package:matcher,让断言更易读、失败信息更清晰。适用场景包括:编写基于 expect 的断言、把遗留的手工检查迁移为更简洁的匹配器、以及排查难以理解的测试失败。
主要能力与用法:集合类优先使用专用匹配器。长度校验用 expect(list, hasLength(n)) 替代比较 length;空判断用 isEmpty / isNotEmpty 替代对布尔属性比较 true;元素存在用 contains(item);无序比较用 unorderedEquals(items) 替代 containsAll;映射键值校验用 containsPair(key, value) 替代手工取 map[key] 或 containsKey。类型检查中,内联断言优先 isA<T>(),可链式调用 .having() 检查属性;定义顶层可复用匹配器时优先 TypeMatcher<T>,并可声明为 const。属性校验在 isA<T>() 或其他 TypeMatcher 上使用 .having(),闭包参数取有意义的名字,失败信息会指明具体哪个属性出错。异步断言使用 completion(matcher) 检查 Future 结果、throwsA(matcher) 检查异常,并配合 await expectLater(...) 保证时序。
可用于发现待改进模式的搜索正则包括:expect([^,]+.length,\s*、expect([^,]+.isEmpty,\s*(true|equals(true))、expect([^,]+.contains(.),\s(true|equals(true))、expect([^,]+[.],\s。
原则:选择能产生清晰失败信息的匹配器;避免用 if/for 手工逻辑做断言;使用最具体的匹配器。测试异步行为时务必 await expectLater,否则副作用检查可能在 Future 完成前运行,产生竞态。相关技能为 dart-test-fundamentals 与 dart-checks-migration(迁移到 package:checks 时使用)。限制与安装方式暂未提供。