Flutter测试迁移鸿蒙：test_process进程适配与CLI集成测试实践

我手头这个 Flutter 项目本来跑得好好的CI 上一套集成测试每天都稳定执行。第一次把整套验证迁移到鸿蒙开发板上时测试零零散散挂了一大片。我看日志还以为是打包脚本的问题点进去才发现错误清一色集中在dart:io的进程相关调用上有的直接抛ProcessException: No such file or directory有的干脆给你一句当前环境不支持 process 操作。这些挂掉的用例恰好是我用 test_process 写的那批外部进程集成测试——用例要启动端侧 CLI 工具、读取命令行输出、再按顺序断言结果。test_process 本身不是业务库它是 Dart test 生态里的测试辅助库。它把一个外部可执行文件包装成TestProcess提供 stdout/stderr 的行流、退出码、超时和 kill 能力我大量依赖它做命令行输出校验。适配到鸿蒙后问题不是 test_process 的断言逻辑变了而是它脚下踩的Process.start在鸿蒙环境中并不总是可用。这篇文章就围绕这条线展开怎么把 test_process 底层的进程能力从 Dart VM 默认实现替换成鸿蒙侧的子进程能力让外部进程交互、命令行输出校验、CLI 工具和自动化脚本协同这套事情在鸿蒙真机上真正跑起来。这篇文章适合两类人一类正把 Flutter 测试往鸿蒙设备迁移又不想重写全部测试代码另一类是打算在鸿蒙侧搭建一套端侧 CLI 集成测试体系、但还没摸清进程能力边界的人。1. 为什么迁移鸿蒙后第一批挂掉的单测全是进程类用例1.1 先分清“测试代码”和“被测试代码”的分层在一个 Flutter 工程里测试通常分纯 Dart 单测、Widget 测试、集成测试三层。很多人以为进程相关用例只出现在最后一层其实不是。我这次栽跟头最狠的反而是一批“看起来像单测”的用例测试代码里调用了Process.run拉起一个代码生成器把 stdout 和预期快照比对。这类用例看起来人畜无害但因为dart:io的 Process 真的会去操作系统拉起一个子进程所以它本质上依赖设备具备完整的进程创建和文件系统能力。在 Android 和 iOS 上这层依赖一直是一笔隐形账没人在意因为底层内核成熟哪台设备都支持。到了鸿蒙上Flutter 引擎跑在鸿蒙运行时之上Dart VM 的 IO 能力并不等于我们习惯的那种完整 Linux 环境。它不是编译期报错而是运行到那里才告诉你UnsupportedError或者进程启动失败。于是那批用例成了第一波重灾区。1.2 test_process 到底搭了什么积木test_process 的定位非常克制不像一个重框架更像一层薄封装。它公开两个核心入口startProcess返回TestProcessrunProcess返回FutureTestProcessResult。TestProcess做的是我们平时手写进程代码最容易写错的那堆事把 stdout 和 stderr 包装成StreamQueue方便按行读取也方便做“按顺序等待某个输出出现”的断言提供expectInOrder对命令行输出做有序匹配主动消费输出流避免缓冲区堆满导致子进程阻塞提供超时控制和进程回收能力。它的底层实现依然是Process.start。我一开始抱着侥幸心理以为只要鸿蒙引擎能跑Process.run就万事大吉后来排查才发现这种乐观没有任何依据。test_process 的适配本质上就是把它脚下的Process.start换成一个我们能控制的进程后端而不是重写它上面那套断言逻辑——那部分才是测试的价值所在。1.3 鸿蒙上到底缺了什么我在鸿蒙开发板上做了一个最小复现测试代码就三行用Process.start拉起echo等退出读输出。结果扑面而来的是ProcessException或者类似“当前环境不支持”的信息。这个现象说明 OpenHarmony 版 Flutter 运行时并没有完整实现dart:io的进程模块至少我手上这个构建没有。既然默认进程能力不可用适配就有两条路可以走。第一条路把测试运行环境改到普通 Linux 或 Android 模拟器上。这条路能保住大部分测试但绕过了真实鸿蒙设备上的 CLI 工具行为失去了“端侧集成测试”的意义。第二条路更符合标题里的目标把进程启动动作放到鸿蒙系统层去执行再通过 Flutter 的 MethodChannel 把 stdout、stderr、退出码这些数据传回 Dart 测试层。这就是我们要做的“鸿蒙化适配”核心思路给 test_process 换一个进程后端同时保留它的断言体验。2. 从 ohos.childProcess 到 Dart Process API 的能力对照表2.1 ArkTS 侧能完成的最小进程动作刚开始在 ArkTS 侧我也没什么现成经验可循尤其刚写完 Android 的ProcessBuilder到鸿蒙这边连从哪个模块创建子进程都要翻文档。查了一圈后确认当前 SDK 里有一个子进程能力模块名字形如ohos.childProcess。这里必须特别提醒不同版本 SDK 的导入路径和打开方式差异很大你在自己的工程里一定要以 IDE 的 API 检查为准。下面我把模块名当作一类能力来叙述不保证所有版本完全一致。ArkTS 侧启动一个外部进程大致的路径是这样import { childProcess } from kit.PerformanceAnalysisKit; let child childProcess.start(/data/local/tmp/hello_tool, [serve, --port8080], { env: { ...process.env }, });如果手头 SDK 还没开放这类子进程能力还有一个兜底方案调试态下走hdc shell替我们执行命令再把 stdout 通过 MethodChannel 传回 Dart。这个方案对集成测试完全够用因为集成测试本身就跑在开发者控制的真机或开发板上权限不是问题。它的缺点也很明显实时性差适合一次性命令不适合长时间交互式进程。所以我自己的方案是优先用系统子进程模块兜底方案只留给兼容老设备。2.2 逐项映射理论上dart:io的 Process 和鸿蒙侧能做的事情大部分能对上。我按 test_process 实际用到的能力整理了一个映射表这张表基本决定了桥接层要设计的接口形状能力Dart 侧 API鸿蒙侧适配建议启动一个可执行文件Process.start(cmd, args)调用系统子进程模块Process.run同理传入环境变量environment通过 start 参数里的 env 透传设置工作目录workingDirectory用命令包一层 cd 处理或让 CLI 支持--directory写入 stdinprocess.stdin.writeln(...)确认子进程模块的 stdin 是否可写不可写则改用文件重定向读取 stdoutprocess.stdout.asBroadcastStream()通过事件回调按行推回 Dart等待退出码process.exitCode监听 close 事件带回 exit code中途终止process.kill()调用子进程句柄的 stop/kill 能力获取 PIDprocess.pid优先用句柄暴露的 pid没有则由日志里的 pid 替代这个表不要当成死规则。exitCode这行实测中就有两种情况子进程正常结束时系统层 close 事件一定能拿到退出码但如果进程在启动阶段就失败系统层可能完全没有事件回来。这时候 Dart 侧要自己补一个约定退出码否则 test_process 会一直等到超时。2.3 进程交互的通信管道设计test_process 的模型是“流式交互”。它不会等所有输出齐全才开始断言而是在运行过程中不断消费 stdout 流用expectInOrder匹配预期行。这意味着桥接层的 stdout/stderr 必须是持续事件不能是最终攒好的一个字符串。所以我在鸿蒙侧维护了一个 channel 映射表每次 start 都动态分配一个唯一 channel 名把子进程句柄存起来const processChannels new Mapstring, childProcess.ChildProcess(); function startWithChannel(name: string, execPath: string, args: string[]) { const child childProcess.start(execPath, args, {}); processChannels.set(name, child); const channel new MethodChannel(name); child.stdout.on(data, (data: string) { channel.invokeMethod(stdout, { data: ${data} }); }); child.on(close, (code: number) { channel.invokeMethod(exit, { code }); processChannels.delete(name); }); return channel; }Dart 侧监听同一个 channel把回调接到自己的StreamController上。这一步跑通之后test_process 依赖的“进程输出从哪里来”的问题就解决了。后面剩下的所有工作其实都是在这个通信管道的细节上打磨。3. 用 MethodChannel 桥一层进程后端让 test_process 不再感知底层差异3.1 Dart 侧先抽象一个薄接口进入正式编码前先说明我的选择不去破坏 test_process 的使用方式而是用兼容方式替换它底层对Process.start的依赖。如果你能直接改仓库代码也可以改成自定义启动函数但目标都是保证TestProcess之上的测试代码不用动。我在 Dart 侧定义了一个薄后端接口class OhosProcess { final String _channelName; final _stdoutController StreamControllerString(); final _stderrController StreamControllerString(); final _exitCompleter Completerint(); StreamString get stdout _stdoutController.stream; StreamString get stderr _stderrController.stream; Futureint get exitCode _exitCompleter.future; Futurevoid kill() async { try { await ProcessChannel.of(_channelName).invokeMethod(kill); } on MissingPluginException { // 插件不可用时至少避免抛到测试用例里 } } }这个kill()是设计上的关键点。test_process 的超时逻辑依赖它能主动终止进程如果鸿蒙侧不能杀进程整个套件在 CLI 进入死循环时就会卡死。所以我把 kill 和 start 放在同等地位而不是后期补功能。3.2 ArkTS 侧事件转发ArkTS 侧每次 start 时动态创建 MethodChannelchannel 名必须全局唯一否则并发测试进程会串线。我第一个版本图省事用了固定 channel结果两个用例同时启动 CLI 时 stdout 全混在一起expectInOrder明明看到了内容但断言就是不通过。排查了很久才发现是 channel 把不同进程的数据串了线。改成唯一 channel 名之后问题立刻消失const channelName flutter_ohos_process_${processSeq};Channel 协议里我尽量精简start、stdout、stderr、exit、kill 五个方法就够了。不需要轮询因为鸿蒙侧子进程的事件是主动回调的轮询反而增加问题定位难度。3.3 参数转义问题桥接层第二个高发坑是“参数拼接”。Dart 侧如果直接写Process.start(sh, [-c, xxx])鸿蒙侧只需要把参数列表透传问题不大。麻烦的是有人习惯把整行命令当成一个字符串传进来比如gen --config/tmp/a.conf --flag。这时候鸿蒙侧必须自己做解析空格、引号、通配符全是 bug 源头。我的建议很粗暴永远保持args是列表不要允许用户提交一个 shell 命令字符串。如果确实需要管道、重定向这类复杂 shell 语法让调用方显式包一层sh -c由测试作者自己负责语义清晰。测试代码是给人读的可读性比省几个字符更有价值。3.4 输出事件与 test_process 断言结合后端启动成功之后stdout 流和expectInOrder就能配合使用了。不过这里有一个绕不开的细节鸿蒙侧 SDK 分包返回输出时Dart 侧如果原封不动把每次事件丢进StreamQueue偶尔会出现行被截断的情况。解决办法是在 channel 回调里先按换行符切分把不完整的尾部字符串缓存到下一条事件到达时再拼接。String _pending ; void _onStdoutChunk(String chunk) { _pending chunk; final lines _pending.split(\n); _pending lines.removeLast(); for (final line in lines) { _stdoutController.add(line); } }这个“攒行”操作直接决定expectInOrder的命中率。否则你会发现同样的 CLI 在鸿蒙设备上跑输出偶尔少最后一行偶尔冒出半个被截断的字符测试失败原因根本定位不到业务逻辑上。4. 端侧 CLI 集成测试套件从构建产物到输出断言4.1 准备一个可被测试的 CLI 产物设备侧要跑的 CLI 工具不是直接能在测试里引用的。首先要把它推到设备上还给够权限。如果工具是鸿蒙原生产物用hdc推到临时目录hdc file send ./build/cli_tool /data/local/tmp/cli_tool hdc shell chmod x /data/local/tmp/cli_tool如果 CLI 依赖动态库动态库也要一并推过去。这个细节早期坑过我测试用例运行时报libfoo.so not found排查半天发现只是动态库不在默认搜索路径。解决办法是把库所在目录加进LD_LIBRARY_PATH或者在启动参数里指定完整路径。测试代码里不要硬编码设备绝对路径。我建议用String.fromEnvironment(CLI_PATH)从环境变量读取路径不同开发机路径不同的时候不用改测试逻辑。4.2 编写三个典型的集成测试场景我用简化版示例展示 test_process 风格的断言。工具里有一个bundle子命令会读取一组资源配置和模板目录生成打包文件并在 stdout 打印校验和。test(bundle 输出行包含最终校验和, () async { final proc await startProcess( cliPath, [bundle, --input, fixtureDir.path, --format, txt], ); await proc.expectInOrder([ resolving templates..., writing bundle..., RegExp(rchecksum[0-9a-f]{64}), ]); await proc.shouldExit(0); }); test(外部参数缺失时输出到 stderr 且退出码非零, () async { final proc await startProcess(cliPath, [bundle]); await proc.expectInOrder([RegExp(rerror: missing required input)]); await proc.shouldExit(2); });这里要注意expectInOrder是顺序匹配会卡住测试直到所有模式按顺序出现。所以桥接层的 stdout 事件必须持续输出。如果你在底层用的是Process.run一次性拿到所有输出expectInOrder也能工作只是实时性差一点。还有一个经验在expectInOrder前用timeout参数控制每个读操作等待时长。我把默认 30 秒调到 10 秒后失败用例从“挂几分钟”变成“秒挂”调试效率提高很多。4.3 通过真实失败日志反查桥接层问题这个套件在真机验证时出现过一种典型失败形态测试在主机 Linux 环境跑expectInOrder能收到完整三行输出换到鸿蒙设备上跑只收到前两行第三行 checksum 永远等不到。一开始我怀疑是 CLI 在鸿蒙设备上的输出有差异后来把 channel 上的原始 chunk 打到日志文件才发现checksum 那一行不是没输出而是行尾嵌了一个\r在 shell 里看起来正常在 Dart 按\nsplit 之后就成了行的一部分。这个问题和底层执行通道强相关hdc shell、ArkTS 子进程模块、本地终端对\r\n的处理并不一致。要做跨平台一致的断言最好在后端把\r也去掉或者统一约定只允许\n。我在桥接层加了一个normalizeLineEnding开关默认打开测试代码里就不用到处写RegExp(r\r?\n)了。5. 把套件接进自动化脚本和 CI 流水线时的工程化细节5.1 设备准备套件最终要跑在真实鸿蒙设备上第一步是连接设备。hdc命令和 Android 的adb用起来很像但有些习惯要改。不要直接hdc list targets然后赌只有一台设备多设备环境下最好显式指定序列号run_on_device() { hdc -t $TARGET_SN shell $ }多设备并行执行时如果不指定-t大概率会随机选一台设备测试结果会变得不可控。5.2 一条自动化脚本的完整流程我在 CI 里把整套流程封装成一个 shell 脚本run_device_tests.sh按顺序执行设备检测、CLI 产物上传、权限修改、清除旧测试数据、执行测试、收集日志。hdc -t $TARGET_SN shell rm -rf /data/local/tmp/test_workspace hdc -t $TARGET_SN file send ./build/cli_tool /data/local/tmp/test_workspace/ hdc -t $TARGET_SN shell chmod x /data/local/tmp/test_workspace/cli_tool CLI_PATH/data/local/tmp/test_workspace/cli_tool \ flutter test integration_test/cli_tool_spec.dart -d $TARGET_SN hdc -t $TARGET_SN shell logcat -d /data/local/tmp/device_log.txt hdc -t $TARGET_SN file recv /data/local/tmp/device_log.txt ./artifacts/日志必须落盘到 CI artifact。设备端出了问题时至少能拿日志反查不至于为了一个断言失败把整套流程重跑一遍。5.3 端侧 CLI 与自动化脚本的协同方式“协同”这个词听起来玄落到实操就是几条硬约定CLI 的运行进度和关键结果写到 stdout不要只打日志文件CLI 要能响应终止信号这样测试超时后kill能快速生效测试脚本通过环境变量通知 CLI 当前是集成测试环境例如APP_ENVtest_debugCLI 输出格式要稳定尽量是keyvalue或 JSON方便在断言里用正则精确匹配而不是解析自然语言。我们的 CLI 早期版本退出时没有冲刷输出缓冲区导致shouldExit(0)通过之后 stdout 还差一行被 test_process 判断成“还有输出未消费”而超时。所以面向自动化测试的命令行工具退出前必须显式 flush 缓冲区。6. 实际适配中绕不开的四个边界场景6.1 沙箱权限不等于命令行权限HarmonyOS 应用沙箱对子进程启动的限制需要单独说。开发者设备上启动进程的权限和正式应用中暴露给一般用户时的系统策略完全不同。集成测试跑在开发态设备上权限通常足够但一旦发现 CLI 不是报“找不到文件”而是动不动Permission denied优先检查module.json5里的权限声明而不是怀疑桥接代码写错了。6.2 路径分隔符与文件系统差异路径问题是进程适配过程中最好定位又最容易犯的错。Dart 侧/data/local/tmp这类路径没问题但如果你用路径拼接工具在鸿蒙设备上动态生成路径要确认它生成的是不是设备实际能识别的格式。我在测试夹具里犯过这种错误目录路径以/结尾和子进程启动入口的路径再拼一次得到双斜杠启动直接失败。这类字符串边界问题排查起来非常消耗耐心建议在桥接层加一个路径规范性检查遇到空段就打印警告。6.3 信号退出与退出码语义测试用例想表达“进程被强制结束”时行动上调用kill就完事了但 test_process 在kill之后并不会立刻返回。系统层close事件有时无法把真实退出码传回来。我建议在 Channel 协议里增加一个exitType字段标记进程是正常结束还是被主动 kill。这样断言层能区分场景不会把“被 kill”误判成业务退出码 137 或 143避免错误断言。6.4 输出过大导致的背压CLI 输出特别大、测试用例又没有及时消费 stdout 时会出现背压。stdout 或 stderr 的缓冲区一旦写满主进程会被阻塞体现在测试里就是“进程永远不会退出”。test_process 通过 StreamQueue 主动消费输出来避免这个问题但桥接层如果自己缓存所有输出就会破坏这个机制。所以 Channel 转发时不要把数据囤积在 ArkTS 侧也不要为了减少事件次数而大批量攒行。流式事件稍微频繁一点没关系重要的是数据能持续流动。最后再分享一个我反复踩过之后的体会test_process 的expectInOrder是一把非常好用的尺子但它好不好用完全取决于底层进程的输出事件是否稳定。鸿蒙适配做到后面你会发现真正值得花时间的不是那套断言语法而是 stdout/stderr 事件从设备一路回到 Dart 测试层的这条链路上有多少隐形差异。把这层桥接稳定住CLI 工具、测试套件、自动化脚本三者协同就是水到渠成的事。