# 自动化测试插件
# 插件说明
本插件，用于在HBuilderX内运行uni-app(x)自动化测试，支持H5、微信小程序、Android、iOS、Harmony自动化测试。
主要功能有：
- 初始化测试环境（创建测试配置文件、以及安装测试所需的环境）
- 运行测试 (运行项目下所有测试用例、运行某一个测试用例)
- 新建测试用例 （uni-app(x) pages页面，右键菜单【新建测试用例】）
- 查看历史测试报告 （HBuilderX顶部运行菜单）
# 测试注意事项
- 本插件支持
uni-app (x) 普通项目和uniapp-cli项目。uniapp-cli项目，运行自动化测试，需要在当前项目下安装自动化测试依赖。 - Windows电脑不支持运行测试到
iOS平台。 - MacOS电脑，运行测试到iOS平台，仅支持
iOS模拟器，不支持iOS真机（备注：iOS模拟器，需要电脑装安装XCode）。 - 运行测试到H5，仅支持
Chrome、Firefox、MacOS Safari浏览器，不支持其它浏览器。 - node: 当本机未安装node时，将使用HBuilderX
内置node运行测试。反之，本机安装了node，则使用本机的node。 - 运行测试到微信小程序，必须在manifest.json内，配置微信小程序 appid。如果微信开发者工具无法成功打开项目，首次请手动打开。
# 插件安装
如下图所示，在插件市场，进入插件详情页，点击【导入插件】，会自动拉起本地安装的HBuilderX。
特别注意：插件安装，依赖HBuilderX 终端插件。
# 测试环境安装
插件依赖：
- H5、微信、ios、android自动化测试依赖
puppeteer、adbkit、node-simctl、jest、playwright，运行插件时，如果未安装此依赖，将会弹窗自动安装。 注意：本插件0.0.3版本及以下，node: 当本机未安装node时，将使用HBuilderX内置的node运行测试。反之，本机安装了node，则使用本机的node。注意：本插件0.0.4+版本，新增配置项 支持自定义设置使用何种node版本进行uni-app(x)编译
特别注意：
- uni-app(x)普通项目，需要通过插件
hbuilderx-for-uniapp-test来安装测试环境。 - uniapp-cli项目，只需在项目下安装相关测试依赖即可。详情
# 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
# 创建测试用例
uni-app(x)项目，pages页面，右键菜单，创建测试用例
# 测试运行
创建测试用例之后，选中项目，右键菜单【运行uni-app自动化测试】，选择运行平台，即可开始运行测试。
注意：如果要运行指定的测试用例，请在项目管理器选中要运行的用例，右键菜单【运行当前测试用例】
# 测试平台说明
- Windows电脑不支持运行测试到
iOS手机 - MacOSX电脑，仅支持运行测试到
iOS模拟器，不支持ios真机。 - 运行测试到H5，仅支持
Chrome、Firefox、MacOS Safari浏览器，不支持其它浏览器。
# 选择测试平台
如下图所示，运行测试时，支持选择对应平台。
# 选择设备
如果无法获取到设备信息，请参考
# 插件配置
点击菜单【设置】【插件配置】，找到hbuilderx-for-uniapp-test项，即可看到设置项。
如上图
- 支持自定义测试报告路径。
- 自动修改jest.config.js文件中的testMatch，默认为
true。去掉勾选后，将不再自动修改testMatch。 - 插件0.0.4+版本，新增配置项 支持自定义设置使用何种node版本进行uni-app编译。即您可以选择使用HBuilderX
内置的Node、还是使用操作系统安装的Node进行uni-app编译。
# 如何编写测试用例
uni-app(x)自动化测试，使用了业内常见的jest测试库。
- uni-app(x)项目，pages目录下，右键菜单【创建测试用例】，选择模板。
- 测试用例文件名，必须为xxx.test.js
- 测试用例编写，请遵循jest规范。
# jest用例解析
下面将使用一个最简单的示例，来讲解测试用例的组成。
- describe 表示一组用例, decribe会形成一个作用域
- it 测试函数
- test 测试函数，类似it
- expect 匹配器。 使用文档
# 求和测试
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');
});
});
扩展：如上测试代码中，使用了beforeAll函数，它用于在所有测试之前执行。了解jest更多钩子函数
# Setup and Teardown
通常在编写测试时，您需要在测试运行之前进行一些设置工作，并且在测试运行之后需要进行一些完成工作。可以使用Jest的钩子函数来解决这个问题.
jest中有4个钩子函数
- beforeAll：所有测试之前执行
- afterAll：所有测试执行完之后
- beforeEach：每个测试实例之前执行
- afterEach：每个测试实例完成之后执行
文档扩展: jest setup-teardown
# 钩子函数的执行顺序
用下列代码，我们来查看一下函数执行顺序
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
# 内置Jest代码块
为了更快速的编写测试用例，本插件内置了jest部分代码块
| prefix | 代码块 |
|---|---|
| describe | describe('', () => {}); |
| test | test('', () => {}); |
| ta | test('', async () => {await}); |
| beforeAll | beforeAll(() => {}); |
| afterEach | afterEach(() => {}); |
| afterAll | afterAll(() => {}); |
| beforeAll | beforeAll(() => {}); |
# env.js
提醒：下面关于env.js的介绍，大部分情况下，自动化测试插件会自动修改，无需您手动调整。如果不确定，请勿修改。
env.js是对jest.config.js文件testEnvironmentOptions节点的抽离和扩充。- 测试项目下测试配置文件env.js, 自动化测试插件, 会根据运行平台，自动修改此文件, 比如会自动填充设备ID、基座路径。
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": {
// ....
},
"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": ""
}
}
}
}
# env.js 设置自定义基座
如果您需要运行自定义基座，需要将is-custom-runtime设置为true，并需要填写平台节点下的appid、package、executablePath
配置is-custom-runtime字段后，hbuilderx uni-app自动化测试插件，将不会再自动修改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"
}
}
}
}
# env.js UNI_TEST_CUSTOM_ENV
提示：大部分场景下，您不会用到UNI_TEST_CUSTOM_ENV。修改请慎重。
下面将对UNI_TEST_CUSTOM_ENV做介绍。
自动化测试插件 1.9.0版本新增UNI_TEST_CUSTOM_ENV, 用于读取自定义环境变量，并传递给uniapp自动化测试框架命令行。后期会随时扩充新的key。
{
"UNI_TEST_CUSTOM_ENV": {
// APPID 用于测试自定义基座
"UNI_TEST_BASE_APPID": "__UNI__xxxxxxxx",
// 基座包名 用于测试自定义基座
"UNI_TEST_BASE_PACKAGE_NAME": "io.xxx.xxx"
}
}
# 多个HBuilderX时，如何共用一个测试依赖？
场景：电脑上安装了HBuilderX 正式版、Dev、Alpha版本，每个程序plugins目录都重新安装一遍测试依赖？答案：不需要。
解决方案：
- 进入HBuilderX安装目录，将plugins目录下的hbuilderx-for-uniapp-test-lib目录，拷贝到电脑其它目录。
- 拷贝后，在命令行进入
上面的拷贝目录下，执行npm install - 打开HBuilderX菜单【设置】【源码视图】，增加配置项:
{
"hbuilderx-for-uniapp-test.customTestEnvironmentDependencyDir" : "自定义的测试依赖node_modules路径，路径必须以node_modules结尾"
}
