openharmony-testing-apis（openharmony 测试 API）

OpenHarmony 测试 API

概述

OpenHarmony 提供四个测试框架模块，用于全面的应用程序测试：

• @ohos.app.ability.abilityDelegatorRegistry (API 9+) - 测试框架入口点，提供 AbilityDelegator 和 AbilityDelegatorArgs
• @ohos.application.testRunner (API 8+) - 用于实现自定义测试运行器的基础测试框架
• @ohos.UiTest (API 8+) - UI 自动化测试，用于模拟用户交互
• @ohos.test.PerfTest (API 20+) - 白盒性能测试，用于指标收集

重要提示：所有测试 API 只能在测试上下文（JsUnit、UiTest）中使用。不支持并发调用。

各框架使用场景

digraph framework_choice {
    "需要测试？" [shape=diamond];
    "性能指标？" [shape=diamond];
    "UI 交互？" [shape=diamond];
    "自定义运行器？" [shape=diamond];
    "Ability 生命周期？" [shape=diamond];

    "PerfTest" [shape=box];
    "UiTest" [shape=box];
    "TestRunner" [shape=box];
    "AbilityDelegatorRegistry" [shape=box];

    "需要测试？" -> "性能指标？" [label="是"];
    "性能指标？" -> "PerfTest" [label="是"];
    "性能指标？" -> "UI 交互？" [label="否"];
    "UI 交互？" -> "UiTest" [label="是"];
    "UI 交互？" -> "自定义运行器？" [label="否"];
    "自定义运行器？" -> "TestRunner" [label="是"];
    "自定义运行器？" -> "Ability 生命周期？" [label="否"];
    "Ability 生命周期？" -> "AbilityDelegatorRegistry" [label="是"];
}

快速参考

模块概述

AbilityDelegatorRegistry

使用场景：需要启动 Ability、监控 Ability 生命周期状态或访问测试参数。

import { abilityDelegatorRegistry } from '@kit.TestKit';

// 获取 delegator
let delegator = abilityDelegatorRegistry.getAbilityDelegator();

// 获取测试参数
let args = abilityDelegatorRegistry.getArguments();

核心能力：启动 Ability、添加 AbilityMonitor 监听生命周期、执行 Shell 命令、等待 Ability。

详见：@ability-delegator-registry.md 获取完整 API 参考。

TestRunner

使用场景：需要实现自定义测试运行器，包含特定的环境设置或测试执行逻辑。

import { TestRunner } from '@kit.TestKit';

export default class UserTestRunner implements TestRunner {
  onPrepare() {
    console.info('触发 onPrepare');
  }

  onRun() {
    console.info('触发 onRun');
  }
}

核心方法：onPrepare() - 设置测试环境，onRun() - 执行测试用例。

详见：@test-runner.md 获取完整 API 参考。

UiTest

使用场景：需要自动化 UI 测试 - 模拟点击、滑动、文本输入或验证组件属性。

import { Driver, ON, Component } from '@kit.TestKit';

// 创建 driver
let driver = Driver.create();

// 查找组件并交互
let button = await driver.find(ON.id('submitBtn'));
await button.click();

核心类：

• Driver - 入口类，查找组件、注入按键、截图
• ON - 组件匹配（按 text、id、type、clickable 等）
• Component - 表示 UI 元素，提供点击、输入、滚动操作
• UiWindow - 窗口操作（拖动、调整大小、获取属性）

注意：API 9+ 使用 ON、Component、Driver。API 8 使用 BY、UiComponent、UiDriver（已废弃）。

详见：@uitest.md 获取完整 API 参考。

PerfTest

使用场景：需要测量代码性能 - 执行时间、CPU 使用率、内存、应用启动延迟、页面切换时间或列表滚动 FPS。

import { PerfTest, PerfMetric, PerfTestStrategy } from '@kit.TestKit';

let actionCode = async (finish: Callback<boolean>) => {
  // 要测试的代码
  finish(true);
};

let strategy: PerfTestStrategy = {
  metrics: [PerfMetric.DURATION, PerfMetric.CPU_USAGE],
  actionCode: actionCode,
  iterations: 10
};

let perfTest = PerfTest.create(strategy);
await perfTest.run();
let result = perfTest.getMeasureResult(PerfMetric.DURATION);
console.info(`平均耗时: ${result.average}ms`);

可用指标：

• DURATION - 代码执行时间（毫秒）
• CPU_LOAD - 进程 CPU 负载（%）
• CPU_USAGE - 进程 CPU 使用率（%）
• MEMORY_RSS - 物理内存（含共享库）（KB）
• MEMORY_PSS - 物理内存（不含共享库）（KB）
• APP_START_RESPONSE_TIME - 应用启动响应延迟（毫秒）
• APP_START_COMPLETE_TIME - 应用启动完成延迟（毫秒）
• PAGE_SWITCH_COMPLETE_TIME - 页面切换完成延迟（毫秒）
• LIST_SWIPE_FPS - 列表滚动帧率（fps）

详见：@perftest.md 获取完整 API 参考。

导入方式

// AbilityDelegatorRegistry
import { abilityDelegatorRegistry } from '@kit.TestKit';

// TestRunner
import { TestRunner } from '@kit.TestKit';

// UiTest（推荐用于 API 9+）
import { Driver, ON, Component, UiWindow, MatchPattern } from '@kit.TestKit';

// PerfTest
import { PerfTest, PerfMetric, PerfTestStrategy, PerfMeasureResult } from '@kit.TestKit';

常见错误

API 版本支持摘要