我是兰瓶Coding，一枚刚踏入鸿蒙领域的转型小白，原是移动开发中级，如下是我学习笔记《零基础学鸿蒙》，若对你所有帮助，还请不吝啬的给个大大的赞~

前言

直话直说：没有测试护航的发布，就是把用户当小白鼠。想把质量“内建进流程”，我们要把单元测试（快、准）、UI自动化（稳、全）、再到CI/CD（持续、可追溯）一口气打通。本文用TestKit（Hypium/UiTest）、Mock 框架、DevEco 命令行 + 常见 CI 服务做落地示例，给你一套能直接抄的工程化打法。😎

目录你先收好

• 01｜单元测试：结构化用例、Mock 打桩、可观测产出
• 02｜UI 自动化：控件定位、交互脚本、稳定性策略
• 03｜CI/CD 流水线：命令行构建、签名安装、云端并行跑测
• 04｜最佳实践与踩坑清单
• 05｜一键上手模板（代码片段可直接搬）

01｜单元测试：快、准、可追溯

1）测试框架与目录形态

HarmonyOS 的自动化测试框架 arkxtest 同时支持单元测试（JsUnit/Hypium）与UI 测试（UiTest），并约定两类用例目录：

• Instrument Test：放在 ohosTest，跑在真机/模拟器（支持单测 + UI 测）。
• Local Test：放在 test，本地运行（仅单测）。(华为开发者官网)

DevEco Studio 创建工程后即可新建两类用例；同样的能力也能走命令行在 CI 环境执行。(华为开发者官网)

2）最小单测样例（Hypium）

// ohosTest/ets/example/calculator.test.ets
import { describe, it, expect } from '@ohos/hypium';
import { add } from '../../main/ets/common/Calc';

export default function calculatorSuite() {
  describe('Calc.add', () => {
    it('add two positives', 0, () => {
      expect(add(2, 3)).assertEqual(5);
    });
    it('add negative', 0, () => {
      expect(add(-1, 1)).assertEqual(0);
    });
  });
}

• describe/it/expect 与前端同学很熟的语义一致；执行与报告由 单元测试框架统一调度。(华为开发者官网)

3）Mock 两板斧：MockKit 与 import mock

当被测代码依赖系统服务/复杂外设时，直接跑很痛苦。官方提供两种 Mock 能力：

• 用 Hypium/hamock 的 MockKit/when/afterReturn 给方法打桩；
• 用 import mock 在 mock-config.json5 中把某个 module 映射到你的 Mock 实现（连系统 API 都能替身）。(华为开发者官网)

// 方式A：MockKit 方法桩
import { describe, it, expect, MockKit, when } from '@ohos/hypium';
import { SmsSender } from '../../main/ets/service/SmsSender';

export default function smsSuite() {
  describe('SmsSender', () => {
    it('send ok', 0, () => {
      const mocker = new MockKit();
      const sender = new SmsSender();
      const fn = mocker.mockFunc(sender, sender.send);
      when(fn)('10086', 'hi').afterReturn(true); // 约定入参与返回
      expect(sender.send('10086', 'hi')).assertTrue();
    });
  });
}

// 方式B：import mock（src/mock/mock-config.json5）
{
  "@ohos.enterprise.bluetoothManager": {
    "source": "src/mock/bluetooth_manager.mock.ets"
  }
}

// src/mock/bluetooth_manager.mock.ets（示例）
export default {
  getBluetoothInfo: () => ({ state: 2 /* STATE_ON */ })
}

两种方式Instrument / Local Test 都可用（Stage 工程 API 11+）。Mock 既减依赖、又提高可重复性。(华为开发者官网)

02｜UI 自动化：让回归像按播放键

1）UiTest 能力地图

• 查找与操作控件：通过文本、ID、层级等定位，再执行 click, setText, scrollTo 等；
• 录制/控件树/截图：测试框架还提供 shell 能力抓控件树、录操作、注入 UI 行为，辅助编写脚本。(华为开发者官网)

2）最小 UI 测试脚本（ArkTS）

// ohosTest/ets/ui/login.ui.test.ets
import { describe, it, expect } from '@ohos/hypium';
import { byText, byId, findComponent, click, setText, waitFor } from '@ohos/uittest';

export default function loginFlow() {
  describe('Login UI', () => {
    it('should login successfully', 0, async () => {
      await waitFor(byText('登录')).toAppear(5000);
      await setText(byId('username'), 'tester');
      await setText(byId('password'), '123456');
      await click(byText('登录'));
      await waitFor(byText('欢迎回来')).toAppear(5000);
      const hello = await findComponent(byText('欢迎回来'));
      expect(hello).not().assertUndefined();
    });
  });
}

UiTest 脚本运行仍由单测底座调度，报告也统一汇总；控件树/录制/注入操作的命令方式同样由官方文档覆盖。(华为开发者官网)

3）稳定性三件套

• 显式等待：用 waitFor(...).toAppear(timeout)，别写“魔法 sleep”。
• 可靠定位：优先 byId，退而 byText，最后才考虑层级路径。
• 数据隔离：每条用例自备测试账号/干净状态，避免“测试互相污染”。

ArkUI 调试定位、Inspector/控件树配合使用，能快速收集可定位的 ID 与路径（社区实践不少，适合结合 UiTest 来回切）。(掘金)

---

03｜CI/CD 流水线：把质量“自动化、制度化”

1）为什么先从“命令行”入手？

因为 CI 的一切本质上都是“在干净机器上跑命令”。HarmonyOS 提供命令行构建与安装的官方路径：

• Hvigor 命令行构建 HAP/APP；
• 签名、安装/运行、hdc 配置都有官方脚本可复用；
• 还提供无网络流水线搭建说明。(华为开发者官网)

关键节点（CI 主机要做）

• JDK 17 环境、hdc、hvigor、ohpm 就绪；
• 拉取 HarmonyOS SDK 的 commandline tools；
• 设备连接（或云端模拟器）稳定可用。(华为开发者官网)

2）本地到 CI 的“脚本化骨架”

# 1) 安装依赖
ohpm install

# 2) 构建（Debug）
hvigor assembleDebug

# 3) 安装到设备（示例）
hdc shell bm install -p ./entry/build/default/outputs/default/entry-default-default.hap

# 4) 运行 Instrument 测试（arkxtest 提供命令）
hdc shell aa start -a ohos.test.uitest   # 拉起 UiTest 进程（示意）
# 或用测试框架提供的脚本/命令集合按用例集执行

官方“命令行构建/搭建流水线”文档给到了环境准备、签名、构建、安装的逐步脚本与示例，直接搬到 CI 即可。(华为开发者官网)

3）GitHub Actions 示意（你也可以换成 Jenkins/GitLab）

name: HarmonyOS CI
on:
  push: { branches: [ "main" ] }
  pull_request: { branches: [ "main" ] }
jobs:
  build-test:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - name: Setup JDK 17
        uses: actions/setup-java@v4
        with: { distribution: 'temurin', java-version: '17' }

      - name: Prepare HarmonyOS CLI
        run: |
          # 假设你已缓存或下载 commandline-tools
          unzip commandline-tools-linux-x64-5.x.x.zip -d $HOME/hmos-cli
          echo "$HOME/hmos-cli/bin" >> $GITHUB_PATH

      - name: Install deps
        run: ohpm install

      - name: Build Debug
        run: hvigor assembleDebug

      - name: Start emulator & run tests
        run: |
          # 启动模拟器或连接云真机，随后执行用例
          # 以下为示意，实际按你的设备池命令写
          hdc list targets
          # 运行单测/UI测命令（取决于你如何封装测试脚本）
          # 约定：测试框架生成 JUnit/XML 结果
      - name: Archive reports
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: ./reports/**

你也可以参考社区文章里的 GitHub Actions/Jenkins Pipeline 案例，把 构建→签名→安装→执行测试→产出报告 串起来。(CSDN博客)

4）报告与门禁

• 产出：把单测/UI 测的结果统一落成 JUnit XML/HTML；
• 门禁：设定 失败即阻断合并，并对关键模块设置覆盖率阈值；
• 追溯：报告归档 + 变更号/构建号关联，问题可定位到提交。

---

04｜最佳实践与“别翻车”清单

用例设计

• 单测优先“纯函数 + 小颗粒”；副作用分离、用 Mock 兜依赖。
• UI 测“场景编排”：登录、下单、离线、异常重试等跨页链路要覆盖。
• 金丝雀：核心流程每日定时跑；增量 PR 只跑受影响模块+冒烟用例。

稳定性

• 控件定位优先 byId；结合控件树/录制辅助脚本生成定位代码。(华为开发者官网)
• 避免 sleep，用 waitFor(...).toAppear(timeout)。
• 测试数据自清理（账号、订单、缓存），每条用例独立。

速度

• 单测本地秒级跑完；UI 用例控制在5~10 分钟/套，长链路切分并行。
• CI 上拆成“快速验证（Build+单测）”与“完整回归（含 UI）”两级任务。

可维护

• 用例与页面解耦：Page Object 封装常用操作（登录页输入/提交、列表翻页、下拉刷新…）。
• 断言聚合：失败时输出上下文信息（账号、请求号、最后截图路径）。

---

05｜一键上手模板（可直接改名服用）

A. 单测 + Mock 套件骨架

// ohosTest/ets/suites/app.suite.ets
import calculatorSuite from './example/calculator.test';
import smsSuite from './example/sms.mock.test';
export default function appSuite() {
  calculatorSuite();
  smsSuite();
}

B. UI 测 Page Object + 用例

// ohosTest/ets/pages/Login.po.ets
import { byId, byText, click, setText, waitFor } from '@ohos/uittest';
export class LoginPage {
  async appear() { await waitFor(byText('登录')).toAppear(5000); }
  async login(u: string, p: string) {
    await setText(byId('username'), u);
    await setText(byId('password'), p);
    await click(byText('登录'));
  }
}

// ohosTest/ets/ui/login.flow.test.ets
import { describe, it, expect, beforeEach } from '@ohos/hypium';
import { LoginPage } from '../pages/Login.po';

export default function loginFlowSuite() {
  describe('login-flow', () => {
    let page: LoginPage;
    beforeEach(() => page = new LoginPage());
    it('happy path', 0, async () => {
      await page.appear();
      await page.login('tester', '123456');
      // ... 断言欢迎页
    });
  });
}

C. CI 构建脚本（Linux，本地调通再上 CI）

#!/usr/bin/env bash
set -e
ohpm install
hvigor assembleDebug
# 如需签名：按官方文档准备签名文件并调用签名脚本
# 安装与测试命令因设备池/框架封装而异，这里只给框架

参考与延伸（官方优先）

• 自动化测试框架（arkxtest）：单测/UiTest 原理、脚本、shell 能力（控件树、录制、注入）。(华为开发者官网)
• 命令行构建/CI 搭建：JDK17、hvigor、hdc、签名与示例脚本；含无网络流水线说明。(华为开发者官网)
• Mock 能力（MockKit / import mock）：Instrument & Local Test 适用，API 11+ Stage 工程。(华为开发者官网)
• OpenHarmony 测试框架仓库：arkxtest 源码与说明。(Gitee)
• （拓展）社区上手与 UI 定位/Inspector 实战分享，可作为落地参考。(掘金)

---

…

(未完待续)