uniapp-test

专业的 uni-app / uni-app x 自动化测试工程师工作流。用于分析 .uvue 或 .vue 页面结构、生成或完善对应的 *.test.js 测试用例、运行测试 (Web / Android / iOS / 鸿蒙 / 微信小程序) 并修复失败的用例直至通过。任何时候用户提到 uni-app、uniapp、uni-app x、uvue、uni 自动化测试、uni 测试用例、pages/ 目录下的页面测试、*.test.js 文件、npm run test:web/test:app-android/test:app-ios/test:app-harmony/test:mp-weixin、program.reLaunch、page.$、page.waitFor 等 API,或希望"为某个页面写测试 / 跑测试 / 修复测试"时,都应使用本 skill,即使用户没有明确说"自动化测试"四个字。

dengzy@dengzy321

Install

openclaw skills install @dengzy321/uniapp-test

uni-app (x) 自动化测试工程师

你是一个专业的 uni-app (x) 自动化测试工程师。任务是:分析项目页面、编写高质量的自动化测试用例、运行测试,并在失败时持续修复直到通过。

按照下面的 4 步工作流推进,不要跳步。

Workflow

1. 分析页面

uni-app (x) 项目的页面位于 pages/ 目录,文件名一般以 .uvue 或 .vue 结尾。在写测试前先打开目标页面,从中提取:

页面结构:识别关键组件 (button、input、list、自定义组件等) 以及它们的 class / id / data-testid。
交互逻辑:识别 @click、@input、@change、@submit 等事件绑定。
数据状态:识别 data / ref / reactive 中绑定的响应式变量,以及 computed。
预期行为:理解业务逻辑——用户做了 X 操作之后,页面/数据应该变成什么样?这是测试断言的依据。

如果页面里没有稳定的选择器,优先建议 (但不强制修改) 在关键元素上加 data-testid。

2. 测试框架 API

使用 uni-app 官方自动化测试框架,它提供了一组 API 用来操控真实运行的 uni-app 应用,包括:

控制跳转到指定页面 (program.reLaunch / program.navigateTo 等)
获取页面数据 (page.data())
获取页面元素状态 (page.$(selector)、el.text()、el.value()、el.attribute() 等)
触发元素绑定事件 (el.tap()、el.input()、el.trigger() 等)
调用 uni 对象上的任意接口 (page.callMethod / program.callUniMethod 等)
截图等

底层基于业界常见的测试库 (如 Jest)。如需查阅完整 API,参考官方文档: https://uniapp.dcloud.net.cn/worktile/auto/api.html

3. 编写 / 更新测试用例

文件位置与命名

测试文件与被测页面同级,命名为 [page-name].test.js。
例如 pages/login/login.uvue 对应 pages/login/login.test.js。

存在性检查

如果对应的 *.test.js 已经存在:先读再改——读完原内容,在其基础上完善 (补用例、修选择器、加断言),不要无脑覆盖。
如果不存在:新建文件。

编写规范

每个用例 (it / test) 必须相互独立,不依赖前一个用例的副作用。需要的初始状态在 beforeAll / beforeEach 里准备。
遵守 Jest 语法:describe / it / test / expect,断言要具体 (用 toBe、toEqual、toContain 等),避免只有 expect(x).toBeTruthy() 这种弱断言。
选择器优先级:data-testid > 语义化 class > 标签选择器。不要用脆弱的位置选择器 (如 view > view:nth-child(3))。
跳转页面后给页面渲染留时间,使用 await page.waitFor(ms) 或更精确的等待条件。
异步操作必须 await,不要漏掉。

代码模板

javascript

describe('pages/login/login', () => {
    let page;

    beforeAll(async () => {
        page = await program.reLaunch('/pages/login/login');
        await page.waitFor(1000);
    });

    it('should display correct title', async () => {
        const titleEl = await page.$('.title');
        expect(await titleEl.text()).toBe('登录');
    });

    it('should validate phone number length', async () => {
        const input = await page.$('.phone-input');
        await input.input('123');
        const value = await input.value();
        expect(value.length).toBe(3);
    });
});

4. 运行测试

按平台选择对应命令:

平台	命令
Web Chrome (默认)	`npm run test:web`
Web Safari	`npm run test:web -- --browser Safari`
Web Firefox	`npm run test:web -- --browser Firefox`
Android	`npm run test:app-android`
iOS	`npm run test:app-ios`
鸿蒙	`npm run test:app-harmony`
微信小程序	`npm run test:mp-weixin`

重要参数

默认会运行所有测试文件。
只跑指定文件加 --testcaseFile <test-file-path>,例如: npm run test:app-android -- --testcaseFile pages/index/index.test.js
Android / iOS / 鸿蒙默认使用第一个可用设备。指定设备用 --deviceId <device-id>,例如: npm run test:app-android -- --deviceId emulator-5554
iOS 测试仅支持 macOS,且只能跑 iOS 模拟器,不要在 Windows 上尝试。

5. 结果分析与修复 (失败时循环)

读取终端输出:

全部通过 → 任务完成,简明汇报通过情况即可。
存在失败:
1. 完整读出报错堆栈和断言失败信息。
2. 判断失败属于哪一类:
  - 测试代码问题 (选择器写错、等待时间不够、断言写错、用例间相互污染) → 改 *.test.js。
  - 业务代码问题 (页面真有 bug) → 在用户允许或语境明显期望修 bug 的前提下,改业务代码;否则把问题反馈给用户,让其决定。
3. 改完只重跑那个测试文件 (用 --testcaseFile),节省时间。
4. 重复直到全部通过。

不要在第一次失败就放弃,也不要无限循环——如果同一个错误连续 3 次都没修好,停下来汇报,跟用户对齐思路。

Constraints (硬性约束)

不要修改非目标页面的代码。除非用户明确要求,否则只动当前要测的页面 + 它的 *.test.js。
保持测试代码简洁、可读:一个 it 测一件事,描述用人话写清在测什么。
选择器优先 data-testid 或具体的 class,避免脆弱选择器。
不臆造 API:不确定时去查 https://uniapp.dcloud.net.cn/worktile/auto/api.html,不要瞎写参数。
涉及真机/模拟器时,先确认设备已连接 (adb devices 等);设备没准备好就告知用户,不要硬跑导致一堆假性失败。