去年年底我在做 Flutter 测试套件向鸿蒙 HarmonyOS 迁移的时候遇到了一件很诡异的事一套在 Android 上已经稳定跑了半年的用例搬到鸿蒙上之后一夜之间“绿”了 17 个用例。不是通过率变高了而是这些用例根本没有执行到断言那一步就悄悄返回了成功。这是典型的“假绿”——测试套件在撒谎而你完全不知道。后来我把异常断言相关的逻辑全部重写收敛成一个独立的组件内部代号就叫 expect_error。这次适配鸿蒙的实战让我把“怎么写异常断言”这件事彻底想明白了异常断言不应该是散落在测试文件里的零散 expect而应该是一套有入口、有链路、有结果归档的治理体系。这篇文章就把整个过程中的设计思路、踩坑记录和最终落地架构原原本本讲一遍适合正在做 Flutter 鸿蒙迁移、或者想系统化构建异常断言能力的团队参考。1. 从一次“假绿”测试说起异常断言为什么必须体系化1.1 鸿蒙迁移后我的测试套件学会了撒谎问题出现得很隐蔽。迁移测试套件的第一周一切看起来都很顺利Android 上 200 多个用例全绿鸿蒙上跑出来也是全绿而且耗时更短。我当时还以为是鸿蒙的运行时更快直到随手把一个用例的断言故意改错重新跑——它还是绿的。那一刻我才意识到问题严重性。逐个定位后发现真正被完整执行的用例只有不到三分之一其余的都是“起跑即终点”测试方法进入后异步逻辑还没完成测试框架就认为该方法执行完毕直接标记为通过。尤其集中在涉及 MethodChannel、平台视图和异步回调的场景里。说白了异常是在测试结束之后才抛出来的框架根本接不住。这个现象在 Android 上没有出现是因为 Android 端 Flutter 引擎的事件循环和线程调度恰好能把异常压回测试 Zone 内而鸿蒙的异步消息队列调度时机不同异常被延后或直接吞掉。这提醒我如果只把迁移当作“跑一遍试试”测试可靠性根本无从谈起。1.2 原生断言写法在异常场景下的四个致命伤把当时测试代码里的异常断言全翻出来看问题非常集中也和绝大多数 Flutter 项目里常见写法一致痛点典型表现后果类型依赖过强直接throwsA(isAFooException())鸿蒙平台层包装后异常类型变化断言直接失效异步捕获盲区expect(() async {...}, throwsException)async 函数闭包返回 Future断言作用在闭包执行瞬间而非 Future 完成之后缺少上下文断言只关心异常类型不知道从哪个业务模块、哪条链路抛出来的出问题后只能靠日志猜位置失败信息碎片化多个异常断言各自为政没有统一报告一次测试失败无法快速判断是新增缺陷还是已有问题这些不是写法水平问题而是缺少一整套围绕“异常”的断言抽象。Flutter 官方 test 包给了很好的底层能力但把底层能力直接铺在业务测试里就必然产生上面这些碎片和盲区。所以我的决定是写一个组件把异常断言从“行为”升级为“治理”。1.3 expect_error 的目标定位expect_error 不是要替代package:test或者flutter_test它要解决的是中间这一层问题在测试代码和异常发生点之间建立一个稳定、可追溯、跨平台一致的断言通道。它承担三件事第一统一同步、异步、事件驱动三种异常断言入口第二兼容鸿蒙平台对异常类型的包装与改写第三为每次断言生成错误链路快照让异常断言天然带上可观测性。整个组件的核心思路可以概括成一句话把“写断言”变成“登记异常”——你不需要在测试里猜异常怎么冒出来只需要告诉 expect_error 你关心什么剩下的捕获、校验、归档都交给它。2. expect_error 的核心设计把“写断言”变成“登记异常”2.1 统一入口同步、异步、事件驱动三种模式最开始我也犹豫过要不要保留原生expect(() {}, throwsA(...))风格做一层薄封装就行。后来发现不行。因为底层throwsA对异步场景的支持天然别扭——它接收的是一个函数这个函数如果是异步的返回的是 FuturethrowsA无法感知 Future 内部的异常。这也正是鸿蒙上大量“假绿”的根源之一。所以我设计了统一入口不再区分断言宏而是区分异常产生的方式// 同步场景直接传入会产生异常的闭包 expectError( () divide(10, 0), onError: (cause) { expect(cause.type, ArithmeticException); expect(cause.detail, contains(division by zero)); }, ); // 异步场景传入返回 Future/Futurevoid 的函数 await expectError( () fetchUserProfile(token_expired), asynchronously: true, timeout: const Duration(seconds: 5), onError: (cause) { expect(cause.linkId, startsWith(network.user.profile)); }, );同步和异步之所以必须分开设计是因为捕获机制完全不同。同步异常由函数调用栈直接抛出闭包内 try-catch 就能接住异步异常则必须等待 Future 完成并在 completer 层面接管错误。而事件驱动场景比如某个 Widget 在 build 期间抛错既不是同步也不是单纯异步它落在 FlutterError 的全局捕获通道里需要额外的桥接钩子。// 事件驱动场景监听 FlutterError.onError / PlatformDispatcher.instance.onError final subscription FlutterError.onError.listen((details) { expectErrorFromEvent(details, onError: (cause) { expect(cause.origin, widget.build); }); });三种模式共用同一个ErrorCause数据模型后续的链路归档和报告生成全部复用不用各写一套。2.2 错误谓词从“匹配类型”升级为“匹配特征”Flutter 里最常见也最脆弱的断言方式就是isASomeException()。在纯 Dart 环境下这个写法问题不大但一旦进入鸿蒙平台层异常从平台通道传回来时类型信息会经过一次“翻译”结果是你在测试里看到的异常类型往往不是业务代码里真正抛出的类型。所以 expect_error 放弃了单点类型匹配改为一个更宽松但更可靠的“特征谓词”体系。你可以从四个维度描述一个异常类型名、消息片段、错误码、链路 ID。命中条件默认是“任意特征匹配即可”也可以通过match: MatchMode.strict要求全命中。await expectError( () channel.invokeMethod(storage/read, {key: config}), asynchronously: true, match: MatchMode.strict, onError: (cause) { expect(cause.type, contains(PlatformException)); expect(cause.code, STORAGE_READ_FAILED); expect(cause.detail, contains(NoSuchFile)); }, );为什么要这么设计因为跨平台场景里异常类型是最不稳定的一层。鸿蒙对 Flutter 平台通道异常的包装方式我后面会详细讲这里先记住结论——按特征断言不按类型断言能把测试对底层实现细节的耦合降到最低。业务代码里改了异常类名、换了包装方式只要关键特征还在断言就还能守住底线。2.3 超时、快照与“异常未发生”的判定异常断言里最容易被忽略的场景是测试关心的是“某段代码必须抛异常”结果它没抛。原生写法下throwsA遇到“没抛”会直接报 expectation 失败信息量几乎为零。你只知道它没抛不知道为什么没抛。expect_error 做了两件事补上这个缺口。第一是超时控制异步断言默认 3 秒内没有异常上报就触发ExpectTimeoutException同时把已收集到的上下文信息原样保留。第二是快照生成无论断言成功还是失败都会把当前请求参数、错误码、堆栈帧摘要、耗时写入一条结构化记录。class ErrorCause { final String type; final String? code; final String? detail; final String? linkId; final StackTrace? stackTrace; final DateTime occurredAt; final Duration elapsed; }有了快照测试失败就不再是一个孤零零的红叉而是一条“错误现场的录像”。尤其在鸿蒙这种平台行为差异较多的环境里快照几乎成了定位问题的第一手材料。3. 鸿蒙适配绕不开的三道坎桥接差异、异步时序与错误码漂移3.1 第一道坎MethodChannel 异常在鸿蒙上会被包一层“马甲”鸿蒙适配过程中第一个让我真正动手改代码的问题就是平台通道异常的包装差异。在 Android 上Flutter 调用 MethodChannel 后如果原生侧抛出异常最终落到 Dart 侧的通常是一个PlatformException类型清晰、message 可读、details 里还能带附加信息。但鸿蒙侧并非总是如此。实际跑下来一部分异常确实能映射成PlatformException另一部分却会被包裹成通用的PlatformException(code: -1, message: unknown error)真正的错误码和原因被塞进了details字段的深层嵌套里。如果断言直接盯 code 或 type必然翻车。我的解包方案是加一层_unwrapPlatformError对平台通道返回的异常做递归解析把深层 details 里的业务错误码和原始消息提取到统一模型里ErrorCause _unwrapPlatformError(Object error) { if (error is PlatformException) { final code error.code; final detail _extractNestedDetails(error.details); if (code -1 || code unknown_error) { return ErrorCause( type: _resolveRealType(detail) ?? error.runtimeType.toString(), code: _resolveRealCode(detail) ?? code, detail: detail, ); } return ErrorCause(type: error.runtimeType.toString(), code: code, detail: detail); } return ErrorCause.fromUnknown(error); }_extractNestedDetails会遍历details里的 Map/List 结构优先取code、errCode、description、msg这些常见字段。这一层解包做完测试代码里对异常特征的描述才和平台实现完成了解耦。鸿蒙版本后续如果调整了包装结构也只需要更新解包规则断言语义不用动。3.2 第二道坎异步时序差异导致异常“迟到”甚至“缺席”回到文章开头那个“假绿”问题。我定位它的过程完整复现一下方便你对照排查。第一步我在可疑用例里插入日志发现测试方法结束时异常确实还没发生第二步在异常真正抛出的地方单独打日志确认异常存在、且堆栈完整第三步确认 FlutterError 和 Zone 的全局回调里都收到了这个异常但它就是没有被测试断言捕获。关键点就在第三步。测试框架是靠 Zone 来捕获异步异常的而鸿蒙的异步任务调度在某些场景下会把任务投递到引擎内部的另一个 Zone导致测试 Zone 里的runZonedGuarded收不到异常。说白了异常发生了但它发生在你监控范围之外。解法是给 expect_error 的异步模式加一个“强制归约”机制不依赖调用方 Zone 的自动捕获而是用 Completer 显式接管 Future并在超时定时器触发时主动判定失败FutureT _runWithTimeoutT(FutureT Function() task, Duration timeout) { final completer CompleterT(); final timer Timer(timeout, () { if (!completer.isCompleted) { completer.completeError(ExpectTimeoutException(timeout)); } }); task().then((value) { if (!completer.isCompleted) { timer.cancel(); completer.complete(value); } }).catchError((Object e, StackTrace st) { if (!completer.isCompleted) { timer.cancel(); completer.completeError(e, st); } }); return completer.future; }这里有个细节值得注意catchError必须显式声明参数类型Object e否则 Dart 的强类型分析会把catchError当成可能吞掉异常的处理导致异常被静默处理。这个写法保证异常无论何时到达都会被 Completer 接住再通过我们自己的错误链路传递不再依赖 Zone 的隐式行为。3.3 第三道坎不同版本鸿蒙错误码漂移断言怎么稳住鸿蒙适配里最隐蔽的问题是错误码在不同系统版本间并不稳定。同一个“文件不存在”场景在某个 API 版本上是errorCode: 101到了另一个版本变成了errorCode: 300003但语义其实一样。如果断言写死错误码升级系统后测试会突然大量失败而且每次失败都是误报。应对思路是建一张“错误码归义表”把不同版本的错误码映射到统一的业务语义上。expect_error 在鸿蒙模式下会先做一次归义解析再交给断言语义层class OhosErrorCodeNormalizer { static const MapString, ListString _semanticGroups { resource_not_found: [101, 300003, FILE_NOT_FOUND, NO_SUCH_FILE], permission_denied: [201, 100401, PERMISSION_DENIED], network_unreachable: [103, 200001, NETWORK_UNREACHABLE], }; static String normalize(String rawCode) { for (final entry in _semanticGroups.entries) { if (entry.value.contains(rawCode)) return entry.key; } return rawCode; } }断言的正确姿势变成了expect(cause.code, resource_not_found);这么做的好处是测试关注的是业务语义不是某个版本的具体实现。错误码表需要持续维护但收益非常明显——系统版本升级时测试套件不会再被一堆“假失败”淹没。4. 从单点断言到全链路错误链路捕捉架构的落地方式4.1 四层异常收集体系单个断言写得再稳如果没有链路视角异常治理仍然是零散的。我在鸿蒙适配的后半段把 expect_error 从断言组件升级成了完整的错误链路捕捉架构分四层层级异常来源捕获点典型场景单元层纯 Dart 函数/类同步闭包入口工具类、状态管理逻辑组件层Widget build/layoutFlutterError.onError组件渲染异常平台层MethodChannel/EventChannel通道消息回调鸿蒙原生能力调用失败全局层未捕获异步异常PlatformDispatcher.instance.onError后台任务、Timer、Stream 回调四层捕获到的异常统一汇入一个链路节点队列。每层之间用节点上下级关系串联最终形成一棵错误链路树。这个设计的动机是线上问题很少是单点失败往往是“组件加载失败 - 平台能力调用失败 - 权限不足”这样的级联链条传统断言只能告诉你最后一步链路树能告诉你完整的因果。4.2 链路 ID 与上下文透传要让链路可追踪必须先有链路 ID。expect_error 在测试初始化时生成一个全局linkId通过 Zone 变量向异步子任务透传const _linkIdKey #expectErrorLinkId; String get currentLinkId Zone.current[_linkIdKey] as String? ?? unknown; R runWithLinkIdR(String linkId, R Function() body) { return runZoned(() body(), zoneValues: {_linkIdKey: linkId}); }这样只要业务代码或测试代码在同一个 Zone 体系里发起异步调用错误捕获时就能从Zone.current里读出链路 ID让每一条异常都自动挂到正确的链路上。不需要侵入业务代码传参这是 Zone 机制在错误可观测性上最大的价值。4.3 断言结果聚合与报告输出所有层级的错误链路最终被聚合成一份结构化报告。报告包含链路 ID、节点数、每层断言的命中情况、超时统计以及未捕获异常清单。CI 阶段可以把报告序列化成 JSON归档到测试管理平台本地调试时则输出到控制台用缩进表现层级class ErrorLinkReport { final String linkId; final ListErrorLinkNode nodes; final Duration totalElapsed; final bool allAssertionsMatched; } class ErrorLinkNode { final String nodeName; final int depth; final DateTime occurredAt; final ErrorCause cause; final ErrorLinkNode? parent; }这套报告机制带来的一个直接变化是测试失败从“某个用例挂了”变成了“某条链路上哪个节点出了什么问题”。排查效率提升得非常明显尤其是在鸿蒙平台行为还不完全稳定的时候一份带链路结构的报告基本就是给定位问题开了天眼。5. 实战收益与维护禁忌5.1 迁移后三个立竿见影的变化expect_error 在鸿蒙测试套件上跑稳之后我观察到了三个非常具体的变化。第一个假绿率归零。所有异步用例都必须显式等待异常或超时结论测试框架再也没出现过“没执行就通过”的情况。第二个异常定位时间从小时级降到分钟级。错误码漂移和平台包装问题在解包层统一处理后测试失败直接指向业务语义不用再翻平台日志。第三个用例的可读性变好了。写断言的同事不再需要关心异常捕获机制只需要描述“这段代码应该报什么特征错误”理念上从底层 API 使用变成了领域规则描述。5.2 过度断言是比漏断言更隐蔽的坑在我把 expect_error 推广给团队后很快遇到了新问题有人把特征谓词写得太死。比如对detail字段精确匹配整段错误描述结果业务侧调整了一个措辞测试就红了。还有人在一个同步用例里叠加十多个断言把实现细节全部固化重构时处处掣肘。我的建议是异常断言遵循“三层原则”第一层断言业务语义错误码归义后的结果第二层断言关键消息片段用contains而不是精确匹配第三层才断诊断言堆栈或耗时等附加信息。前两层是必须的第三层默认不写。这样既守住了核心质量底线又给业务代码留了演进空间。5.3 这个架构还能怎么扩展目前这套错误链路捕捉架构已经稳定跑在鸿蒙和 Android 双端。后续我计划把链路报告接入实时监控大盘把测试环境的异常数据同步用于灰度发布前的风险预判。还打算把错误码归义表做成配置热更新的形式鸿蒙每次发版后由 CI 自动比对错误码差异把漂移检测前置到版本发布之前而不是等测试跑了才发现。最后分享一个我一直强调的细节异常断言治理的成败不取决于断言怎么写而取决于错误链路能不能打通。只要链路是通的断言早晚能补全链路断着断言写得再漂亮也是自欺欺人。做鸿蒙适配尤其要记住这一点——先解决假绿再谈覆盖率。