企业官网建设流程全解析

• 示例工程
• 前端
• 移动开发
• 跨平台

uni-app 自动化测试插件（插件市场 ID：5708）将 uni-app(x) 自动化测试的完整链路——测试环境安装、测试用例创建、多端测试运行、历史报告查看——收拢进 HBuilderX 的右键菜单与运行菜单。本文以该插件的官方文档为骨架，结合当前 uni-app 开源仓库中的真实配置（src/env.js、src/jest.config.js）与真实测试用例，完整讲解插件的安装、配置、用例编写与多平台运行，让读者在 HBuilderX 内即可对 H5、微信小程序、Android、iOS、Harmony 一次运行自动化测试，并能为后续接入命令行与持续集成打下基础。

插件定位与核心能力

本插件用于在 HBuilderX 内运行 uni-app(x) 自动化测试，支持H5、微信小程序、Android、iOS、Harmony五个平台的自动化测试，主要提供四项能力：

• 初始化测试环境：创建测试配置文件（env.js、jest.config.js），并安装测试所需的环境依赖；
• 运行测试：一键运行项目下全部测试用例，也可只运行某一个指定的测试用例；
• 新建测试用例：在 uni-app(x) 的 pages 页面文件上，通过右键菜单【新建测试用例】快速生成测试骨架；
• 查看历史测试报告：通过 HBuilderX 顶部运行菜单查看历史测试报告。

从技术底座上看，uni-app(x) 自动化测试基于业内常见的jest测试库，测试代码中通过 uni-automator 自动注入的全局对象program来操控应用（跳转页面、获取元素、触发点击、调用 uni 接口、截图等），关于program、page、element的完整方法清单可参考 uni-app(x) 自动化测试 API 文档。因此，插件的本质是把这套基于 jest + uni-automator 的测试体系，以可视化菜单的方式封装进 HBuilderX，降低上手成本。

测试注意事项：平台与运行环境的硬性约束

在开始使用前，先明确插件的平台与运行环境约束（以下内容来自官方文档，务必逐条核对）：

1. 本插件支持uni-app(x) 普通项目和uniapp-cli 项目。其中 uniapp-cli 项目运行自动化测试，需要在当前项目下安装自动化测试依赖。
2. Windows 电脑不支持运行测试到 iOS 平台。
3. MacOS 电脑运行测试到 iOS 平台，仅支持iOS 模拟器，不支持 iOS 真机（注意：iOS 模拟器需要电脑安装 XCode）。
4. 运行测试到 H5，仅支持Chrome、Firefox、MacOS Safari浏览器，不支持其它浏览器。
5. Node 版本选择：当本机未安装 node 时，将使用 HBuilderX 内置 node 运行测试；反之，本机安装了 node，则使用本机的 node。
6. 运行测试到微信小程序，必须在 manifest.json 内配置微信小程序 appid。如果微信开发者工具无法成功打开项目，首次请手动打开。

其中第 5 条在插件 0.0.4+ 版本进一步演进为可配置项（见下文「插件配置」），允许开发者自行选择使用 HBuilderX 内置 Node 还是操作系统安装的 Node 进行 uni-app 编译。

插件安装

在插件市场进入插件详情页，点击【导入插件】，会自动拉起本地安装的 HBuilderX 完成导入。

特别注意：插件安装依赖 HBuilderX 的终端插件，请确保终端插件已就绪。

安装完成后，插件同时提供了两类使用入口：HBuilderX 图形界面内的右键菜单/运行菜单（本文主体），以及命令行入口（插件 4.1.0 版本起支持被 HBuilderX CLI 调用，用于 CI 集成，详见文末「进阶：命令行与持续集成」）。

测试环境安装

插件依赖清单：

• H5、微信、iOS、Android 自动化测试依赖puppeteer、adbkit、node-simctl、jest、playwright。运行插件时，如果本机未安装这些依赖，会弹窗提示自动安装。
• 其中playwright依赖包体积较大（约 1G 左右），安装速度受网络、操作系统环境影响，可能较慢，需要耐心等待。

不同项目类型的环境安装方式不同，分为两种情况：

uni-app(x) 普通项目

uni-app(x) 普通项目，在项目管理器中选中项目，右键菜单点击【初始化测试环境】（或直接【运行测试】）时，如果检测到相关依赖未安装，会自动安装。

同时，安装环境依赖时，如果检测到项目下不存在测试配置文件env.js和 jest.config.js，插件会自动创建这两个测试配置文件，无需手动搭建。

uniapp-cli 项目

uniapp-cli 项目的自动化测试运行将使用项目下的依赖库，需要在命令行进入项目目录，手动安装依赖：

npm install --save cross-env puppeteer adbkit node-simctl jest playwright @playwright/test

安装完成后，同样在项目管理器选中项目，即可通过右键菜单运行测试。更完整的 CLI 项目测试工程配置（含package.json中test:h5、test:android等 npm script 的编写）可参考 uniapp-cli 项目自动化测试教程。

创建测试用例

在 uni-app(x) 项目中，定位到 pages 目录下的页面文件，右键菜单选择【创建测试用例】，即可基于当前页面自动生成对应的测试用例文件。

插件生成/要求的测试用例需遵循以下规范（详见下文「如何编写测试用例」）：

• 测试用例文件名必须为xxx.test.js；
• 测试用例文件通常与页面放在同一级目录，便于维护与定位；
• 测试代码遵循 jest 规范编写。

在 uni-app 官方示例仓库中，测试用例正是这样组织的：如 animation-frame.test.js 与页面pages/API/animation-frame/animation-frame同目录，App.test.js 也遵循同样的约定。仓库src/pages目录下已积累了 200+ 个*.test.js文件，可作为编写用例的丰富参考。

测试运行

创建测试用例之后，选中项目，右键菜单点击【运行uni-app自动化测试】，选择运行平台，即可开始运行测试。

• 运行全部用例：在项目管理器选中项目，右键【运行uni-app自动化测试】；
• 运行指定用例：如果要运行某个指定的测试用例，请在项目管理器选中该用例文件，右键菜单点击【运行当前测试用例】。

测试平台说明

• Windows 电脑不支持运行测试到 iOS 手机；
• MacOSX 电脑仅支持运行测试到iOS 模拟器，不支持 iOS 真机；
• 运行测试到 H5，仅支持 Chrome、Firefox、MacOS Safari 浏览器，不支持其它浏览器。

选择测试平台

运行测试时，插件会弹出平台选择列表，可按需选择对应平台（H5 / 微信小程序 / Android / iOS / Harmony）。

选择设备

运行到 App 类平台时，需要选择设备（真机或模拟器）。如果无法获取到设备信息，请参考 HBuilderX 运行到 App 的常见问题文档（运行菜单【运行到手机或模拟器】的 FAQ 章节），排查 adb 驱动、模拟器连接等基础环境问题。

插件配置

点击 HBuilderX 菜单【设置】→【插件配置】，找到hbuilderx-for-uniapp-test项，即可看到设置项，主要包含：

• 自定义测试报告路径：支持自定义测试报告的输出目录，便于归档与后续查阅历史测试报告。
• 自动修改 jest.config.js 中的 testMatch：默认为true。勾选状态下，插件会自动将jest.config.js中的testMatch调整为匹配项目测试用例的规则；去掉勾选后，插件将不再自动修改testMatch，此时需开发者自行在 jest.config.js 中维护正确的testMatch。例如当前仓库src项目的配置为testMatch: ['<rootDir>/pages/**/*test.[jt]s?(x)']。
• 自定义 Node 版本（插件 0.0.4+ 新增）：支持自定义设置使用何种 node 版本进行 uni-app(x) 编译，即可以选择使用 HBuilderX内置的 Node、还是使用操作系统安装的 Node。

其中第二点与仓库中的 jest.config.js 直接相关：插件自动修改的正是该文件中的testMatch节点。仓库实测配置还包含setupFilesAfterEnv（加载jest-setup.js完成环境初始化）与testSequencer（自定义用例执行顺序），说明在插件自动生成的基础上，配置文件依然保留了充分的定制空间。

如何编写测试用例

uni-app(x) 自动化测试使用了业内常见的 jest 测试库，编写规范与 jest 一致。

编写步骤概括为：

1. 在 uni-app(x) 项目 pages 目录下，右键菜单【创建测试用例】，选择模板生成骨架；
2. 测试用例文件名必须为xxx.test.js；
3. 按 jest 规范编写断言逻辑。

jest 用例基础：describe / it / test / expect

• describe：表示一组用例，会形成一个作用域；
• it：测试函数；
• test：测试函数，用法类似it；
• expect：匹配器，用于断言（如toBe、toEqual等）。

最简单的求和测试示例：

# 求和测试 function sum(a, b) { return a + b; }; describe("sum test", () => { it('adds 1 + 2 to equal 3', () => { expect(sum(1, 2)).toBe(3); }); test('adds 1 + 1 to equal 3', () => { expect(sum(1, 1)).toBe(3); }); })

uni-app(x) 页面用例示例

以 uni-app(x)【默认模板】index 页面为例，编写测试用例检查index.vue页面标题是否为Hello：

describe('test title', () => { let page; beforeAll(async () => { page = await program.currentPage(); await page.waitFor(3000); }); it('check page title', async () => { const el = await page.$('.title'); const titleText = await el.text(); expect(titleText).toEqual('Hello'); }); });

代码中program是 uni-automator 自动注入的全局对象，page.$('.title')通过选择器（id、class、元素选择器）获取页面元素，el.text()获取元素文本，最后用expect(...).toEqual(...)断言。上述代码还使用了beforeAll钩子函数（在所有测试之前执行），关于钩子函数的更多细节见下一节。

仓库真实用例的进阶写法

当前仓库的测试用例在页面示例基础上做了更多工程化处理，非常值得参考：

• 平台条件分支：animation-frame.test.js 通过process.env.uniTestPlatformInfo判断当前测试平台，在小程序平台跳过不适用用例；App.test.js 进一步结合UNI_APP_X_DOM2等环境变量区分渲染模式，实现同一套用例在 Android / iOS / Harmony / H5 上差异化断言；
• 调用页面方法与读取页面数据：page.callMethod('startRequestAnimationFrame')调用页面暴露的方法，page.data('data')读取页面渲染数据，再断言数据变化，这是对「功能正确性」的典型验证方式；
• 页面跳转：program.reLaunch('/pages/index/index')重置页面栈并返回 page 对象，配合page.waitFor('view')等待元素出现，替代了盲目的固定时长等待，更加稳健。

Setup 与 Teardown：四个钩子函数

通常在编写测试时，需要在测试运行之前进行一些设置工作，并在测试运行之后进行一些收尾工作，Jest 的钩子函数正是为解决这个问题而设计。Jest 共有 4 个钩子函数：

• beforeAll：所有测试之前执行；
• afterAll：所有测试执行完之后执行；
• beforeEach：每个测试实例之前执行；
• afterEach：每个测试实例完成之后执行。

钩子函数执行顺序

用下面的代码可以直观查看函数的执行顺序：

describe('test Run Sequence', () => { beforeAll(() => { console.log('1 - beforeAll'); }); afterAll(() => { console.log('1 - afterAll'); }); beforeEach(() => { console.log('1 - beforeEach'); }); afterEach(() => { console.log('1 - afterEach'); }); test('test', () => { console.log('1 - test') }); });

运行结果：

test Run Sequence ✓ test (4 ms) console.log 1 - beforeAll console.log 1 - beforeEach console.log 1 - test console.log 1 - afterEach console.log 1 - afterAll Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 total Time: 0.454 s

可以看到执行顺序为：beforeAll→beforeEach→test→afterEach→afterAll。这套顺序保证了「全局初始化一次、每个用例独立隔离」的测试语义，是编写稳定用例的基础。

内置 Jest 代码块

为了更快速地编写测试用例，插件内置了部分 Jest 代码块（在 HBuilderX 编辑器中输入 prefix 即可联想补全）：

| prefix | 代码块 | | -- | -- | | describe |describe('', () => {});| | test |test('', () => {});| | ta |test('', async () => {await});| | beforeAll |beforeAll(() => {});| | beforeEach |beforeEach(() => {});| | afterEach |afterEach(() => {});| | afterAll |afterAll(() => {});|

env.js：测试配置文件的抽离与扩充

提醒：下面关于 env.js 的介绍，大部分情况下自动化测试插件会自动修改，无需手动调整；如果不确定，请勿修改。

env.js需要理解两个关键点：

1. env.js是对jest.config.js文件testEnvironmentOptions节点的抽离和扩充。也就是说，env.js 中的内容等价于写在jest.config.js的testEnvironmentOptions节点下，二者是同一套配置的两种存放形式（完整的testEnvironmentOptions形态可参考 快速开始文档 中的 jest.config.js 示例）；
2. 测试项目下的env.js，自动化测试插件会根据运行平台自动修改此文件，比如自动填充设备 ID、基座路径。

以下为 env.js 的完整配置模板（与仓库 src/env.js 内容一致，可直接对照参考）：

module.exports = { // is-custom-runtime = true，自动化测试插件将不会自动修改env.js中配置的基座executablePath，executablePath可以配置自定义基座路径 "is-custom-runtime": false, "UNI_TEST_CUSTOM_ENV": { // 以下3个配置项用于定义以App-WebView方式运行的H5页面地址，方便自动化测试App-WebView场景 // "UNI_AUTOMATOR_APP_WEBVIEW": "true", // "UNI_WEB_SERVICE_URL": "http://xxx.com/xxx.html", // "UNI_AUTOMATOR_APP_WEBVIEW_SRC": "http://xxx.com/xxx.html" }, "compile": true, "h5": { "options": { "headless": true }, "executablePath": "" }, "mp-weixin": { // ...微信开发者工具相关配置，如 port、account、launch、teardown、remote、executablePath 等 }, "app-plus": { "android": { "id": "", "executablePath": "" }, "version": "", "ios": { "id": "", "executablePath": "" }, "uni-app-x": { "version": "", "android": { "appid": "", //自定义基座测试需配置manifest.json中的appid "package": "", //自定义基座测试需配置包名 "id": "", "executablePath": "" // apk 目录或自定义调试基座包路径 }, "ios": { "appid": "", //自定义基座测试需配置manifest.json中的appid "package": "", //自定义基座测试需配置包名 "id": "", "executablePath": "" } } } }

配置项要点说明：

• is-custom-runtime：是否使用自定义基座（默认false）。设为true后，插件不再自动修改env.js中的基座路径，executablePath需自行配置为自定义基座路径；
• compile：是否在运行测试前编译项目（默认true）；
• h5.options.headless：H5 测试是否无头运行（默认true，不弹出浏览器窗口）；h5.executablePath：指定浏览器可执行文件路径；
• mp-weixin：微信小程序相关配置（端口默认 9420、是否主动拉起开发者工具、测试结束后断开还是关闭开发者工具、是否真机自动化等），完整字段说明同样可参考 jest.config.js 示例；
• app-plus.android / ios：App 端设备id与基座executablePath；
• app-plus["uni-app-x"].android / ios：uni-app x 的 App 端配置，其中appid与package仅在使用自定义基座测试时需要配置（appid 取 manifest.json 中的 appid，package 取包名）。

仓库中的 src/env.js 是一份已被实际填充的示例，其app-plus["uni-app-x"]节点配置了 HBuilderX-Dev 内置的模拟器 id（如emulator-5554）与基座路径（plugins/uniappx-launcher/base/android_base.apk、Pandora_simulator.app），可以看出 uni-app x 的 App 测试依赖 HBuilderX 自带的 uni-app x 启动器基座，这也解释了为什么 App 自动化测试需要安装 HBuilderX。

使用自定义基座测试

如果您需要运行自定义基座，需要将is-custom-runtime设置为true，并填写对应平台节点下的appid、package、executablePath。配置is-custom-runtime字段后，插件将不会再自动修改 env.js：

module.exports ={ "is-custom-runtime": true, "app-plus": { "uni-app-x": { "version": "", "android": { "id": "emulator-5584", "executablePath": "projects/hello-uni-ai-x/unpackage/debug/android_debug.apk", "appid": "", "package": "uni.app.UNIC5010321212A" } } } }

UNI_TEST_CUSTOM_ENV：自定义环境变量

提示：大部分场景下不会用到UNI_TEST_CUSTOM_ENV，修改请慎重。

自动化测试插件1.9.0 版本新增UNI_TEST_CUSTOM_ENV，用于读取自定义环境变量，并传递给 uni-app 自动化测试框架命令行，后期会随时扩充新的 key。目前可用 key 如下：

{ "UNI_TEST_CUSTOM_ENV": { // APPID 用于测试自定义基座 "UNI_TEST_BASE_APPID": "__UNI__xxxxxxxx", // 基座包名 用于测试自定义基座 "UNI_TEST_BASE_PACKAGE_NAME": "io.xxx.xxx" } }

其中UNI_TEST_BASE_APPID用于测试自定义基座时传递 APPID，UNI_TEST_BASE_PACKAGE_NAME用于传递基座包名。

多个 HBuilderX 版本共用一个测试依赖

场景：电脑上安装了 HBuilderX 正式版、Dev、Alpha 等多个版本，是否每个版本的 plugins 目录都要重新安装一遍测试依赖？答案：不需要。

解决方案：

1. 进入 HBuilderX 安装目录，将plugins目录下的hbuilderx-for-uniapp-test-lib目录，拷贝到电脑其它目录；
2. 拷贝后，在命令行进入上面的拷贝目录，执行npm install；
3. 打开 HBuilderX 菜单【设置】→【源码视图】，增加配置项：

{ "hbuilderx-for-uniapp-test.customTestEnvironmentDependencyDir" : "自定义的测试依赖node_modules路径，路径必须以node_modules结尾" }

配置完成后，所有版本的 HBuilderX 将共用同一份测试依赖，避免重复下载（尤其是体积较大的 playwright 依赖）。

进阶：命令行与持续集成

除了在 HBuilderX 图形界面内运行，插件4.1.0 版本起支持被 HBuilderX CLI 调用（即uniapp.test命令），可以在终端命令行运行 uni-app(x) 自动化测试到 Web、微信小程序、Android、iOS 和 Harmony，从而接入持续集成。基本用法为在 HBuilderX 安装目录下执行：

cli uniapp.test <platform> --project <ProjectPath>

支持web-chrome、web-safari、web-firefox、mp-weixin、app-android、app-ios-simulator、app-harmony等平台参数，以及--device_id、--testcaseFile等可选参数。运行前请先确保插件在 HBuilderX 内可以正常使用。完整的命令参数、示例与 npm scripts 集成方式，可参考 uniapp.test CLI 命令行工具文档。

结语与更多参考

通过 hbuilderx-for-uniapp-test 插件，uni-app(x) 开发者可以在 HBuilderX 内以「右键 + 选择平台」的极简方式，完成从测试环境搭建、用例生成、用例编写到多端运行、报告查看的完整闭环；配合 CLI 调用能力，同一套 jest 用例还可以无缝进入持续集成流水线，实现「研发提交源码 → CI 自动拉取 → 自动运行自动化测试」的推荐工作流。

继续深入阅读：

• uni-app(x) 自动化测试快速开始：测试工程目录规范、jest.config.js 完整配置与注意事项；
• uni-app(x) 自动化测试 API 文档：program、page、element全量方法与平台差异表；
• uniapp-cli 项目自动化测试教程：CLI 工程的依赖版本约束与各平台 npm script；
• 仓库实测用例：animation-frame.test.js、App.test.js、action-sheet.test.js，以及 src/pages 下 200+ 个*.test.js文件。

• 示例工程
• 前端
• 移动开发
• 跨平台