@witon/laozhu_mp_e2e_testkit 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# laozhu_mp_e2e_testkit
+
+微信小程序 E2E 自动化测试通用套件：**automator 统一配置**、**日志转发与错误检测**、**测试规范文档**、**工具助手**。用例与业务逻辑由各项目自行实现。
+
+## 安装
+
+在项目根目录：
+
+```bash
+# 从 npm 安装
+npm install @witon/laozhu_mp_e2e_testkit
+
+# 或从 Git
+npm install git+https://github.com/your-org/laozhu_mp_e2e_testkit.git
+
+# 或本地路径（开发/未发布时）
+npm install file:./path/to/laozhu_mp_e2e_testkit
+```
+
+项目需已安装 `miniprogram-automator` 与 Jest（或其它测试运行器）。从 npm 安装时，代码中引用包名均为 `@witon/laozhu_mp_e2e_testkit`。
+
+## 配置
+
+### automator 统一配置（projectPath / cliPath）
+
+在 `beforeAll` 中获取配置并启动小程序：
+
+```js
+const automator = require('miniprogram-automator');
+const { getAutomatorConfig, installTestLogger } = require('@witon/laozhu_mp_e2e_testkit');
+const path = require('path');
+
+beforeAll(async () => {
+  const config = getAutomatorConfig({
+    projectPath: path.resolve(__dirname, '../..'),  // 小程序项目根路径
+    // cliPath: '...',  // 可选，默认用环境变量 WECHAT_CLI_PATH
+  });
+  miniProgram = await automator.launch({
+    cliPath: config.cliPath,
+    projectPath: config.projectPath,
+  });
+  await installTestLogger(miniProgram);
+}, 300000);
+```
+
+**环境变量（可选）：**
+
+- `MINIPROGRAM_PROJECT_PATH` 或 `E2E_PROJECT_PATH`：小程序项目根路径，不设则必须在调用 `getAutomatorConfig(overrides)` 时传入 `projectPath`
+- `WECHAT_CLI_PATH`：微信开发者工具 CLI 路径
+
+### TabBar 路径常量
+
+本包不包含 `TAB_BAR_PATHS`，由项目在本地定义并与此包的 `navigateTo`、`switchTab`、`navigateBack` 一起使用，例如：
+
+```js
+// test/setup/tabBarPaths.js
+const { navigateTo, switchTab, navigateBack } = require('@witon/laozhu_mp_e2e_testkit');
+
+const TAB_BAR_PATHS = {
+  INDEX: '/pages/index/index',
+  MINE: '/pages/mine/index',
+};
+
+module.exports = {
+  navigateTo,
+  switchTab,
+  navigateBack,
+  TAB_BAR_PATHS,
+};
+```
+
+## 使用
+
+从包中按需引用：
+
+```js
+const {
+  getAutomatorConfig,
+  installTestLogger,
+  startErrorCapture,
+  checkHadError,
+  debugLog,
+  waitForElement,
+  wait,
+  findButtonByText,
+  navigateTo,
+  switchTab,
+  scrollToSelector,
+  triggerPickerChange,
+} = require('@witon/laozhu_mp_e2e_testkit');
+```
+
+或从子路径引用（便于 tree-shaking 或按需加载）：
+
+```js
+const { getAutomatorConfig } = require('@witon/laozhu_mp_e2e_testkit/src/config/automatorConfig');
+const { installTestLogger, startErrorCapture, checkHadError } = require('@witon/laozhu_mp_e2e_testkit/src/logger/testLogger');
+const { waitForElement, wait } = require('@witon/laozhu_mp_e2e_testkit/src/utils/waitHelpers');
+```
+
+## 文档
+
+- [自动化测试实现原则](docs/AUTOMATION_TEST_PRINCIPLES.md)
+- [自动化测试日志原则](docs/LOGGING_PRINCIPLES.md)
+
+## 提供能力概览
+
+| 类别     | 内容 |
+|----------|------|
+| 统一配置 | `getAutomatorConfig(overrides)`、`checkCliExists()` |
+| 日志     | `installTestLogger`、`startErrorCapture`、`checkHadError`、`debugLog`、`debugWait`、`debugConfig` |
+| 等待     | `wait`、`waitFor`、`waitForElement`、`waitForAnyElement`、`waitForPagePath`、`waitForPageToLeave`、`waitForTextInPage`、`waitForTextNotInPage` |
+| 页面     | `findElement`、`findElements`、`findButtonByText`、`clickElement`、`inputText`、`elementExists`、`getElementText`、`scrollToSelector`、`scrollToElement` 等 |
+| 导航     | `navigateTo`、`switchTab`、`navigateBack`（无 `TAB_BAR_PATHS`，由项目定义） |
+| 表单     | `triggerPickerChange` |
+
+## 构建与发布
+
+构建与发布到 npm（公开）的步骤见 [PUBLISH.md](PUBLISH.md)。
+
+## License
+
+MIT

package/docs/AUTOMATION_TEST_PRINCIPLES.md

@@ -0,0 +1,179 @@
+# 自动化测试实现原则
+
+以 `test/integration/competitionFlow.test.js` 为范本，新建或扩展自动化测试用例时应遵循以下原则。
+
+---
+
+## 1. 分层辅助架构
+
+### 1.1 通用工具 (`test/utils/`)
+
+将可复用的操作抽取到 `test/utils/` 下的辅助模块：
+
+- **pageHelpers**：元素查找、点击、输入等与页面无关的通用操作
+- **waitHelpers**：`wait`、`waitFor`、`waitForElement`、`waitForAnyElement`、`waitForPagePath` 等异步等待
+- **navigationHelpers**：`navigateTo`、`switchTab`、`TAB_BAR_PATHS` 等导航能力
+- **formHelpers**：通用表单操作（如 `triggerPickerChange`），不依赖具体业务
+- **scrollHelpers**：`scrollToSelector`，在操作前将目标元素滚入视口
+- **testLogger**：日志转发、错误捕获
+
+原则：通用逻辑抽取到 utils，保持测试用例主流程简洁可读。
+
+---
+
+## 2. 文档化测试流程
+
+在测试文件顶部用注释说明：测试目标、步骤顺序、每步在做什么、前置条件（如 Mock）、环境限制和注意事项。这样阅读测试文件即可理解整体流程，方便后续维护和扩展。
+
+---
+
+## 3. 生命周期与 Mock 策略
+
+在 `beforeAll` 中完成：启动小程序、安装日志转发、等待初始化，并按需 Mock（如 `requestSubscribeMessage`、`showModal`）。Mock 时只 Mock 会阻塞或依赖真实环境的调用，既保证测试可运行，又尽量保持真实行为。
+
+---
+
+## 4. 异步与等待策略
+
+避免硬编码 `wait(ms)`，优先使用 `waitFor`、`waitForElement`、`waitForPagePath` 等条件等待，直到条件满足或超时。这样既减少无效等待、缩短运行时间，又降低因时机不稳定导致的间歇性失败。
+
+---
+
+## 5. 数据与状态传递
+
+长流程测试在用例内用共享变量（如 `competitionId`、`competitionName`）串联各步骤。测试数据命名加时间戳（如 `E2E测试_${dateStr}`），避免多次运行相互干扰，确保每个用例有可追踪的唯一标识。
+
+---
+
+## 6. 清理测试数据
+
+在测试结尾（或 `afterAll`）删除本次创建的测试数据（如通过云函数删除比赛），避免数据库中残留脏数据，保证后续运行环境干净、可复现。
+
+---
+
+## 7. 元素查找与交互策略
+
+优先用语义化方式查找元素（如通过按钮文案 `btn.text()`），而非依赖易变的 DOM 结构或选择器。在点击前用 `scrollToSelector` 将目标元素滚入视口，避免被遮挡或不可见；对 picker、日期等复杂组件，可考虑用 `page.callMethod` 模拟事件，绕过 UI 模拟的限制。
+
+---
+
+## 8. 错误检测与验证
+
+通过 `installTestLogger` 将小程序内的 `console.error` 转发到测试端，用 `startErrorCapture` 和 `checkHadError` 在用例结束时检查是否发生过 JS 错误。这样不仅验证 UI 行为，也确保执行过程中没有未捕获异常或错误日志。
+
+---
+
+## 9. 单用例长流程设计
+
+将完整业务链路（新建→配置→发布→报名→审核→查看→取消→清理）放在同一个 `test()` 中，共享生命周期和状态，减少重复启动和 Mock。这样提高效率，但单步失败时难以精确定位，需在日志和断言上适当补充。
+
+---
+
+## 10. 小程序侧错误日志输出
+
+**目的**：业务逻辑出错时能在自动化测试环境中可见、可追踪。
+
+**实现要点**：
+
+1. **使用 `console.error` 输出错误**  
+   在 catch、异常分支、校验失败等处使用 `console.error`，例如：
+   ```javascript
+   try {
+     await someAsyncOp();
+   } catch (e) {
+     console.error('操作失败', e.message, e);
+   }
+   ```
+
+2. **提供有意义的错误信息**  
+   日志中包含错误类型、简要上下文、必要参数（如 ID、接口名），便于定位问题。
+
+3. **保持 testLogger 能力**  
+   `testLogger` 会拦截并转发 `console.error` 到测试端，并标记 `hadError`，测试端可据此检测到业务错误。
+
+4. **避免吞掉错误**  
+   不要只 `console.error` 而不抛出或标记失败，否则日志能看到，但自动化测试无法断言结果。
+
+---
+
+## 11. 自动化测试通过错误日志检测运行结果
+
+**目的**：不仅验证 UI 与业务行为，还确保运行期间无未捕获错误或 `console.error`，避免“表面通过、内藏错误”。
+
+**实现要点**：
+
+1. **安装 testLogger**  
+   在 `beforeAll` 中启动小程序后调用：
+   ```javascript
+   await installTestLogger(miniProgram);
+   ```
+
+2. **测试前重置错误状态**  
+   在用例开始时调用：
+   ```javascript
+   startErrorCapture();
+   ```
+
+3. **测试结束时校验**  
+   用例末尾断言：
+   ```javascript
+   expect(checkHadError()).toBe(false);
+   ```
+
+4. **机制说明**  
+   - `installTestLogger`：在小程序内 patch `console`，通过 `exposeFunction` 将日志转发到测试端，并监听未捕获异常。  
+   - `startErrorCapture`：将 `hadError` 置为 false，开始新一轮检测。  
+   - `checkHadError`：返回本次测试期间是否出现过 `console.error` 或未捕获异常。
+
+5. **长流程用例**  
+   单用例覆盖多步骤时，在流程开始前调用 `startErrorCapture()`，流程结束后调用 `checkHadError()` 一次，即可检测整个链路中是否出现错误日志或异常。
+
+---
+
+## 12. 业务流程中的页面跳转
+
+在业务流程测试中，页面间跳转时应**尽量使用页面操作的方式**（如点击按钮、链接、列表项等触发导航），而非在测试代码中直接调用 `page.navigateTo`、`switchTab` 等 API 跳转。
+
+**理由**：通过页面操作模拟真实用户行为，既能验证导航入口是否正确（如按钮是否可点、跳转逻辑是否生效），也能覆盖从点击到跳转的完整链路；直接跳转则绕过了入口和中间逻辑，测试覆盖面不足，且难以发现入口相关的回归问题。
+
+**例外**：在必须从特定页面开始、或入口不可用（如 Mock 场景）时，可使用 `navigationHelpers` 直接跳转作为前置步骤。
+
+---
+
+## 13. UI 失败不兜底云函数
+
+**目的**：E2E 测试以验证真实用户路径为主；若通过 UI 操作失败，应暴露问题、驱动修正，而不是用云函数等“捷径”掩盖失败。
+
+**原则**：
+
+1. **不兜底**  
+   当某步通过 UI 操作（点击、输入、导航等）失败时，**不要**在测试中再尝试通过云函数、`callMethod`、`evaluate` 等方式完成同一操作作为“后备”。例如：UI 删除活动失败时，不要再用云函数 `deleteActivity` 删除以“保证测试通过”。
+
+2. **检测并失败**  
+   一旦检测到 UI 操作未达到预期（如未找到按钮、操作后状态未更新、删除未成功等），应通过 `expect(...)` 让测试失败，并辅以清晰的日志（如 `debugLog('✗ UI删除失败，不调用云函数，测试应失败以驱动修正')`）。
+
+3. **驱动修正**  
+   测试失败会促使修正 UI 流程、Mock 策略或测试步骤本身，从而提升真实用户路径的可信度；若用云函数兜底，测试可能通过但 UI 问题被隐藏。
+
+**适用场景**：所有依赖 UI 完成的关键步骤（如创建、编辑、删除、报名、取消等），其失败处理都应遵循本原则。
+
+---
+
+## 14. 测试用例实现方式单一清晰
+
+**目的**：用例逻辑简单可读、行为稳定，避免“多种尝试、多种兜底”带来的复杂度和潜在误判。
+
+**原则**：
+
+1. **编写与调试时可尝试多种实现**  
+   在编写或调试测试时，可以尝试多种查找方式、多种等待策略等，以验证哪种方式在环境中可靠。
+
+2. **最终只保留一种最清晰可靠的实现**  
+   定稿时只保留一种最清晰、最可靠的实现方式写进测试用例，删除其余尝试和兜底逻辑。例如：若页面已为删除按钮设置 `data-id`，则只用「文本为“删除”且 `data-id === activityId`」定位按钮，不再叠加“按标题+索引匹配”“找不到就用第一个”等后备方案。
+
+3. **避免多重 fallback 带来的问题**  
+   多重 fallback 会令用例难以理解和维护，且可能掩盖真实问题（如“用第一个删除按钮”可能误删其他数据）。找不到目标时，应让断言失败并辅以清晰日志，便于定位并修正页面或测试本身。
+
+**适用场景**：元素查找、等待条件、状态判定等一切在测试中可能写出多种实现方式的逻辑。
+
+---

package/docs/LOGGING_PRINCIPLES.md

@@ -0,0 +1,97 @@
+# 自动化测试日志原则
+
+为自动化测试设计一套使用 `console.debug`、`console.error` 输出日志的机制。何时该输出日志，输出什么级别的日志。
+
+---
+
+## 1. 背景
+
+- **testLogger** 会将小程序内的 `console.log/info/warn/error/debug` 转发到测试终端
+- **只有 `console.error` 会触发 `hadError`**，导致 `checkHadError()` 时测试失败
+- 因此：**日志级别直接影响自动化测试的通过/失败判定**
+
+---
+
+## 2. 日志级别定义
+
+| 级别 | 是否影响测试结果 | 使用场景 |
+|------|------------------|----------|
+| **console.error** | ✅ 会（视为失败） | 真实业务错误、异常、校验失败、不可恢复状态 |
+| **console.debug** | ❌ 不会 | 流程关键节点、状态变化、诊断信息，便于排查问题 |
+
+---
+
+## 3. console.error —— 何时输出
+
+仅在 **业务错误、异常、校验失败、不可恢复状态** 时使用，且应包含足够上下文。
+
+| 场景 | 示例 |
+|------|------|
+| catch 异常 | `try/catch` 中的异常、网络错误 |
+| 云函数/接口返回错误 | `ret.errorcode !== 0` 或接口失败 |
+| 数据校验失败 | 必填项为空、ID 无效、状态不合法 |
+| 关键前置条件缺失 | 如活动/比赛 ID 不存在 |
+
+**推荐格式：**
+```javascript
+console.error('[模块名] 简短描述', { errorcode, msg, id, ... });
+// 或
+console.error('操作失败:', error.message, error);
+```
+
+---
+
+## 4. console.debug —— 何时输出
+
+用于 **可追踪流程和诊断** 的信息，不影响测试通过/失败。
+
+| 场景 | 示例 |
+|------|------|
+| 关键流程节点 | 进入/离开页面、发起请求、收到响应 |
+| 重要状态变化 | 报名成功、签到成功、状态切换 |
+| 调试相关数据 | 请求参数、返回 ID、加载的数据量 |
+| 替代无意义的 console.log | 点击事件、选择事件等开发调试用日志 |
+
+**推荐格式：**
+```javascript
+console.debug('[模块名] 操作/状态描述', { key: value });
+```
+
+---
+
+## 5. 不建议使用或需谨慎
+
+| 级别 | 建议 |
+|------|------|
+| **console.log** | 可改为 `console.debug`，避免与正式环境日志混淆，语义更清晰 |
+| **console.info** | 与 debug 类似，可统一用 `console.debug` |
+| **console.warn** | 可用于降级、非致命问题；当前不触发 hadError，若需视为失败应改用 `error` |
+
+---
+
+## 6. 分层建议
+
+| 代码位置 | 建议 |
+|----------|------|
+| **页面 / 业务逻辑** | catch、校验失败、接口错误 → `console.error`；关键流程节点 → `console.debug` |
+| **clicom / 云调用** | 请求失败、云函数返回错误 → `console.error`；成功或调试信息 → `console.debug` |
+| **云函数** | 业务错误 → `console.error`；调试/流程信息 → `console.debug` 或 `console.log`（云函数侧无 testLogger） |
+
+---
+
+## 7. 与自动化测试的配合
+
+1. **testLogger** 已转发所有 console 级别，测试端可看到完整输出
+2. 只有 **`console.error`** 会触发 `checkHadError()`
+3. **`console.debug`** 仅作诊断，不影响测试结果
+4. 测试中通过 `startErrorCapture()` + `checkHadError()` 可确保流程中无业务错误
+
+---
+
+## 8. 总结
+
+- **`console.error`**：业务/技术错误，需要测试失败 → 仅在真实错误时使用
+- **`console.debug`**：流程与诊断信息，帮助排查问题 → 用于关键步骤和状态变化
+- 使用 `[模块名]` 前缀，便于搜索和定位
+- 错误日志需包含 `errorcode`、`id`、`msg` 等上下文
+- 避免只 `console.error` 而不抛出或标记失败，否则日志可见但自动化测试无法断言结果

package/index.js

@@ -0,0 +1,36 @@
+/**
+ * laozhu_mp_e2e_testkit 统一导出
+ * 微信小程序 E2E：统一配置、日志、测试规范文档、工具助手
+ */
+
+const config = require('./src/config/automatorConfig');
+const logger = require('./src/logger/testLogger');
+const debugConfig = require('./src/logger/debugConfig');
+const debugHelpers = require('./src/logger/debugHelpers');
+const waitHelpers = require('./src/utils/waitHelpers');
+const pageHelpers = require('./src/utils/pageHelpers');
+const navigationHelpers = require('./src/utils/navigationHelpers');
+const formHelpers = require('./src/utils/formHelpers');
+const scrollHelpers = require('./src/utils/scrollHelpers');
+
+module.exports = {
+  // config
+  getAutomatorConfig: config.getAutomatorConfig,
+  checkCliExists: config.checkCliExists,
+  DEFAULT_CONFIG: config.DEFAULT_CONFIG,
+
+  // logger
+  installTestLogger: logger.installTestLogger,
+  startErrorCapture: logger.startErrorCapture,
+  checkHadError: logger.checkHadError,
+  debugConfig,
+  debugLog: debugHelpers.debugLog,
+  debugWait: debugHelpers.debugWait,
+
+  // utils
+  ...waitHelpers,
+  ...pageHelpers,
+  ...navigationHelpers,
+  ...formHelpers,
+  ...scrollHelpers,
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@witon/laozhu_mp_e2e_testkit",
+  "version": "1.0.0",
+  "description": "微信小程序 E2E 自动化测试：日志转发、测试规范文档、工具助手与 automator 统一配置",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "src/",
+    "docs/"
+  ],
+  "scripts": {
+    "prepublishOnly": "node -e \"require('fs').accessSync('index.js')\"",
+    "build": "echo No build step"
+  },
+  "peerDependencies": {
+    "miniprogram-automator": ">=0.12.0"
+  },
+  "keywords": [
+    "miniprogram",
+    "wechat",
+    "e2e",
+    "automator",
+    "jest"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config/automatorConfig.js

@@ -0,0 +1,52 @@
+/**
+ * 小程序自动化工具统一配置
+ * projectPath、cliPath 可通过环境变量或 getAutomatorConfig(overrides) 传入
+ */
+
+// 默认配置：projectPath 优先从环境变量读取，否则需调用方传入 overrides
+const DEFAULT_CONFIG = {
+  cliPath: process.env.WECHAT_CLI_PATH || "C:\\Program Files (x86)\\Tencent\\微信web开发者工具\\cli.bat",
+  projectPath: process.env.MINIPROGRAM_PROJECT_PATH || process.env.E2E_PROJECT_PATH || undefined,
+  launchTimeout: 300000,
+  testTimeout: 300000,
+};
+
+/**
+ * 获取自动化工具配置
+ * @param {Object} overrides - 覆盖默认配置，如 { projectPath: path.resolve(__dirname, '../..'), cliPath: '...' }
+ * @returns {Object} 配置对象
+ */
+function getAutomatorConfig(overrides = {}) {
+  const merged = {
+    ...DEFAULT_CONFIG,
+    ...overrides,
+  };
+  if (merged.projectPath == null || merged.projectPath === '') {
+    console.warn('laozhu_mp_e2e_testkit: projectPath 未设置，请通过 overrides 或环境变量 MINIPROGRAM_PROJECT_PATH / E2E_PROJECT_PATH 指定小程序项目根路径');
+  }
+  return merged;
+}
+
+/**
+ * 检测微信开发者工具 CLI 是否存在
+ * @param {Object} [config] - 可选，若不传则使用 getAutomatorConfig()
+ * @returns {Promise<boolean>}
+ */
+async function checkCliExists(config) {
+  const fs = require('fs').promises;
+  const cfg = config || getAutomatorConfig();
+  try {
+    await fs.access(cfg.cliPath);
+    return true;
+  } catch (error) {
+    console.warn(`警告: 未找到微信开发者工具 CLI: ${cfg.cliPath}`);
+    console.warn('请设置环境变量 WECHAT_CLI_PATH 或在调用 getAutomatorConfig 时传入 cliPath');
+    return false;
+  }
+}
+
+module.exports = {
+  getAutomatorConfig,
+  checkCliExists,
+  DEFAULT_CONFIG,
+};

package/src/logger/debugConfig.js

@@ -0,0 +1,12 @@
+/**
+ * 调试模式配置
+ * 通过环境变量 TEST_DEBUG=true 启用
+ */
+
+const DEBUG_CONFIG = {
+  ENABLED: process.env.TEST_DEBUG === 'true' || false,
+  DELAY_MS: 2000,
+  VERBOSE: true,
+};
+
+module.exports = DEBUG_CONFIG;

package/src/logger/debugHelpers.js

@@ -0,0 +1,24 @@
+/**
+ * 调试工具函数
+ */
+
+const DEBUG_CONFIG = require('./debugConfig');
+const { wait } = require('../utils/waitHelpers');
+
+function debugLog(...args) {
+  if (DEBUG_CONFIG.ENABLED && DEBUG_CONFIG.VERBOSE) {
+    console.log(...args);
+  }
+}
+
+async function debugWait(ms = null) {
+  if (DEBUG_CONFIG.ENABLED) {
+    const delayTime = ms || DEBUG_CONFIG.DELAY_MS;
+    await wait(delayTime);
+  }
+}
+
+module.exports = {
+  debugLog,
+  debugWait,
+};

package/src/logger/testLogger.js

@@ -0,0 +1,106 @@
+/**
+ * 小程序自动化测试 - 日志转发
+ * 使用 miniProgram.exposeFunction 将小程序内 console 输出转发到测试终端
+ */
+
+const TEST_LOG_NAME = '__testLog__';
+
+const errorCaptureState = {
+  hadError: false,
+};
+
+function bindingLog(level, location, ...args) {
+  if (level === 'error') {
+    if (location && typeof location === 'string') {
+      console.error('[MiniProgram][error]', location);
+      if (args.length > 0) {
+        console.error(...args);
+      }
+    } else {
+      console.error('[MiniProgram][error]', ...args);
+    }
+    errorCaptureState.hadError = true;
+  } else {
+    if (location !== undefined) {
+      console.log('[MiniProgram][' + level + ']', location, ...args);
+    } else {
+      console.log('[MiniProgram][' + level + ']', ...args);
+    }
+  }
+}
+
+function patchConsoleInMiniprogram() {
+  if (typeof __testLog__ !== 'function') return;
+  var methods = ['log', 'info', 'warn', 'error', 'debug'];
+  for (var i = 0; i < methods.length; i++) {
+    (function (level) {
+      var orig = console[level];
+      if (!orig) return;
+      console[level] = function () {
+        var args = Array.prototype.slice.call(arguments);
+        orig.apply(console, args);
+        if (level === 'error') {
+          try {
+            var stack = new Error().stack;
+            if (stack) {
+              var lines = stack.split('\n');
+              var location = null;
+              for (var j = 0; j < lines.length; j++) {
+                var line = lines[j];
+                if (line.indexOf('Error') === -1 &&
+                    line.indexOf('console') === -1 &&
+                    line.indexOf('__testLog__') === -1 &&
+                    line.trim() !== '') {
+                  location = line.trim();
+                  break;
+                }
+              }
+              if (location) {
+                __testLog__.apply(null, [level, location].concat(args));
+              } else {
+                __testLog__.apply(null, [level, undefined].concat(args));
+              }
+            } else {
+              __testLog__.apply(null, [level, undefined].concat(args));
+            }
+          } catch (e) {
+            __testLog__.apply(null, [level, undefined].concat(args));
+          }
+        } else {
+          __testLog__.apply(null, [level, undefined].concat(args));
+        }
+      };
+    })(methods[i]);
+  }
+}
+
+async function installTestLogger(miniProgram) {
+  if (!miniProgram || typeof miniProgram.exposeFunction !== 'function') {
+    return;
+  }
+  try {
+    await miniProgram.exposeFunction(TEST_LOG_NAME, bindingLog);
+    await miniProgram.evaluate(patchConsoleInMiniprogram);
+    if (typeof miniProgram.on === 'function') {
+      miniProgram.on('exception', () => {
+        errorCaptureState.hadError = true;
+      });
+    }
+  } catch (err) {
+    console.warn('[testLogger] 安装小程序日志转发失败（不影响测试）:', err.message);
+  }
+}
+
+function startErrorCapture() {
+  errorCaptureState.hadError = false;
+}
+
+function checkHadError() {
+  return errorCaptureState.hadError;
+}
+
+module.exports = {
+  installTestLogger,
+  startErrorCapture,
+  checkHadError,
+};

package/src/utils/formHelpers.js

@@ -0,0 +1,20 @@
+/**
+ * 表单操作通用工具
+ */
+
+const { wait } = require('./waitHelpers');
+
+async function triggerPickerChange(page, methodName, value) {
+  try {
+    await page.callMethod(methodName, { detail: { value } });
+    await wait(200);
+    return true;
+  } catch (error) {
+    console.warn(`triggerPickerChange ${methodName} 失败:`, error.message);
+    return false;
+  }
+}
+
+module.exports = {
+  triggerPickerChange,
+};

package/src/utils/navigationHelpers.js

@@ -0,0 +1,50 @@
+/**
+ * 导航辅助函数（不包含 TAB_BAR_PATHS，由项目在本地定义）
+ */
+
+const { debugLog, debugWait } = require('../logger/debugHelpers');
+const { wait } = require('./waitHelpers');
+
+async function navigateTo(miniProgram, path, query = {}, options = {}) {
+  const { description = `导航到: ${path}` } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  const queryString = Object.keys(query)
+    .map(key => `${key}=${encodeURIComponent(query[key])}`)
+    .join('&');
+  const url = queryString ? `${path}?${queryString}` : path;
+  const page = await miniProgram.navigateTo(url);
+
+  debugLog(`  ✓ ${description}完成`);
+  await debugWait();
+  return page;
+}
+
+async function switchTab(miniProgram, tabBarPath, options = {}) {
+  const { description = `切换到TabBar: ${tabBarPath}` } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  const page = await miniProgram.switchTab(tabBarPath);
+  debugLog(`  ✓ ${description}完成`);
+  await debugWait();
+  return page;
+}
+
+async function navigateBack(page, options = {}) {
+  const { description = '返回上一页' } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  await page.navigateBack();
+  await wait(1000);
+  debugLog(`  ✓ ${description}完成`);
+  await debugWait();
+}
+
+module.exports = {
+  navigateTo,
+  switchTab,
+  navigateBack,
+};

package/src/utils/pageHelpers.js

@@ -0,0 +1,174 @@
+/**
+ * 页面操作辅助函数
+ */
+
+const { waitForElement, wait } = require('./waitHelpers');
+const { debugLog, debugWait } = require('../logger/debugHelpers');
+
+async function findElement(pageOrElement, selector, timeout = 5000) {
+  return await waitForElement(pageOrElement, selector, timeout);
+}
+
+async function findAllButtonsByText(pageOrElement, pattern, options = {}) {
+  const { timeout = 5000 } = options;
+  const startTime = Date.now();
+  let isRegExp = pattern instanceof RegExp;
+  let matcher = isRegExp ? (txt) => pattern.test(txt) : (txt) => txt && txt.includes(pattern);
+
+  while (Date.now() - startTime < timeout) {
+    try {
+      const buttons = await pageOrElement.$$('button').catch(() => []);
+      const matched = [];
+      for (const btn of buttons) {
+        try {
+          const btnText = await btn.text();
+          if (btnText && matcher(btnText.trim())) matched.push(btn);
+        } catch (e) { /* ignore */ }
+      }
+      if (matched.length > 0) return matched;
+    } catch (e) { /* ignore */ }
+    await wait(100);
+  }
+  return [];
+}
+
+async function findButtonByText(pageOrElement, pattern, options = {}) {
+  const buttons = await findAllButtonsByText(pageOrElement, pattern, options);
+  if (buttons && buttons.length > 0) return buttons[0];
+  return null;
+}
+
+async function findElements(pageOrElement, selector, timeout = 5000) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    try {
+      const elements = await pageOrElement.$$(selector);
+      if (elements && elements.length > 0) return elements;
+    } catch (error) { /* continue */ }
+    await wait(100);
+  }
+  return [];
+}
+
+async function clickElement(pageOrElement, selector, options = {}) {
+  const { description = `点击元素: ${selector}`, timeout = 5000 } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  const element = await findElement(pageOrElement, selector, timeout);
+  await element.tap();
+  await wait(300);
+
+  debugLog(`  ✓ ${description}完成`);
+  await debugWait();
+  return element;
+}
+
+async function elementExists(pageOrElement, selector) {
+  try {
+    const element = await pageOrElement.$(selector);
+    return !!element;
+  } catch (error) {
+    return false;
+  }
+}
+
+async function getElementText(pageOrElement, selector, options = {}) {
+  const { description = `获取元素文本: ${selector}`, timeout = 5000 } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  const element = await findElement(pageOrElement, selector, timeout);
+  const text = await element.text();
+
+  debugLog(`  ✓ ${description}完成: ${text.substring(0, 50)}...`);
+  await debugWait();
+  return text;
+}
+
+async function inputText(pageOrElement, selector, text, options = {}) {
+  const { description = `输入文本到: ${selector}`, timeout = 5000 } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  const element = await findElement(pageOrElement, selector, timeout);
+  await element.input(text);
+  await wait(200);
+
+  debugLog(`  ✓ ${description}完成: ${text}`);
+  await debugWait();
+  return element;
+}
+
+async function scrollPage(page, x, y, options = {}) {
+  const { description = `滑动页面到 scrollTop: ${y}` } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+  debugLog(`  ⚠ 页面滚动功能：miniprogram-automator 可能不支持直接滚动`);
+  await wait(300);
+  debugLog(`  ✓ ${description}完成（已跳过实际滚动操作）`);
+  await debugWait();
+}
+
+async function pullDownRefresh(page, options = {}) {
+  const { description = '下拉刷新' } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+  debugLog(`  ⚠ 下拉刷新功能：miniprogram-automator 可能不支持直接触发`);
+  await wait(500);
+  debugLog(`  ✓ ${description}完成（已跳过实际刷新操作）`);
+  await debugWait();
+}
+
+async function clickComponentAndNavigate(page, selector, options = {}) {
+  const { description = `点击组件: ${selector}`, timeout = 5000, waitAfterClick = 2000 } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  const element = await findElement(page, selector, timeout);
+  await element.tap();
+  debugLog(`  ✓ 已点击，等待跳转...`);
+  await wait(waitAfterClick);
+  await debugWait();
+  return element;
+}
+
+async function clickElementObject(element, options = {}) {
+  const { description = '点击元素', waitAfterClick = 2000 } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  await element.tap();
+  debugLog(`  ✓ 已点击，等待响应...`);
+  await wait(waitAfterClick);
+  await debugWait();
+  return element;
+}
+
+async function selectOption(page, selector, optionValue, options = {}) {
+  const { description = `选择选项: ${optionValue}` } = options;
+  debugLog(`  📌 ${description}...`);
+  await debugWait();
+
+  const pickerElement = await findElement(page, selector);
+  await pickerElement.tap();
+  await wait(500);
+  debugLog(`  ✓ ${description}完成`);
+  await debugWait();
+}
+
+module.exports = {
+  findElement,
+  findElements,
+  clickElement,
+  elementExists,
+  getElementText,
+  inputText,
+  scrollPage,
+  pullDownRefresh,
+  clickComponentAndNavigate,
+  clickElementObject,
+  selectOption,
+  findButtonByText,
+  findAllButtonsByText,
+};

package/src/utils/scrollHelpers.js

@@ -0,0 +1,61 @@
+/**
+ * 测试用滚动辅助
+ */
+
+const { debugLog } = require('../logger/debugHelpers');
+const { wait } = require('./waitHelpers');
+
+async function scrollToSelector(miniProgram, selector, options = {}) {
+  const { offsetTop: offsetTopOption = 80 } = options;
+  debugLog(`  📜 滚动到组件: ${selector}`);
+
+  try {
+    const page = await miniProgram.currentPage();
+    if (!page) return;
+
+    const element = await page.$(selector);
+    if (!element) {
+      debugLog(`  ⚠ 未找到元素: ${selector}`);
+      return;
+    }
+
+    const offset = await element.offset();
+    if (!offset || offset.top === undefined) {
+      debugLog(`  ⚠ 无法获取元素位置: ${selector}`);
+      return;
+    }
+
+    const scrollTop = Math.max(0, offset.top - offsetTopOption);
+    await miniProgram.pageScrollTo(scrollTop);
+    await wait(350);
+  } catch (e) {
+    debugLog(`  ⚠ 滚动失败: ${e.message || e}`);
+  }
+}
+
+async function scrollToElement(miniProgram, element, options = {}) {
+  const { offsetTop: offsetTopOption = 80 } = options;
+
+  if (!element) {
+    debugLog('  ⚠ scrollToElement: element 为空');
+    return;
+  }
+
+  try {
+    const offset = await element.offset();
+    if (!offset || offset.top === undefined) {
+      debugLog('  ⚠ scrollToElement: 无法获取元素位置');
+      return;
+    }
+    const scrollTop = Math.max(0, offset.top - offsetTopOption);
+    await miniProgram.pageScrollTo(scrollTop);
+    await wait(350);
+  } catch (e) {
+    debugLog(`  ⚠ scrollToElement 滚动失败: ${e.message || e}`);
+  }
+}
+
+module.exports = {
+  scrollToSelector,
+  scrollToElement,
+};

package/src/utils/waitHelpers.js

@@ -0,0 +1,147 @@
+/**
+ * 等待和断言辅助函数
+ */
+
+function wait(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function waitForTextNotInPage(page, pattern, timeout = 5000, interval = 200) {
+  const isRegExp = pattern instanceof RegExp;
+  const matcher = isRegExp
+    ? (txt) => pattern.test(txt)
+    : (txt) => txt && txt.includes(pattern);
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    try {
+      const views = await page.$$('view').catch(() => []);
+      const texts = await Promise.all(views.map(v => v.text().catch(() => '')));
+      const combined = texts.join(' ');
+      if (!texts.some(txt => matcher(txt)) && !matcher(combined)) {
+        return true;
+      }
+    } catch (e) {
+      return true;
+    }
+    await wait(interval);
+  }
+  throw new Error(`页面 ${timeout}ms 内未移除指定文本: "${pattern}"`);
+}
+
+async function waitForTextInPage(page, pattern, timeout = 5000, interval = 200) {
+  const isRegExp = pattern instanceof RegExp;
+  const matcher = isRegExp
+    ? (txt) => pattern.test(txt)
+    : (txt) => txt && txt.includes(pattern);
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    try {
+      const views = await page.$$('view').catch(() => []);
+      const texts = await Promise.all(views.map(v => v.text().catch(() => '')));
+      const combined = texts.join(' ');
+      if (texts.some(txt => matcher(txt)) || matcher(combined)) {
+        return true;
+      }
+    } catch (e) {
+      // ignore
+    }
+    await wait(interval);
+  }
+  throw new Error(`页面 ${timeout}ms 内未出现指定文本: "${pattern}"`);
+}
+
+async function waitFor(condition, timeout = 5000, interval = 100, errorMessage = '等待条件超时') {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    try {
+      const result = await condition();
+      if (result) return true;
+    } catch (error) {
+      // continue
+    }
+    await wait(interval);
+  }
+  throw new Error(`${errorMessage}: ${timeout}ms`);
+}
+
+async function waitForElement(page, selector, timeout = 5000) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    try {
+      const element = await page.$(selector);
+      if (element) return element;
+    } catch (error) {
+      // continue
+    }
+    await wait(100);
+  }
+  throw new Error(`元素未找到: ${selector} (超时: ${timeout}ms)`);
+}
+
+async function waitForAnyElement(page, selectors, timeout = 8000) {
+  const list = Array.isArray(selectors) ? selectors : [selectors];
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    for (const sel of list) {
+      try {
+        const el = await page.$(sel);
+        if (el) return el;
+      } catch (e) { /* ignore */ }
+    }
+    await wait(100);
+  }
+  throw new Error(`等待任一元素超时: [${list.join(', ')}] (${timeout}ms)`);
+}
+
+async function waitForPagePath(miniProgram, condition, options = {}) {
+  const { timeout = 15000, interval = 200 } = options;
+  const isString = typeof condition === 'string';
+  const predicate = isString ? (path) => (path || '').includes(condition) : condition;
+  const errorMsg = isString ? `等待页面路径包含 "${condition}" 超时` : '等待页面路径满足条件超时';
+
+  let lastPage = null;
+  let lastPath = '';
+  try {
+    await waitFor(
+      async () => {
+        lastPage = await miniProgram.currentPage();
+        lastPath = lastPage ? (lastPage.path || '') : '';
+        return predicate(lastPath);
+      },
+      timeout,
+      interval,
+      errorMsg
+    );
+  } catch (err) {
+    const pathInfo = lastPath !== undefined && lastPath !== '' ? ` 当前 path: "${lastPath}"` : ' (currentPage 或 path 为空)';
+    throw new Error(`${err.message}${pathInfo}`);
+  }
+  return lastPage;
+}
+
+async function waitForPageToLeave(miniProgram, pathToLeave, options = {}) {
+  const { timeout = 15000, interval = 200 } = options;
+  let lastPage = null;
+  await waitFor(
+    async () => {
+      lastPage = await miniProgram.currentPage();
+      const path = lastPage ? (lastPage.path || '') : '';
+      return !path.includes(pathToLeave);
+    },
+    timeout,
+    interval,
+    `等待离开页面 "${pathToLeave}" 超时`
+  );
+  return lastPage;
+}
+
+module.exports = {
+  wait,
+  waitFor,
+  waitForElement,
+  waitForAnyElement,
+  waitForPagePath,
+  waitForPageToLeave,
+  waitForTextInPage,
+  waitForTextNotInPage,
+};