CPTF - Cross-Platform Test Framework

业界唯一支持 HarmonyOS 的跨端自动化测试框架

跨端自动化测试框架，专为跨平台应用设计。

为什么选择 CPTF？

特性	CPTF	其他框架
HarmonyOS 支持	✅ 原生支持	❌ 不支持
性能指标采集	✅ 19 个性能指标（17 内置 + 2 插件，真实 FPS）	⚠️ 2-3 种（模拟 FPS）
稳定性测试	✅ SmartMonkey + ANR + 白屏检测 + 内存泄漏 + 崩溃恢复	❌ 需自行搭建
跨平台对比	✅ HarmonyOS vs Android	⚠️ 需自行搭建
用例编写	✅ 声明式（减少 70-90%代码）	⚠️ 命令式

核心亮点：

• 唯一性：业界唯一支持 HarmonyOS 自动化测试
• 精准性：真实 FPS 采集（RenderService fpsCount + hitchs），非模拟数据
• 完整性：19 个性能指标（17 内置 + 2 插件）+ 3 个稳定性检测器 + 完整稳定性测试套件（SmartMonkey/白屏/内存泄漏/ANR/崩溃恢复）
• 简洁性：声明式框架 @Test/@Step，代码量减少 70-90%
• 专业性：五层架构设计（src/ 目录即五层），职责分离清晰，易于扩展

业界最佳实践

React Native for OpenHarmony (RNOH) 基于 CPTF 框架完成全量功能、性能、稳定性测试，是目前业界最大的 HarmonyOS 跨端测试实践：

• 功能测试：覆盖 Switch、Button、RefreshControl 等核心组件的全量属性跨平台一致性验证
• 性能测试：19 个指标采集（17 内置 + 2 插件）+ Warmup 迭代 + 阈值告警 + HTML 趋势图
• 稳定性测试：SmartMonkey + ANR 检测 + 白屏检测 + 内存泄漏 + 崩溃自动恢复
• 跨平台对比：HarmonyOS vs Android UI 结构 4 维对比（属性/样式/位置/层级）

测试用例工程：RNOH Test App

框架源码双托管：GitCode（主）· AtomGit（镜像，packages/framework/package.json repository）

平台支持

平台	状态
HarmonyOS	✅ 已支持
Android	✅ 已支持
iOS	🚧 开发中

项目结构

cptf/
├── packages/framework/    # 框架层（npm 包 @cptf/framework）
│   └── src/               # 五层架构源码（对外概览三组合并：base+infrastructure=基础设施、capability+orchestration=调度、system=系统）
│       ├── base/           # 基础层（类型/配置/工具/设备管理/端口管理）
│       ├── infrastructure/ # 基础设施层（扫描/索引/设备发现）
│       ├── system/         # 系统层（ISystem接口+平台实现+Agent客户端）
│       ├── capability/     # 能力层（UI/断言/对比/采集）
│       ├── orchestration/  # 编排层（运行器/测试类/报告）
│       ├── cli/            # CLI命令
│       └── __tests__/      # 框架单元测试

快速开始

安装与构建

cd packages/framework
pnpm install
pnpm build

CLI 命令

cptf devices              # 列出设备
cptf devices -p harmony   # 列出HarmonyOS设备
cptf scan                 # 扫描测试用例
cptf index                # 生成测试用例索引文件
cptf run                  # 执行所有测试（自动平台选择）
cptf run -p harmony       # HarmonyOS测试
cptf run -m performance   # 指定模块测试
cptf run -C Button        # 按分类测试
cptf run -t all-metrics-performance # 指定用例测试
cptf run --driver native  # 驱动模式（native灰盒 | external黑盒 | auto，默认auto：优先native失败降级external）
cptf run --strategy by-module  # 多设备分配策略（round-robin | by-module | by-category | by-case | single）
cptf run --timeout 600    # 全局超时(秒)，超时后生成部分报告
cptf run --include-unsupported  # 包含无法自动化的用例（默认跳过并从通过率分母排除）
cptf run --force-baseline # 强制覆盖已有视觉基线（覆盖前自动备份到 .history/）
cptf compare              # 跨平台对比测试
cptf compare --driver native  # 对比测试同样支持驱动模式
cptf index                # 生成测试用例索引（test-cases-index.ts）
cptf install              # 安装应用到连接设备（--atx 同时装 Android ATX Agent）
cptf init                 # 初始化配置
cptf check-env            # 检查环境依赖
cptf template performance -n my-test  # 生成测试模板

# 或全局安装后使用
# pnpm link --global  # 可选：全局安装后直接使用 cptf 命令
cptf devices
cptf run -p harmony

配置设备

编辑被测应用的 cptf.config.json：

{
  "platforms": {
    "harmony": {
      "toolPath": "hdc",
      "bundleId": "com.tester.RNTester",
      "appPath": "harmony/entry/build/default/outputs/default/entry-default-signed.hap",
      "devices": [{ "id": "设备ID", "screenWidth": 1280, "screenHeight": 2832 }]
    },
    "android": {
      "toolPath": "adb",
      "bundleId": "com.tester.RNTester",
      "appPath": "android/app/build/outputs/apk/release/app-release.apk",
      "devices": [{ "id": "设备ID", "screenWidth": 1080, "screenHeight": 2400 }]
    }
  }
}

核心功能

多平台支持

• HarmonyOS (hdc)
• Android (adb)
• iOS (WDA + xctrace，模拟器 xcrun simctl)

UI 自动化

• 元素查找 (testId, text)
• 点击操作 (坐标、元素)
• 滑动操作 (scroll, fling)
• 等待机制 (waitFor)

性能采集

• FPS 监控（真实 FPS：RenderService fpsCount + hitchs）
• CPU 使用率
• 19 个性能指标（17 内置 + 2 插件）+ 3 个稳定性检测器 + HTML 趋势图

稳定性测试

• SmartMonkey（权重衰减+覆盖率引导+安全区域过滤）
• ANR 自动检测
• 白屏检测（零外部依赖）
• 内存泄漏检测（线性回归+高/中置信度）
• 崩溃自动恢复（forceStop→launchApp→ensureInScene）
• 场景漂移三层防护

视觉对比

• 截图采集
• 图片对比
• 属性检查

报告生成

• HTML 格式
• Markdown 格式
• JSON 格式
• 性能告警

命令速查

cptf devices              # 列出设备
cptf devices -p harmony   # 列出平台设备
cptf scan                 # 扫描用例
cptf index                # 生成测试索引文件
cptf run                  # 执行所有测试（自动平台选择）
cptf run -p harmony       # HarmonyOS测试
cptf run -m performance   # 指定模块
cptf run -C Button        # 指定分类
cptf run -t calendar-perf-declarative # 指定用例
cptf run --driver native  # 驱动模式 native|external|auto（默认auto）
cptf run --strategy by-category  # 多设备分配策略
cptf run --timeout 600    # 全局超时(秒)，超时生成部分报告
cptf run --include-unsupported  # 包含不可自动化用例
cptf run -p harmony --rn-version rn84 --update-baseline  # 按 RN 版本分段建立/验证视觉基线
cptf run -p harmony --rn-version rn84 --force-baseline   # 强制覆盖视觉基线（自动备份旧基线）
cptf compare              # 跨平台对比测试
cptf compare --driver native  # 对比测试同样支持驱动模式
cptf index                # 生成测试用例索引
cptf install              # 安装应用到设备
cptf init                 # 初始化配置文件
cptf check-env            # 检查环境依赖
cptf template <module> -n <name>  # 生成测试用例模板

文档

文档	说明
架构总览	框架架构、源码目录、依赖规则
架构优势	五层架构、三平台加速、性能优势
能力规格	性能指标、API 规格、数据结构
用户指南	安装、配置、CLI、API 使用
声明式测试指南	@Test/@Step 装饰器、TestConfig 详解
命令式测试指南	命令式测试编写
Expect 断言指南	声明式断言使用
UI 对比指南	跨平台 UI 结构对比
扩展开发	新增平台、能力、报告生成
框架对比分析	与 Jest/Appium/Cypress 等对比
稳定性对比分析	7 维度对标业界稳定性方案
npm 包说明	CLI 命令、快速开始、架构设计

License

MIT