使用文档

uitest-sdk 0.8.0 · Node.js ≥ 20 · MIT

把鸿蒙 uitest 的设备侧扩展封装成 TypeScript API:一条 TCP 长连接(agent.so)负责点击、滑动、截图与 UI 树;另一条 gRPC 通道(libscreen_casting.z.so)负责 H.264 投流与 MP4 录制。0.2.0 起,同一套能力还有一层命令行,可作为 uitest-phone 使用,也能以 MCP 暴露给 Agent。

1. 安装与前提

npm install uitest-sdk
npx uitest-sdk doctor      # 确认设备与所需能力都在

扩展必须由华为签名才能在真机加载(XPM 校验拒绝未签名 .so)。本包内置的是实测可用的签名版本。

2. 快速开始

import { Device } from "uitest-sdk";

const dev = await Device.connect(); // 只有一台设备时可省略参数
try {
  const { width, height } = await dev.agent.getDisplaySize();

  await dev.agent.click(width / 2, height / 2);
  await dev.agent.swipe(width / 2, height * 0.7, width / 2, height * 0.3);

  const jpeg = await dev.agent.captureScreen(); // 608×1344 JPEG
  console.log(`captured ${jpeg.length} bytes`);
} finally {
  await dev.dispose();
}

可运行的版本在包里:node_modules/uitest-sdk/examples/quickstart.mjs。

3. 核心概念

坐标

所有触摸坐标都是逻辑显示坐标,即 getDisplaySize() 返回的那套(例如 1216×2688)。captureScreen() 默认按 scale: 0.5 出图(608×1344);把截图上的点换回显示坐标,乘以 display.width / 608。

扩展与 daemon

Device.connect() 依次完成:读 ABI → 推送对应 agent.so(必要时也推 casting 扩展)→ 如果没有 daemon 在监听 8012 就拉起一个 → 建 hdc fport 隧道 → 连上 TCP → 用一次 getDisplaySize() 做健康检查。任何一步失败都会清掉自己建立的隧道与 daemon,然后抛错。

失败即报错

每个失败都是 UitestError 的子类,带稳定的 code。SDK 不做静默降级:能走 H.264 就走 H.264,走不了会通过 cast.castKind 明确告诉你走的是 MJPEG。

4. Device

import { Device } from "uitest-sdk";
const dev = await Device.connect(options?);

DeviceOptions

字段类型默认说明
hdcPathstring自动查找查找顺序:HDC_PATH → PATH → 常见 DevEco 安装位置
deviceIdstring唯一设备多设备时必须指定(或设 HDC_TARGET)
agentPortnumber8012本地隧道起始端口,被占用时向后找空位
autoRestartbooleantrue断开后下一次调用自动重连;进行中的请求不会重放
extensionDirstring包内 assets/按 <dir>/<abi>/agent.so 查找
requestTimeoutMsnumber30000单次请求超时;超时后连接被丢弃
ownDaemonbooleanfalse为 true 时 dispose() 杀掉本实例拉起的那个 daemon
retryOnBusybooleantrue设备全局锁冲突时按抖动退避重试

属性与方法

成员类型说明
dev.agentAgentClient长连接客户端
dev.cliCliRunner走 uitest dumpLayout 的窗口级工具
dev.filesFiles设备文件:list / stat / mkdir / remove / move / push / pull / readText
dev.stateconnected / disconnecteddispose() 后变为 disconnected,再调用抛 EDISPOSED
dev.ownsDaemonboolean本次连接是否由自己拉起 daemon
dev.resolveCastExtension()string / null该 ABI 的 casting 扩展路径
dev.createCast(opts)Promise<CastClient>创建投流或录制
dev.dispose()Promise<void>关连接、撤销自己的 fport;ownDaemon: true 时再杀掉自己的 daemon

5. AgentClient:UI 自动化

所有方法都返回 Promise,失败抛 UitestError。

显示

await dev.agent.getDisplaySize();     // { width: 1216, height: 2688 }
await dev.agent.getDisplayRotation(); // 0 / 1 / 2 / 3

触摸

await dev.agent.click(x, y);
await dev.agent.touchDown(x, y);
await dev.agent.touchMove(x, y);
await dev.agent.touchUp(x, y);
await dev.agent.swipe(x1, y1, x2, y2, { steps?: number; durationMs?: number });

文本与按键

await dev.agent.inputText(x, y, "hello"); // hypium Driver.inputText
await dev.agent.triggerKey(keyCode);

截图

const jpeg = await dev.agent.captureScreen();               // 608×1344 JPEG Buffer
const jpeg2 = await dev.agent.captureScreen({ scale: 1 });  // 1.1.10 上 scale 无效

实现是「起一次采集流 → 取第一帧 → 停止」,这是设备上最快的整屏路径。

连续取帧(MJPEG)

for await (const jpeg of dev.agent.streamScreen({ scale: 0.5 })) {
  // jpeg 是完整的 JPEG Buffer
  if (done) break;
}

采集是脏区驱动的:静止画面只出 1 帧然后不再出帧,这不是卡死。断开循环会自动 stopStream()。

UI 事件流

for await (const ev of dev.agent.streamUiActions()) {
  console.log(ev.type, ev);
}

只上报真实用户输入;通过 agent 注入的合成触摸不会回传。stopCaptureUiAction 会关闭会话。

事件与低层接口

const off = dev.agent.onFrame((jpeg) => void 0);
const offClose = dev.agent.onClose((err) => void 0);
dev.agent.connected; // boolean
dev.agent.close();   // 主动关闭,之后不再重连

await dev.agent.call("CtrlCmd", { api: "getDisplaySize", args: [] });
await dev.agent.hypium("Driver.screenCapture", "Driver#0", []);

call 的 method 只能是 "Captures" / "CtrlCmd" / "Gestures" / "callHypiumApi"。

6. Session 与命令行

Session 是 SDK 里「一个任务看一台设备」的那一层:它持有租约(两个任务不能交错)、策略(危险步骤在碰设备前停下)、ref 表(ref 只指向它被观察时的那个元素)和 trace。CLI 的每条命令都只是开一个 Session、跑一步、关掉。

直接使用 Session

import { Device, Session } from "uitest-sdk";

const dev = await Device.connect();
const session = await Session.open(dev, { task: "check WLAN" });
try {
  await session.observe();                 // 读屏并记录
  const r = await session.tap({ ref: 12 }); // 按 ref 点击
  console.log(r.status, r.text);           // settled · 一行 diff
} finally {
  await session.release();                 // 释放租约、关 trace、dispose 设备
}
成员说明
Session.open(device, opts)取设备租约;被别的任务占用时抛 LeaseHeldError,此时设备还没被读写
observe() / screen()读屏并记录;screen() 返回上一次读到的屏幕,没有则新读
tap(target, opts){ref} 走坐标点击,{text} 或 On 走设备自己的 Component.click
type(text, opts)默认输入到焦点框;密码框在任何按键前被策略拒绝。{paste: true} 一次粘贴而不是逐字符输入,实测 36 字符 1.3 s 对 2.8 s
swipe / longPress / doubleClick / drag / fling / pinch手势;pinch 走 PointerMatrix,单指通道表达不了两条同时的轨迹
waitFor / readList / scrollUntilVisible设备侧等待、逐屏读列表、逐屏翻到目标
window(filter, opts)报告焦点窗口或某 bundle 的窗口,可 focus / close
pressKey(key)命名按键或数字 key code
steps本会话已记录的步数
release()结束任务

SessionOptions

字段类型默认说明
taskstring—任务名,出现在租约、trace 与报告里
stateDirstring.uitest-phonetrace、截图、租约所在目录
leaseobject | false开false 表示放弃独占
policyPolicyOptions—read-only、confirm 规则、应用白名单
traceShotsbooleanfalse每步存一张截图
settleMsnumber3000动作后等待 UI 稳定的上限
noTracebooleanfalse不读写 trace 文件

命令行

安装后命令名是 uitest-phone;npx uitest-sdk <command> 等价,无需全局安装。

uitest-phone doctor
uitest-phone observe --task "check WLAN"
uitest-phone inspect --html layout.html
uitest-phone tap --ref 12 --task "check WLAN"
uitest-phone read-list --ref 20
uitest-phone report --title "WLAN check"
uitest-phone live                        # 浏览器里投屏 + 节点表(0.7.0)

全局 flag 对所有命令生效:--task、--state-dir、--device、--read-only、--apps、--confirm、--settle-ms、--trace-shots、--approval-id、--approval-scope、--json。完整命令与参数见 --help 与随包 Skill 的 REFERENCE.md。

状态与退出码:settled 0、uncertain/not_found 1、lease_held/handoff/device_locked/device_needs_setup/device_offline 2、approval_pending 3、blocked/approval_denied/stale 4。--json 时输出 {status, code, text, data}。

设备本身不可用时也有名字:锁屏是 device_locked(不把锁屏当成页面去点),连上但没授权调试是 device_needs_setup,没插/关机/Offline 是 device_offline。三者都以退出码 2 停下,Agent 应请人解锁、点「允许」或插线,而不是重试。

凭据脱敏

observe、动作后的 diff、read-list、screenshot、--trace-shots 与 report 共用一份屏幕模型:密码框的值显示为 ••••••;凭据语境里的 3–8 位验证码显示为等长圆点,前后的词保留,策略仍能分类。被遮住的元素不能再按原文找到(tap --text 482913 返回 not_found),截图里的对应区域盖成灰色。低层 agent.captureLayout() / captureScreen() 返回设备原样数据,不脱敏。

MCP 与 Skill

uitest-phone mcp               # stdio 上以 JSON-RPC 2.0 暴露 uitest_<command>
uitest-phone install-skill     # 写进 ~/.claude/skills 与 ~/.agents/skills

MCP 进程只开一次设备,工具调用不再付每步的设备启动开销。返回非 settled 的工具调用是 isError: true 的工具错误,文本里带状态与原因,而不是传输失败。install-skill 同时写两个目录:~/.claude/skills 给 Claude Code,~/.agents/skills 是 agentskills.io 的跨 runtime 别名,Codex、Copilot CLI、Gemini CLI 都读它。两个目标先全部检查再写,拒绝时不会留下半套;已有的 SKILL.md 默认保留,除非给 --force。升级不需要重跑:安装目录里记着版本与文件摘要,mcp 启动时会把本包写的那份就地更新到当前版本;人改过的与手写的副本不动。

一步接好 Agent0.4.0

uitest-phone connect                     # 默认 claude
uitest-phone connect --agent codex
uitest-phone connect --agent gemini
uitest-phone connect --agent copilot

把「改配置文件 + 装 Skill」合成一步:只改自己那一项,注释、顺序与其它 server 的格式原样保留;已经正确时什么都不写;文件解析失败就拒绝并报出文件名与偏移,不替人重写。

Agent设置文件Skill 目录
claude(默认)~/.claude.json($CLAUDE_CONFIG_DIR)~/.claude/skills、~/.agents/skills
codex~/.codex/config.toml($CODEX_HOME)~/.agents/skills
gemini~/.gemini/settings.json~/.agents/skills
copilot~/.copilot/mcp-config.json($COPILOT_HOME)~/.agents/skills

写入的入口是当前 node 加本包的绝对路径:从 Dock 或开始菜单启动的 Agent 看不到终端的 PATH,裸命令可能解析不到、或被别的程序顶替。只有当本包只存在于 npx 缓存(npm 会清掉它)时,才改写成 npx -y uitest-sdk@<version> mcp。MCP server 在会话开始时读取,接好之后要开新会话。

接管:人要用手机

uitest-phone hold       # 设备归人;Agent 命令 2 秒内以 lease_held(退出码 2)停下
uitest-phone handoff --reason "请登录后继续"   # Agent 主动请人接手,停在 handoff
uitest-phone resume     # 交还给 Agent

hold 把租约写成 "held by a person" 后立即退出。它不按进程存活判断,所以不会自己过期,也没有 Agent 命令能把它抢回去;resume 只释放 hold,别的任务自己的租约不碰——只有取走设备的那个任务能干净地结束。

它可以抢走正在运行的任务,包括整个进程只持一次租约的 uitest-phone mcp 会话。任务不会在动作中途被打断,而是在下一条命令前发现租约没了,返回 lease_held;hold 会打印它从哪个任务手里接过了设备。resume 之后同一个 Agent 会话在下一条命令自动重新取得设备,不需要重启。

Agent 也能反向发起:handoff --reason "请登录后继续" 把手机交给人,立即返回 handoff(退出码 2)。原因写在租约里,之后每个拿到 lease_held 的命令都会重复它;人做完后 resume,同一个 Agent 会话下一条命令继续。MCP 里对应工具是 uitest_handoff,参数 reason 必填——没有原因,人打开手机时只能猜 Agent 要什么。

设备侧没有「人在用手机」的可靠信号:UI 事件流会关掉会话、能把 agent daemon 卡死,而且合成点击也会被当成手指,分不出真假。所以接管是人的明确声明,这也正好是 Agent 唯一能遵守的形式。

7. 投流与录制

const cast = await dev.createCast({
  mode: "stream",   // "stream" | "record"
  frameRate: 60,    // 15 | 30 | 60 | 120,默认 30
  scale: 2,         // 1..5 整数缩小因子,默认 1
});
for await (const chunk of cast.stream()) {
  // H.264: { data, pts, flags, isKeyFrame };MJPEG: { data, pts }
  if (chunk.isKeyFrame) { /* 从这里开始解码 */ }
}
await cast.requestIDRFrame(); // H.264 专用;MJPEG 上是 no-op
await cast.dispose();

CastOptions

字段类型默认说明
modestream / record必填record 只支持 arm64(需要 casting 扩展)
frameRate15|30|60|12030扩展只认这四个值,其它值会被设备侧静默重置
scale1..51整数缩小因子;越界抛 EBADARG
outputPathstring—record 必填,dispose() 时把 MP4 拉到这里
bitRatenumber8_000_000编码码率
iFrameIntervalnumber2000关键帧间隔
screenIdnumber0屏幕编号
transportgrpc / wsgrpcgrpc 用内置 6.8 扩展;ws 用 7.0 WebSocket 扩展(需 wsExtension)
wsExtensionstring—ws 必填:本地 7.0 .so 路径,按文件名推到设备
portnumber5000ws 专用:设备侧监听端口,每个 daemon 一个
socketNamestring内部常量grpc 专用:覆盖抽象 socket 名,同机跑多个投流的方式
durationMsnumber—record:到点自动停止(等价于调 dispose():关 muxer、拉回文件、杀 daemon)

CastClient

成员说明
castKind"h264" 或 "mjpeg",显式选择的结果
stream()AsyncIterable,逐块给出 H.264 / JPEG
requestIDRFrame()请求一个关键帧(H.264);MJPEG 无操作
dispose()结束投流;录制模式下关闭 muxer 并拉回文件

选择规则

7.0 WebSocket 传输0.6.0

const cast = await dev.createCast({
  mode: "stream",
  transport: "ws",
  wsExtension: "./libscrcpy_server_unix_7.0-20260930.z.so",
  port: 5000,
});

SDK 不打包 7.0 扩展,需要自己提供 .so。它按文件名推到 /data/local/tmp/<name> 并用 --extension-name <name> 加载,所以能和内置的 6.8 扩展同时存在、互不覆盖。

真机实测:启动 0.9–1.3 s,首帧 82–137 ms,requestIDR 7–9 ms,-frameRate 30 下 20.8–23.2 fps。与 6.8 持平,优势是客户端零 gRPC 依赖。

一个客户端独占一个 daemon。实测 stop 是进程级的:任一客户端 stop,同一 daemon 上另一路立刻停止出流;stop 后监听 socket 关闭,新客户端连不上。并发投流靠多个 port,不是一个 daemon 多客户端。

投屏与实时检查:uitest-sdk live0.7.0

npx uitest-sdk live                    # http://127.0.0.1:7000/
npx uitest-sdk live --privacy off      # 初始不遮凭据
npx uitest-sdk live --no-layout        # 只投屏

一个页面里同时有画面和布局:右边是当前屏的节点表,点节点(或点画面上的框)就复制它的 ref、角色、标签与中心坐标,编号和 tap --ref 共用。解码在浏览器里完成:H.264 走 WebCodecs VideoDecoder(服务端把 Annex-B 转 AVCC 并生成 avcC),MJPEG 走 createImageBitmap,没有 MSE、没有 fMP4 重封装。

隐私开关默认打开:密码框与验证码在节点表和画面上都被遮住。关掉后服务端用 redact: false 重新读布局,原文才出现 —— 遮罩在读的时候完成,不是事后擦除。多个页面同时连着时,只要有一个还开着遮罩,共享的屏幕模型就保持遮罩。

状态机是 idle → starting → live → reconnecting → stopping → stopped,失败从任意状态进入 failed 并按 0.5/1/2/4/5 s 退避重启;页面重载有 5 s 宽限期,不重开投流。背压在 socket 写队列超过 1 MB 时丢增量帧并请求 IDR,页面侧 decodeQueueSize > 4 时同样丢。

页头两个按钮:Shot 存截图,Record 录 MP4。截图走 Session.observe({ out }),所以遮罩规则和节点表是同一套——文字里藏起来的密码在像素里也是灰块。录屏另起一个 record daemon(gRPC 用自己的 socket,WebSocket 用端口 +1),画面不会停;同一时间只有一个录屏,页面关掉时正在录的那个会被停掉并写盘。实测录制期间画面保持 29–30 fps。

真机 1216×2688 / 30 fps 实测:首帧约 3.1 s(含 daemon 启动),画面持续变化时页面绘制 18.5 fps,帧间隔中位 33 ms、p90 55 ms,每帧平均 11.6 KB。

这条链路每一步的耗时都量过:服务端把 Annex-B 转 AVCC 并封装成帧是 12 µs/帧(关键帧 43 µs),浏览器解码 1216×2688 是 1.57 ms/帧(硬解)到 2.46 ms/帧(强制软解),画布绘制 0.07 ms。30 fps 的 33 ms 预算里只用掉约 5%,瓶颈在设备侧编码器。和 hscrcpy / HOScrcpy / HarmonyMirror 的逐行对比见首页,真实页面截图见首页「实拍」。

import { LiveServer } from "uitest-sdk";

const server = await LiveServer.start({
  port: 0,
  privacy: true,
  graceMs: 5000,
  layoutMs: 250,
  source: {
    createCast: () => dev.createCast({ mode: "stream", frameRate: 30 }),
    readScreen: (redact) => {
      session.reader.builder.setRedact(redact);
      return session.reader.read();
    },
  },
});
console.log(server.port);   // 页面地址
await server.close();

录制

const cast = await dev.createCast({ mode: "record", frameRate: 30, outputPath: "out.mp4" });
// 让画面动起来:静止画面不会产生新帧
await cast.dispose(); // 关闭 muxer → 等待设备写完 → 拉回 out.mp4

设备侧文件路径写死在扩展里(/data/local/tmp/mytest.mp4),不可改。编码器是起停驱动的:createCast 返回时已经在录,dispose() 后才完成。

8. UI 树与窗口

整屏 UI 树

const tree = await dev.agent.captureLayout(); // { attributes, children }
console.log(tree.attributes.bundleName, tree.children.length);

窗口截图

设备不提供窗口级截图,SDK 的做法是「整屏采集 + 按节点 bounds 裁剪」:

const jpeg = await dev.agent.cropToWindow({ bundleName: "com.huawei.hmos.settings" });
const jpeg2 = await dev.agent.cropToWindow({ windowId: 12, scale: 1 });

找不到窗口抛 ENOWINDOW,节点没有可解析的 bounds 抛 ENOBOUNDS。

窗口级 UI 树

agent.captureLayout() 永远返回整屏;要按窗口过滤,用 cli.dumpLayout(一次 shell + pull):

const tree = await dev.cli.dumpLayout({ windowId: 12 });
const tree2 = await dev.cli.dumpLayout({ bundleName: "com.huawei.hmos.settings", withFontAttrs: true });

找节点并点击

import { parseBounds } from "uitest-sdk";

const tree = await dev.agent.captureLayout();
const target = find(tree, (n) => n.attributes.text === "设置");
const bounds = target && parseBounds(target.attributes.bounds ?? "");
if (bounds) {
  await dev.agent.click(bounds.x + bounds.width / 2, bounds.y + bounds.height / 2);
}

布局检查与节点高亮

Session.inspect 读一次屏幕、截一帧,把每个元素的 bounds 画成方框并编号 —— 编号就是 ref,可以直接 tap --ref 3。框线按角色着色,被脱敏的元素先涂灰再画框;html 另存一个单文件面板(图片 base64 内嵌,悬停节点表高亮对应的框)。面板长什么样:首页「实拍」。

const r = await session.inspect({ out: "layout.jpg", html: "layout.html" });
// r.nodes: [{ index, ref, role, label, rect, state, masked }, ...]

不走 Session 时可以直接组合组件:Screenshot.mark(boxes) 是绘制原语,inspectScreen(screen, shot) 返回 { nodes, annotated, plain },renderPanel(screen, inspection) 生成 HTML。纯客户端,建立在已有的 captureLayout 与 JPEG 截图上。

9. 完整 hypium API0.5.0

设备侧的 hypium 驱动公开 118 个方法(OHOSDriver 106 + 兼容层 12)。dev.hypium 把它们逐个映射成 TypeScript 方法,参数按设备实际行为定,并逐条标注真机状态:

import { On } from "uitest-sdk";

await dev.hypium.click(On.text("设置"));
await dev.hypium.waitForComponent(On.text("WLAN"), { timeoutMs: 3000 });
await dev.hypium.swipe("up", { distance: 40 });
console.log(await dev.hypium.getComponentProperty(On.type("Button"), "bounds"));

全部 118 个方法、参数说明、示例与调用路径图在 完整 API 页。

从 0.5.0 起提供;0.4.0 及更早的版本没有 dev.hypium。

10. 工具类与导出

文件、配置与帧率

const entries = await dev.files.list("/data/local/tmp"); // [{ name, path, size, isDir, mode, mtime }]
await dev.files.mkdir("/data/local/tmp/demo dir", { parents: true });
await dev.files.push("./clip.mp4", "/data/local/tmp/demo dir/clip.mp4");
await dev.files.remove("/data/local/tmp/demo dir", { recursive: true });

const cfg = await CastConfig.load(castConfigPath(stateDir));
await cfg.set({ scale: 2, frameRate: 30, transport: "ws" });
const cast = await dev.createCast({ ...cfg.toCastOptions("stream"), wsExtension: "./lib.so" });

const meter = new FpsMeter({ windowMs: 2000 });
for await (const chunk of cast.stream()) meter.add();

Files.remove 拒绝空路径与 /;readText 默认上限 1 MiB。CastConfig 不接管 createCast,合并是显式的;load 忽略手改坏的键,set 对非法值抛 EBADARG。FpsMeter 按帧间隔计算,MJPEG 与 H.264 都能用。

导出说明
parseBounds("[x1,y1][x2,y2]")解析成 { x, y, width, height },格式不对返回 null
cropRect(inner, outer)求交集矩形;无交集返回零矩形
FrameDemux把「一行 JSON + 裸 JPEG」的混合流拆开
SerialQueue串行队列,run(fn) 保证同一时刻只有一个请求在途
HdcRunnerhdc 封装:shell、push、pull、fportAdd/Remove、listTargets
CliRunner窗口级 dumpLayout
isBusyException(msg)判断是不是「全局锁被占用」
MODULE_IDcom.ohos.devicetest.hypiumApiHelper
CASTING_EXTENSIONlibscreen_casting.z.so
resolveCastingExtension(abi, dir)该 ABI 的 casting 扩展路径,没有返回 null
loadScrcpyService()加载 scrcpy.proto 的 gRPC service 构造器
H264CastClient / MjpegCastClient低层客户端;正常用 dev.createCast()
Files设备文件封装(dev.files):list / stat / mkdir / remove / move / push / pull / readText
CastConfig / castConfigPath()投流默认值的 JSON 持久化(<state-dir>/cast.json)
FpsMeter客户端帧率统计:add() / stats() / reset()
inspectScreen() / renderPanel()布局检查:叠框、编号、生成 HTML 面板
Session一个任务看一台设备:租约、策略、ref 表、trace
ScreenReader / ScreenBuilder读屏与渲染;renderDiff / renderFull 生成 CLI 打印的那份文本
Components / Gestures / AppManager设备侧控件操作、手势、应用与窗口管理
HypiumDriver / HYPIIUM_CATALOGhypium 全部 118 个方法的封装,以及它们的状态清单
Gesture宿主侧手势构造器:start / moveTo / pause
Policy / Approvals / Lease标签策略、一次性或记住的审批、每设备租约
TraceRecorder逐步 JSONL trace 与 HTML 报告
CommandRunner / COMMANDS命令层;CLI 与 MCP 共用同一张表
McpServer / toolDefinitionsstdio JSON-RPC 服务与工具定义
DevicePool多设备连接池
installSkill() / skillFiles()随包 Skill 的安装
doctor() / deviceTagOf(id)能力探测;设备序列号的 8 位哈希
VERSION从 package.json 读出的版本号

11. 错误码

所有错误继承 UitestError,带 code 与可选 cause。

类典型 code触发条件
DeviceNotConnectedErrorENODEVICE / ENOHDC / EHDC / EDISPOSED没有设备、找不到 hdc、hdc 命令失败、Device 已 dispose
ExtensionMissingErrorENOEXT / ENOCAST本地没有对应 ABI 的 agent.so;x86_64 上请求录制
DaemonStartErrorENODAEMON / EPORT / ENOSOCKET / ENORECORDdaemon 拉不起来、端口耗尽、投流 socket 没出现、录制文件没出现
AgentProtocolErrorEPROTO / ETIMEDOUT / EBADJSON / ENOWINDOW / ENOBOUNDS / EBADARG设备返回异常、请求超时、输出不是 JSON、找不到窗口/边界、参数非法
AgentBusyErrorEBUSY全局锁被其它进程占着且重试耗尽;或该设备已有采集流(立即失败)
AgentConnectionErrorECONN连接不可用、请求超时后连接被丢弃、关闭后继续调用

12. 并发与生命周期

13. 完整示例

点击、滑动与输入

const { width, height } = await dev.agent.getDisplaySize();
await dev.agent.click(width / 2, height / 2);
await dev.agent.swipe(width / 2, height * 0.8, width / 2, height * 0.2, { durationMs: 200 });
await dev.agent.inputText(width / 2, height * 0.5, "hello");

只截一个应用窗口

const jpeg = await dev.agent.cropToWindow({ bundleName: "com.huawei.hmos.settings" });

投流并解码

const cast = await dev.createCast({ mode: "stream", frameRate: 30 });
try {
  for await (const chunk of cast.stream()) {
    if ("isKeyFrame" in chunk && chunk.isKeyFrame) {
      // H.264 Annex-B:从这里开始送解码器
    }
  }
} finally {
  await cast.dispose();
}

录制 10 秒

const cast = await dev.createCast({ mode: "record", frameRate: 30, outputPath: "demo.mp4" });
await new Promise((r) => setTimeout(r, 10_000));
await cast.dispose();

多设备并行

const ids = ["<device-a>", "<device-b>"];
const devices = await Promise.all(ids.map((deviceId) => Device.connect({ deviceId })));
try {
  await Promise.all(devices.map((d) => d.agent.click(100, 100)));
} finally {
  await Promise.all(devices.map((d) => d.dispose()));
}

文档对应 uitest-sdk 0.8.0(2026-11-16)。数字与限制来自真机验收与 更新日志 中引用的报告。