小程序自动化测试实战：minitest回归与CI流水线落地

手工回归一遍核心流程要四十多分钟，连着点三遍人就麻了，这是我当初决定在小程序项目里上自动化测试框架的直接原因。试过几套方案之后，我最后留在自用工具链里的是 minitest —— 一套面向小程序自动化测试的框架，底层依托开发者工具的自动化通信能力，上层补上了用例组织、断言、报告和失败重试。它解决的问题很具体：让"每次发版前把登录、下单、支付、退款这条主链路点一遍"这件事从人力变成脚本。这篇文章适合两类人看：一是手上已经有小程序项目、被重复回归折磨过的测试或开发；二是想搞清楚小程序自动化测试这条路到底怎么走、坑在哪的新手。我会把自己从零跑通到放进流水线的完整过程写清楚，包括那些文档里不会写、但排查起来能耗掉你一整天的细节。

1. 手工点一遍要四十分钟，我把回归交给了这套框架

1.1 小程序自动化测试和 Appium 那套根本不是一条路

很多人第一次接触小程序自动化测试，脑子里冒出来的还是 Appium 那一套逻辑：拿到控件树，按 id 或坐标定位，然后点击。这套思路在小程序里会撞墙。原因不难理解，小程序在开发者工具里运行时，渲染层和逻辑层是分离的，控件树并不以原生控件的形式暴露给外部驱动，你拿不到那种可以随便遍历的 UI 层级结构。

小程序自动化测试走的是另一条路：开发者工具本身开放了一个自动化端口，外部脚本通过通信协议连上去，拿到一个"小程序实例"的句柄，然后基于这个句柄去操作页面、查询元素、执行脚本、模拟接口返回。你可以把它理解成：不是从外面"戳"界面，而是站在工具的内部控制台里"指挥"界面。这个差异决定了后面所有的写法——定位用选择器而不是控件树，交互走封装好的方法而不是坐标点击，断言更多依赖数据状态而不是像素。

理解了这层，你就明白为什么小程序自动化测试的脚本普遍比原生 App 短，也为什么它的稳定性和工具版本强绑定。它不是模拟真人手指，它是在工具内部下指令，所以速度快、可控性强，但一旦工具行为变了，脚本就得跟着调。这是这条路的天生特性，接受它，后面很多"玄学问题"就都有解释了。

1.2 这套框架的组成：通信层、编排层、报告层

minitest 这类框架，我习惯按三层去理解，这个心智模型对排查问题非常有用。

第一层是通信层。它负责跟开发者工具建立连接、启动或关闭工具、持有小程序实例。所有的页面操作、元素查询、脚本执行，最终都从这里出去。这一层出问题的典型表现是连接超时、连接突然断开、工具进程残留。

第二层是编排层。它管的是用例怎么写、怎么组织、怎么串行或并行跑。断言库、钩子函数、用例分组、失败重试，都在这一层。这一层出问题的表现是：单条用例能跑，一起跑就挂；或者某条用例挂了之后，后面的全乱套。

第三层是报告层。截图、日志、用例通过率、耗时统计。这一层最容易被忽略，但它决定了自动化跑完之后你能不能在五分钟内定位到问题。我见过不少团队脚本写得挺好，报告只有一行"失败"，最后没人愿意看结果，整套东西就废了。

把这三层分清楚之后，你会发现自己排查问题的效率会明显提高：先判断现象属于哪一层，再往那个方向查，别一上来就怀疑选择器写错了。我早期最大的毛病就是所有问题都往"元素定位"上想，结果折腾半天发现是连接没有正常关闭，工具进程堆积导致后面全部连不上。

1.3 什么时候值得上，什么时候纯属自找麻烦

说点实在的，自动化测试不是所有项目都该上。我自己的判断标准是这样：

我自己的项目属于第一类：主链路稳定了大概两个月，发版节奏是两周一次，每次回归都要把登录、商品详情、下单、支付回调、退款这条线走一遍，还得在两种屏幕尺寸下各走一遍，一个人一上午就没了。上自动化之后，这套流程压缩到四分钟出头，而且是在我写代码的时候后台自己跑。

反过来说，我见过一个刚起步的项目，页面一天一个样，上面要求"先把自动化框架搭起来"，结果两周写了三十条用例，第三周全部重构。这不是框架的问题，是时机不对。脚本本质上是代码，代码就有维护成本，页面结构不稳定的时候，维护成本会吃掉全部收益。

还有一点要说清楚：自动化测试不替代手工测试。它替代的是"重复验证已知行为"，不是"发现未知问题"。探索性测试、边界体验、视觉走查，这些还是得人来。我把自动化定位成"发版前的守门员"，它能拦住回归缺陷，但拦不住设计缺陷和体验问题。

2. 跑通第一次连接：环境准备里被忽略的三个开关

2.1 开发者工具的服务端口与自动化开关

这是新手最容易卡住的地方，也是我踩的第一个坑。

开发者工具默认是不开放自动化端口的，你必须手动去设置里把"服务端口"打开。路径通常在工具的设置面板里，名字叫"安全设置"，里面有一项跟服务端口相关的开关。不开这个，你的脚本无论怎么写都会在连接阶段超时，而且报错信息往往很含糊，只说连不上，不会告诉你是开关没开。

第二个容易忽略的点是工具的登录状态。自动化启动工具时，如果工具没有处于已登录状态，可能会卡在登录页，脚本拿不到小程序实例。我的做法是：先手动打开工具、扫码登录一次、确认能正常打开项目，然后再让脚本去接管。有些 CI 环境里会预置登录态，这属于进阶操作，第一次跑通的时候不要折腾这个。

第三个是工具版本和框架版本的匹配。这一点我吃过亏。工具升级之后，自动化接口的某些行为会变，比如页面栈的返回内容、元素属性的读取方式。我现在的习惯是：在项目里记录一份"已验证可用"的工具版本号，升级工具之前先在本地跑一遍全量脚本，确认没问题再动。这个习惯救过我好几次，尤其是赶版本的时候。

提示：不要用"最新版"这个模糊描述去管理工具版本。写清楚具体版本号，并且把它写进团队文档，比什么都管用。

环境这块还有个小细节：如果你的工具安装路径里有空格或者中文，启动时可能会失败。我一般建议把工具装在纯英文路径下，能少一类玄学问题。这不是框架的锅，是子进程调用时的路径处理问题，但排查起来很浪费时间。

2.2 项目目录骨架与依赖安装

我自己的目录结构是这样的，跑通之后一直没改过：

project-root/ ├── tests/ │ ├── cases/ # 用例文件 │ ├── pages/ # 页面对象封装 │ ├── fixtures/ # 测试数据 │ └── setup.js # 全局启动与关闭 ├── reports/ # 报告输出目录 ├── screenshots/ # 失败截图 └── package.json

依赖安装部分没什么花活，一个测试运行器和框架本体就够了。我用的组合是 Jest 做用例组织和断言，加上框架提供的运行入口。装完之后记得检查一下 Node 版本，这个坑我踩过：Node 版本过低会导致一些异步写法的行为不一致，表现是用例偶发失败，而且失败得很随机，非常难查。我现在统一用 Node 18 以上的 LTS 版本，项目里加一个.nvmrc锁定版本，省得换机器又要重新调。

package.json里我一般配两个脚本：

{ "scripts": { "test": "jest --runInBand", "test:smoke": "jest --runInBand tests/cases/smoke" } }

--runInBand这个参数很关键，它让用例串行执行。因为自动化测试是共享一个工具实例的，并行跑同一个实例会互相干扰，表现为元素莫名其妙找不到、页面栈错乱。我早期为了"跑得快"开过并行，结果排查了两天才发现是这个原因。真正需要并行的时候，正确的做法是起多个工具实例，每个实例跑不同的用例集，这属于后期优化的范畴。

2.3 一次完整的启动、操作、关闭流程

先把最小闭环跑通，这件事比写一百条用例都重要。我的第一版脚本只做三件事：启动工具、打开首页、关闭工具。跑通了，后面的都是在这个骨架上加肉。

const automator = require('miniprogram-automator'); async function bootstrap() { const miniProgram = await automator.launch({ cliPath: '/path/to/devtools/cli', projectPath: '/path/to/your/miniprogram-project', timeout: 60000 }); return miniProgram; } async function shutdown(miniProgram) { if (miniProgram) { await miniProgram.close(); } } (async () => { let mp; try { mp = await bootstrap(); const page = await mp.reLaunch('/pages/index/index'); console.log('current page:', page.path); } finally { await shutdown(mp); } })();

这段代码里有三个细节值得说明。

cliPath指向的是开发者工具的命令行入口，不是工具主程序。不同系统下名字不一样，Mac 上通常是cli，Windows 上是cli.bat，具体位置在工具安装目录里。找错了会报"找不到命令"。

timeout我建议显式给一个比较大的值，默认值在慢机器上容易不够。第一次启动工具本来就慢，再加上项目编译时间，六十秒是相对稳妥的。

finally里关闭实例，这一点极其重要。我最早的脚本没写这个，跑挂了之后工具进程留在后台，跑十次就堆十个进程，内存吃满，后面全部启动失败。表现是"昨天还好好的，今天突然连不上"，非常迷惑。自从加了finally关闭，这类问题基本消失。

3. 元素定位：小程序自动化里最考验耐心的一段

3.1 选择器能力边界与跨组件查找

小程序自动化测试的定位主要靠选择器，支持的形式大致是 id、class 和标签名这几种基础写法，不支持完整的 XPath。这一点跟习惯了 Web 自动化的人预期不太一样，需要调整思路。

id 选择器最稳，优先级最高。我的做法是：凡是需要被脚本操作的元素，一律加一个语义明确的 id，命名上带上业务含义，比如login-submit、order-total。不要用自动生成的、带随机串的 id，那种东西改一次页面就失效了。

class 选择器能用但脆弱。一个 class 往往对应多个元素，你查出来的是一个集合，还得自己判断取哪个。而且样式重构的时候 class 会被改，脚本就跟着挂。我的经验是：class 只用来做"存在性检查"，比如判断某个状态样式有没有加上，不用来做点击定位。

跨自定义组件的查找是个专门的问题。小程序的自定义组件天然形成一层隔离，外部页面的选择器进不去组件内部。要穿透这层，需要用特殊的连接符写法，把外层组件选择器和内层元素选择器串起来。我最初不知道这一点，对着组件里的按钮找了一下午，$$返回空数组，日志里什么提示都没有。

// 穿透自定义组件查找内部元素 const innerBtn = await page.$('custom-dialog >>> .confirm-btn'); await innerBtn.tap();

这个>>>就是我说的连接符。它只能穿透一层，如果组件嵌套两层，就得写两段。实际项目里我尽量要求开发同学在关键交互元素上加 id，能避免大部分穿透查找，可维护性也好得多。

3.2 等待与重试：把固定 sleep 换掉

sleep(2000)这个写法我早期用得特别多，后来全删了。原因很朴素：它要么不够，要么浪费。

小程序有数据请求、有渲染延迟、有页面跳转动画，固定等待时间根本覆盖不了所有情况。网络慢的时候两秒不够，本地跑的时候两秒纯浪费。全量用例一百条，每条浪费一秒就是一百秒，这是实实在在的成本。

比较靠谱的做法是三层策略配合。

第一层，显式等待元素出现。框架一般提供了等待某个选择器出现的方法，给一个超时时间，出现就继续，超时就报错。

const btn = await page.waitFor('#login-submit', { timeout: 10000 }); await btn.tap();

第二层，等待页面切换完成。点击跳转之后，不要立刻去查新页面的元素，先拿到当前页面对象，确认路径变了，再往下走。

await page.waitFor(300); // 仅用于给跳转动画留时间，不作为主要等待手段 const newPage = await miniProgram.currentPage(); expect(newPage.path).toBe('pages/detail/index');

第三层，等待具体数据状态。有些元素是渲染出来了但数据还没填进去，这时候点击没反应，或者断言拿到空字符串。我的做法是等文本内容变成预期值再断言，而不是等元素存在。

await page.waitFor(async () => { const el = await page.$('#order-total'); const text = el ? await el.text() : ''; return text.includes('¥'); }, { timeout: 15000 });

这三层配合下来，我的用例从"跑十次挂三次"变成"跑二十次挂一次"，剩下那一次通常是环境问题，不是脚本问题。

3.3 输入、滑动与视口外元素处理

输入框的操作有个坑：直接设置值有时候不触发页面的绑定逻辑。框架提供的输入方法通常是模拟真实输入，会触发完整的事件链，这类方法更可靠。如果只是想快速填值、不关心事件，可以用另一种赋值方式，但要注意页面数据可能没更新，后续断言会失败。

我遇到过最典型的一次：脚本把手机号填进去了，界面上也看得见，但点"获取验证码"提示"请输入手机号"。原因是赋值方式绕过了输入事件，页面绑定的变量还是空的。换成模拟输入的方法就好了。这个坑我建议直接记住结论：表单类元素一律用模拟输入，别图快用赋值。

视口外元素是另一个高频问题。小程序的点击是真实点击，元素不在可视区域内，点了没反应也不报错。表现就是"脚本跑完了，什么都没发生"。解决办法是先滚动到元素位置再点。

await miniProgram.pageScrollTo(500); // 滚动到指定位置 const submit = await page.$('#submit-order'); await submit.tap();

更稳的做法是先拿到元素的位置信息，再滚动到那个位置：

const el = await page.$('#submit-order'); const offset = await el.offset(); await miniProgram.pageScrollTo(offset.top - 100); await el.tap();

减掉 100 是给顶部导航栏留空间，这个数值要按实际页面调。这点小细节听起来不起眼，但如果不做，元素刚好被导航栏挡住，点击就会打到导航栏上，非常难查——因为脚本不报错，页面就是不跳转。

4. 断言与用例结构：能跑起来只是第一步

4.1 页面对象模式的轻量落地

用例写到三十条左右的时候，你会发现一个问题：同一个页面上的元素定位代码，在十几条用例里重复出现。页面一改，就得改十几处。这时候就该上页面对象模式了。

我的做法比较轻，不搞复杂的继承体系，就是一个页面一个文件，导出一组方法。

// tests/pages/login.js class LoginPage { constructor(page) { this.page = page; } async inputPhone(phone) { const el = await this.page.waitFor('#phone-input'); await el.input(phone); } async inputCode(code) { const el = await this.page.waitFor('#code-input'); await el.input(code); } async submit() { const el = await this.page.waitFor('#login-submit'); await el.tap(); } } module.exports = LoginPage;

用例里就变成：

const login = new LoginPage(page); await login.inputPhone('13800000000'); await login.inputCode('123456'); await login.submit();

好处很直接：页面结构变了，改一个文件就行。而且用例读起来像业务描述，不是一堆选择器。我后来给团队其他人看用例，他们说"这个能看懂"——这就对了，用例首先得让人看懂，其次才是给机器跑。

要注意别把页面对象做太重。我见过把整个业务流程都塞进页面对象的写法，结果一个方法两百行，比不用还难维护。我的原则是：页面对象只负责"这个页面能做什么动作"，业务流程交给用例去编排。

4.2 异步陷阱与执行顺序

JavaScript 的异步在小程序自动化里特别容易出事。最常见的是忘了await。

// 错误写法：没有 await page.$('#login-submit'); element.tap(); // 正确写法 const btn = await page.$('#login-submit'); await btn.tap();

忘await的表现很诡异：脚本跑得飞快，全程不报错，但页面状态完全不对。因为你的操作都在排队，脚本已经结束的时候操作还没执行完。我刚开始写的时候被这个坑折磨了整整一个下午，还以为是框架不工作。

第二个容易出事的地方是用例之间的状态污染。自动化测试共享同一个工具实例，上一条用例登录了，下一条用例默认就是登录态。如果你的用例假设"每次从首页开始"，就得在beforeEach里做重置。

beforeEach(async () => { await miniProgram.reLaunch('/pages/index/index'); await miniProgram.evaluate(() => { // 清理本地存储中的登录态 wx.clearStorageSync(); }); });

reLaunch是重启到指定页面，会清空页面栈，比navigateTo更适合做重置。页面栈里堆太多页面，后面查当前页面的时候容易拿到错的，这也是个隐藏坑。

第三个异步陷阱是网络请求。点击按钮之后发起请求，请求回来之前页面就是空的。如果你在点击之后立刻断言，必然失败。这时候要用前面说的三层等待策略，等数据状态而不是等固定时间。

4.3 数据驱动与接口 mock 的配合

数据驱动能让用例数量成倍增长，而维护成本几乎不增加。我的做法是把测试数据放在单独的 fixtures 文件里，用例里循环。

const cases = [ { phone: '13800000001', expect: 'success' }, { phone: '13800000002', expect: 'success' }, { phone: '', expect: 'empty' } ]; cases.forEach(({ phone, expect: expected }) => { it(`手机号 ${phone || '空'} 登录校验`, async () => { const login = new LoginPage(page); await login.inputPhone(phone); await login.submit(); const tip = await page.waitFor('#tip', { timeout: 5000 }); const text = await tip.text(); if (expected === 'empty') { expect(text).toContain('请输入手机号'); } }); });

比数据驱动更有价值的是接口 mock。框架提供了临时替换内置接口返回值的能力，把网络请求直接挡掉，返回预设数据。这个能力在小程序自动化测试里非常关键，原因有两个。

一是稳定性。真实接口会超时、会限流、会返回意外数据，这些都不是你要测的东西，但会让脚本挂掉。mock 掉之后，用例只验证前端逻辑，稳定性提升非常明显。

二是覆盖边界。你想测"接口返回空列表时页面显示什么"，真实环境很难构造，mock 一行代码就行。

await miniProgram.mockWxMethod('request', (options) => { if (options.url.includes('/api/order/list')) { return { statusCode: 200, data: { list: [] } }; } }); // 用例结束后记得恢复，否则会影响后面的用例 await miniProgram.restoreWxMethod('request');

恢复这一步千万别忘。我早期就吃过这个亏：某个用例 mock 了接口，忘记恢复，后面十条用例全部拿到空数据，报告上一片红，我对着用例看了半天才想起来是 mock 没清。现在我的做法是在afterEach里统一做一次全量恢复，不管有没有 mock 过。

5. 放进流水线：无人值守回归的几个硬条件

5.1 无人值守环境下的运行前提

脚本在本地跑通和放进流水线跑，中间隔着一堆环境问题。我第一次把脚本扔进流水线，十分钟后收到的结果是一片红，而且每一条的报错都是"连接超时"。

排查下来有三个原因。

第一，工具需要图形环境。开发者工具本质上是个桌面应用，在没有显示的环境里启动会失败。解决方案一般有两种：一是用虚拟显示的能力给一个虚拟屏幕，二是用支持离屏运行的模式。我选的是前者，配置起来简单，兼容性也好。

第二，登录态。流水线环境是干净的，工具打开后处于未登录状态，自动化连上去也拿不到项目。我的处理方式是提前准备一个已登录的工具配置目录，运行时挂载进去。这个目录里存着登录凭证，所以要注意它的存放和权限，别随手提交到代码仓库里。

第三，路径和权限。流水线里的路径跟本地不一样，cliPath、projectPath都得改成环境变量或者配置项，不能写死。我现在的做法是全部走环境变量，本地给个默认值，流水线里覆盖掉。

const cliPath = process.env.DEVTOOLS_CLI_PATH || '/path/to/devtools/cli'; const projectPath = process.env.PROJECT_PATH || process.cwd();

这三件事搞定之后，流水线才算真正跑起来。这一步花了我大概两天，比写用例本身还久，但只要搞定一次，后面加用例就是纯收益。

5.2 报告、截图与失败现场还原

流水线上的失败和本地的失败不一样：本地你能看到界面，流水线上你什么都看不到。所以失败现场必须被记录下来，否则你就只能靠猜。

我的做法是在afterEach里判断结果，失败就截图。

afterEach(async () => { if (expect.getState().currentTestName && expect.getState().assertionCalls === 0) { const name = expect.getState().currentTestName.replace(/\s/g, '_'); await miniProgram.screenshot({ path: `screenshots/${name}.png` }); } });

截图之外，我还额外记录两样东西：当前页面路径，以及页面的关键文本内容。

const page = await miniProgram.currentPage(); console.log('failed at page:', page.path); const bodyText = await miniProgram.evaluate(() => { return JSON.stringify(getCurrentPages().map(p => p.route)); }); console.log('page stack:', bodyText);

页面栈这个东西在排查"为什么跳错页面"的时候特别有用。我遇到过一次，脚本点完之后查当前页面，路径跟预期差了两级，看页面栈才发现中间有个自动跳转的引导页，脚本没等它跳完就往下走了。

报告我建议至少包含这几个信息：用例名称、耗时、结果、失败截图路径、失败页面。信息量不用多，但这几项必须有。我见过只有"失败"两个字的报告，看一次还行，看三次就没人看了。

5.3 稳定性和耗时之间的取舍

自动化测试跑到一定规模，一定会遇到"偶发失败"这个敌人。我用过的手段，按效果从高到低排：

失败重试这个手段要慎用。它能解决环境抖动导致的偶发失败，但也会掩盖真实的时序问题。我现在的策略是：核心链路的用例一律不重试，失败了就是真失败；外围的、非关键路径的用例允许重试一次。这样既保证核心质量，又不至于被边缘用例的红灯淹没。

耗时方面，我的全量脚本跑完是四分钟出头，四十多条用例。这个速度是能接受的，因为它跑在我写代码的时候，不占用额外时间。如果哪天涨到十分钟以上，我就会考虑拆分成冒烟集（五分钟内跑完的核心用例）和全量集（发版前跑），冒烟集放在每次提交时触发。

6. 三个真实踩过的坑和排查路径

6.1 连接超时：端口、进程与工具版本的三角关系

这个坑我遇到不止一次，每次现象都一样：脚本启动后卡在连接阶段，几十秒后超时退出。

第一次查的时候我完全没方向，因为报错信息只有一行超时。我当时的排查路径是这样的：

先看工具是否正常。手动打开开发者工具，能正常打开项目、能正常操作界面，说明工具本身没问题。

再看端口。这一步是关键——服务端口的开关如果没打开，自动化永远连不上。打开设置确认开关状态，确实开着。

然后看进程。这一步发现了问题：后台残留着十几个工具进程，是之前脚本异常退出没有清理留下的。这些进程占着端口，新启动的实例连不上。

解决方案分两步。一是短期：把这些残留进程清掉，重新跑，通了。二是长期：在脚本里加finally关闭，并且在测试启动前做一次进程清理。

// 启动前清理残留（示意，实际命令按系统调整） const { execSync } = require('child_process'); try { execSync('pkill -f "devtools" || true'); } catch (e) { // 忽略 }

这个清理动作看起来粗暴，但在流水线环境里很有用，因为流水线的机器可能被复用，上一轮的残留会污染下一轮。

第三次遇到这个问题的时候，原因又不一样了：工具自动升级到了新版本，新版本的启动速度变慢，原来的超时时间不够。这件事让我养成了两个习惯——一是给启动超时留足余量，二是把工具版本锁死，不自动升级。

现在我的排查顺序固定成这样：先确认开关，再确认进程，最后确认版本。按这个顺序走，基本五分钟内定位。

6.2 元素明明在，点击没反应

这个现象我遇到的最多，也最费时间，因为脚本不报错，就是"什么都没发生"。

我把遇到的情况归成三类，排查时按这三类依次排除。

第一类，元素在视口外。前面提过，点击是真实点击，元素不在可视区域就点不到。排查方法很简单：截图看一眼，元素是不是在屏幕外。如果是，加滚动。

第二类，元素被遮挡。元素在视口内，但上面盖着一层东西——可能是弹窗、可能是浮层、可能是"新用户引导"的蒙层。这种情况截图能看出来。解决方案是先把遮挡物关掉，或者等它消失。

我遇到过一次特别坑的：一个"活动倒计时"的浮层，只在特定时间出现，本地跑的时候从来没碰到，流水线上跑的时候刚好撞上。后来我在用例开头加了一步"关闭可能存在的浮层"，判断存在就点关闭，不存在就跳过。

async function closePopupIfExists(page) { const close = await page.$('#popup-close'); if (close) { await close.tap(); } }

第三类，元素存在但不可交互。比如按钮是禁用状态、元素还没绑定事件、自定义组件的内部元素没有开放出来。排查方法是看元素的属性，检查disabled之类的状态。

const el = await page.$('#submit-btn'); const disabled = await el.attribute('disabled'); console.log('disabled:', disabled);

还有一种是组件内部元素虽然查到了，但点击事件绑在父节点上，点内部元素不触发。这种情况我会往上找一层，点父元素。

这三类排除完还不行，就得怀疑框架版本和工具版本的兼容性了。我遇到过工具升级之后，某类自定义组件的点击行为变了，只能升级框架版本来解决。

6.3 版本升级后集体失效

这个坑的杀伤力最大：某天早上来跑脚本，昨天的全绿变成今天的一片红，四十条用例挂了三十条。

第一次遇到时我慌了，以为是代码被人改了。查了提交记录，没人动。又怀疑是环境问题，重装了一遍依赖，没用。

冷静下来之后，我做了三件事。

第一件，挑一条最简单的用例单独跑。最简单的那条也挂了，说明问题在公共部分，不在具体用例。

第二件，看失败的具体位置。所有失败都出现在同一个位置——启动之后拿页面对象那一步。这说明是连接层或者页面获取的问题。

第三件，回想最近的环境变化。打开工具看了一眼版本号，发现自动升级到了新版本。

根因就这么找到了：新版本改了页面对象的返回结构，某个字段从数组变成了对象，我们的封装里按数组取，直接报错。

修复很快，改了两行代码。但这件事给了我一个更重要的教训：环境必须锁版本。我现在的做法是：

• 在项目根目录记录一份环境清单，写清楚工具版本、Node 版本、框架版本、依赖版本；
• 流水线镜像里预装指定版本的工具，关闭自动更新；
• 每次要升级工具，先在本地分支上跑全量脚本，确认全绿再合并。

这套流程建立之后，这一类"集体失效"再没发生过。

顺便说一个相关的经验：当一大批用例突然同时失败，九成以上是环境问题，不是用例问题。这时候最忌讳的是挨个去改用例，那会让你在错误的方向上改出一堆新问题。正确做法是先找共性——共同的失败位置、共同的前置动作、共同的环境变化。

最后分享一个小技巧：我在脚本里加了一行启动日志，打印工具版本、框架版本、当前时间。每次流水线失败，第一眼看这行日志，能快速判断是不是环境变了。这行日志不值钱，但省下来的排查时间很值钱。

用了大半年下来，我对这套东西的感受是：它的价值不在"炫技"，而在于把我从重复劳动里解放出来，让我有时间去看真正需要人判断的东西。前面写的这些坑，大部分都不是框架本身的问题，而是环境、时序、版本这些"工程细节"。把这些细节捋顺了，脚本就很稳；捋不顺，就会觉得这套东西"不好用"。我现在的心态是，把它当成项目里的一个普通模块去维护——有版本、有文档、有回归，它就能一直用下去。