vitest-midscene-e2e

Vitest Midscene E2E

模块

模块	角色
Vitest	TypeScript 测试框架。提供 describe/it/expect/hooks，用于组织测试、断言和管理生命周期。
Midscene	AI 驱动的 UI 自动化。通过自然语言与 UI 元素交互，无需脆弱的选择器。核心 API：aiAct。

支持的平台：

• Web — WebTest（Playwright Chromium）：ctx.agent + ctx.page
• Android — AndroidTest（ADB + scrcpy）：仅 ctx.agent
• iOS — IOSTest（WebDriverAgent）：仅 ctx.agent

工作流

步骤 1：克隆样板代码并确保项目已准备就绪

bash scripts/clone-boilerplate.sh

~/.midscene/boilerplate/vitest-all-platforms-demo/ 中的样板代码是项目结构、配置、平台上下文类和测试约定的权威参考。将当前项目与其进行比较。如果缺少任何内容，请询问用户需要哪些平台（Web / Android / iOS），然后以样板代码为目标状态补齐缺失内容。仅包含用户所需平台的文件。不要覆盖现有配置或文件。如果 .env 不存在，请将样板代码中的 .env.example 复制为 .env，并提示用户填写环境变量。

步骤 2：编写测试前，阅读下方的 Midscene Agent API 部分

其中包含使用 aiAct 的强制规则——它是所有 UI 操作的主要 API。不要跳过此步骤。

步骤 3：创建、更新或运行测试

参考样板代码的 e2e/ 目录和 src/context/，了解模式和约定。运行测试前，确保依赖已安装且 .env 已配置。调试失败时，请查看 troubleshooting.md。

Midscene Agent API

ctx.agent 是特定于平台的 Agent 实例。所有方法都会返回 Promise。

• Web：来自 @midscene/web/playwright 的 PlaywrightAgent
• Android：来自 @midscene/android 的 AndroidAgent
• iOS：来自 @midscene/ios 的 IOSAgent

以下三个 Agent 共享相同的 AI 方法。

强制规则：对用户描述的步骤使用 aiAct

当用户用自然语言描述 UI 操作或状态确认时，必须使用 aiAct 实现。 不要将用户指令拆解为 aiTap/aiInput/aiAssert 或其他细粒度 API。将用户的意图直接传给 aiAct，由 Midscene 的 AI 负责规划和执行。

// User says: "type iPhone in the search box and click search"

// WRONG — manually decomposing into fine-grained APIs
await ctx.agent.aiInput('search box', { value: 'iPhone' });
await ctx.agent.aiTap('search button');

// CORRECT — pass intent directly to aiAct
await ctx.agent.aiAct('type "iPhone" in the search box, then click the search button');

断言、数据提取和等待也应通过 aiAct 完成——它会处理所有这些操作。不要单独使用 aiAssert、aiQuery、aiWaitFor、aiTap 或 aiInput。

aiAct(taskPrompt, opt?) — 主要 API

aiAct 是所有 UI 操作和状态确认的主要 API。 它接收自然语言指令，并自主规划和执行多步骤交互。

// UI operations
await ctx.agent.aiAct('type "iPhone" in the search box, then click the search button');
await ctx.agent.aiAct('hover over the user avatar in the top right');

// State confirmations / assertions — also use aiAct
await ctx.agent.aiAct('verify the page shows "Login successful"');
await ctx.agent.aiAct('verify the error message is visible');

通过提示词上传文件（仅限 Web）

当 aiAct 提示词要求 Midscene 上传文件时，请显式传入 fileChooserAllowedDir。使用包含该测试用例夹具的最小目录，并在提示词中使用相对于该目录的文件路径。不要使用项目根目录或主目录。将下方的 ./fixtures 替换为相对于测试进程工作目录的夹具目录。

await ctx.agent.aiAct(
  'click the upload button and upload avatar.png',
  { fileChooserAllowedDir: './fixtures' },
);

拆分阶段： 如果任务提示词过长或涵盖多个不同阶段，请拆分为多个独立的 aiAct 调用，每个阶段调用一次。每个阶段都应是自包含的逻辑步骤，并且所有阶段合起来必须符合用户的原始意图。

// Incorrect — prompt spans multiple pages and too many steps, AI may lose context mid-way
await ctx.agent.aiAct('click the settings button in the top nav, go to settings page, find personal info and click into it, change email to "[email protected]", change phone to "13800000000", click save, wait for success');

// Correct — split by page/stage boundary, each phase stays within one logical context
await ctx.agent.aiAct('click the settings button in the top nav, go to settings page, find personal info and click into it');
await ctx.agent.aiAct('change email to "[email protected]", change phone to "13800000000", click save');
await ctx.agent.aiAct('verify the save success message appears');

aiAction 已弃用。请改用 aiAct 或 ai。

常见错误

• 定位器模糊 — 'button' 含义不明确；请使用 '页面顶部的蓝色“Submit”按钮'
• 已弃用的 aiAction — 请改用 aiAct
• 目标包含多个元素且不明确 — 请指定行或位置：'第一行商品中的删除按钮'

Agent 配置 — aiActionContext

aiActionContext 是一个系统提示词字符串，会附加到 Agent 执行的所有 AI 操作中。使用它来定义 AI 的角色和专业领域。

// Set via agentOptions in setup()
const ctx = WebTest.setup('https://example.com', {
  agentOptions: {
    aiActionContext: 'You are a Web UI testing expert.',
  },
});

好的示例：

• 'You are a Web UI testing expert.'
• 'You are an Android app testing expert who is familiar with Chinese UI.'

不好的示例：

• 'Click the login button.' — 具体操作应放在 aiAct() 中，而不是 aiActionContext 中
• 'The page is in Chinese.' — 这是页面描述，不是系统提示词

如何查找更多信息

1. 在 node_modules/@midscene/web、node_modules/@midscene/android 和 node_modules/@midscene/ios 中查找 Agent 类的类型定义
2. 如果类型信息不足，请沿着 .d.ts 文件中的源码引用，在 node_modules 中阅读实现代码
3. 下载 https://midscenejs.com/llms.txt，然后使用 grep 搜索所需的 API 或概念（该文件很大，请勿完整阅读）