vitest-midscene-e2e

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vitest Midscene E2E

Modules

模块

Module	Role
Vitest	TypeScript test framework. Provides `describe` / `it` / `expect` /hooks for test organization, assertions, and lifecycle.
Midscene	AI-driven UI automation. Interacts with UI elements via natural language — no fragile selectors. Core API: `aiAct` .

Supported platforms:

Web —
```
WebTest
```
(Playwright Chromium):
```
ctx.agent
```
+
```
ctx.page
```
Android —
```
AndroidTest
```
(ADB + scrcpy):
```
ctx.agent
```
only
iOS —
```
IOSTest
```
(WebDriverAgent):
```
ctx.agent
```
only

模块	作用
Vitest	TypeScript测试框架。提供 `describe` / `it` / `expect` 及钩子函数，用于测试组织、断言和生命周期管理。
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
```

Workflow

工作流程

Step 1: Clone boilerplate & ensure project ready

步骤1：克隆模板项目并确保项目就绪

bash

bash scripts/clone-boilerplate.sh

The boilerplate at

~/.midscene/boilerplate/vitest-all-platforms-demo/

is the canonical reference for project structure, configs, platform context classes, and test conventions. Compare the current project against it. If anything is missing, ask the user which platform(s) they need (Web / Android / iOS), then fill in what's missing using the boilerplate as the target state. Only include files for the requested platform(s). Do NOT overwrite existing configs or files. Copy

.env.example

from the boilerplate as

.env

if it doesn't exist, and prompt the user to fill in the env vars.

bash

bash scripts/clone-boilerplate.sh

位于

~/.midscene/boilerplate/vitest-all-platforms-demo/

的模板项目是项目结构、配置、平台上下文类和测试规范的标准参考。请将当前项目与模板进行对比。如果有缺失内容，请询问用户需要支持哪些平台（Web / Android / iOS），然后以模板为基准补充缺失的内容。仅包含用户指定平台的相关文件，请勿覆盖现有配置或文件。如果

.env

文件不存在，从模板中复制

.env.example

并重命名为

.env

，并提示用户填写环境变量。

Step 2: Read the Midscene Agent API section below before writing tests

步骤2：编写测试前请阅读下方的Midscene Agent API章节

It contains mandatory rules for using

aiAct

— the primary API for all UI operations. Do NOT skip this step.

该章节包含使用

aiAct

的强制规则——

aiAct

是所有UI操作的核心API，请务必不要跳过此步骤。

Step 3: Create, update, or run tests

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

Use the boilerplate's

e2e/

directory and

src/context/

as reference for patterns and conventions. Before running tests, ensure dependencies are installed and

.env

is configured. When debugging failures, check troubleshooting.md.

请参考模板项目的

e2e/

目录和

src/context/

目录中的模式与规范。运行测试前，请确保已安装依赖并配置好

.env

文件。调试失败时，请查看troubleshooting.md。

Midscene Agent API

ctx.agent

is a platform-specific agent instance. All methods return Promises.

Web:
```
PlaywrightAgent
```
from
```
@midscene/web/playwright
```
Android:
```
AndroidAgent
```
from
```
@midscene/android
```
iOS:
```
IOSAgent
```
from
```
@midscene/ios
```

All three agents share the same AI methods below.

ctx.agent

是平台专属的Agent实例，所有方法均返回Promise。

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

这三种Agent共享以下AI方法。

Mandatory Rule: Use

aiAct

for User-Described Steps

强制规则：使用

aiAct

实现用户描述的步骤

When the user describes a UI action or state confirmation in natural language, you MUST use
aiAct
to implement it. Do NOT decompose user instructions into
aiTap
/
aiInput
/
aiAssert
or other fine-grained APIs. Pass the user's intent directly to
aiAct
and let Midscene's AI handle the planning and execution.

typescript

// 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');

Assertions, data extraction, and waiting should also be done via

aiAct

— it handles all of these. Do NOT use

aiAssert

aiQuery

aiWaitFor

aiTap

, or

aiInput

separately.

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

typescript

// 用户需求："在搜索框中输入iPhone并点击搜索"

// 错误示例——手动拆解为细粒度API
await ctx.agent.aiInput('search box', { value: 'iPhone' });
await ctx.agent.aiTap('search button');

// 正确示例——直接将意图传递给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?) — Primary API

aiAct(taskPrompt, opt?) —— 核心API

aiAct
is the primary API for all UI operations and state confirmations. It accepts natural language instructions and autonomously plans and executes multi-step interactions.

typescript

// 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');

Phase splitting: If the task prompt is too long or covers multiple distinct stages, split it into separate

aiAct

calls — one per phase. Each phase should be a self-contained logical step, and all phases combined must match the user's original intent.

typescript

// 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 "test@example.com", 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 "test@example.com", change phone to "13800000000", click save');
await ctx.agent.aiAct('verify the save success message appears');

aiAction
is deprecated. Use
aiAct
or
ai
instead.

aiAct

是所有UI操作和状态验证的核心API。**它接受自然语言指令，并自主规划和执行多步交互。

typescript

// UI操作示例
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');

// 状态验证/断言示例——同样使用aiAct
await ctx.agent.aiAct('verify the page shows "Login successful"');
await ctx.agent.aiAct('verify the error message is visible');

**阶段拆分：**如果任务指令过长或包含多个不同阶段，请将其拆分为多个独立的

aiAct

调用——每个阶段对应一个调用。每个阶段应是一个独立的逻辑步骤，所有阶段组合起来需与用户的原始意图一致。

typescript

// 错误示例——指令跨多个页面且步骤过多，AI可能在执行过程中丢失上下文
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 "test@example.com", change phone to "13800000000", click save, wait for success');

// 正确示例——按页面/阶段边界拆分，每个阶段保持在单一逻辑上下文中
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 "test@example.com", change phone to "13800000000", click save');
await ctx.agent.aiAct('verify the save success message appears');

aiAction
已被弃用，请使用
aiAct
或
ai
替代。

Common Mistakes

常见错误

Vague locators —

'button'

is ambiguous; use

'the blue "Submit" button at the top of the page'

Deprecated
aiAction
— use
```
aiAct
```
instead
Ambiguous multi-element targets — specify row/position:
```
'the delete button in the first product row'
```

模糊定位器 ——
```
'button'
```
表述模糊，应使用
```
'页面顶部的蓝色“提交”按钮'
```
这类明确描述
使用已弃用的
aiAction
—— 请使用
```
aiAct
```
替代
多元素目标模糊 —— 请指定行/位置：
```
'第一行产品对应的删除按钮'
```

Agent Configuration —

aiActionContext

Agent配置 ——

aiActionContext

aiActionContext

is a system prompt string appended to all AI actions performed by the agent. Use it to define the AI's role and expertise.

typescript

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

Good examples:

```
'You are a Web UI testing expert.'
```

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

Bad examples:

'Click the login button.'

— specific actions belong in

aiAct()

, not

aiActionContext

```
'The page is in Chinese.'
```
— this is page description, not a system prompt

aiActionContext

是附加到Agent所有AI操作的系统提示字符串，用于定义AI的角色和专业领域。

typescript

// 在setup()中通过agentOptions设置
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.'
```
—— 这是页面描述，不属于系统提示

How to Look Up More

如何查找更多信息

node_modules/@midscene/web

node_modules/@midscene/android

, and

node_modules/@midscene/ios

, find the type definitions for the agent classes

If types are not enough, follow the source references in the
```
.d.ts
```
files to read the implementation code in
```
node_modules
```
Download https://midscenejs.com/llms.txt, then use
```
grep
```
to search for the API or concept you need (the file is large, do not read it in full)

在

node_modules/@midscene/web

、

node_modules/@midscene/android

和

node_modules/@midscene/ios

中查找Agent类的类型定义

如果类型定义不够详细，可通过
```
.d.ts
```
文件中的源引用，查看
```
node_modules
```
中的实现代码
下载https://midscenejs.com/llms.txt，使用`grep`搜索你需要的API或概念（文件较大，请勿完整阅读）

vitest-midscene-e2e

Original

Translation

Vitest Midscene E2E

Vitest Midscene E2E

Modules

模块

Workflow

工作流程

Step 1: Clone boilerplate & ensure project ready

步骤1：克隆模板项目并确保项目就绪

Step 2: Read the Midscene Agent API section below before writing tests

步骤2：编写测试前请阅读下方的Midscene Agent API章节

Step 3: Create, update, or run tests

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

Midscene Agent API

Midscene Agent API

Mandatory Rule: Use
`aiAct`
for User-Described Steps

强制规则：使用
`aiAct`
实现用户描述的步骤

aiAct(taskPrompt, opt?) — Primary API

aiAct(taskPrompt, opt?) —— 核心API

Common Mistakes

常见错误

Agent Configuration —
`aiActionContext`

Agent配置 ——
`aiActionContext`

How to Look Up More

如何查找更多信息

vitest-midscene-e2e

Original

Translation

Vitest Midscene E2E

Vitest Midscene E2E

Modules

模块

Workflow

工作流程

Step 1: Clone boilerplate & ensure project ready

步骤1：克隆模板项目并确保项目就绪

Step 2: Read the Midscene Agent API section below before writing tests

步骤2：编写测试前请阅读下方的Midscene Agent API章节

Step 3: Create, update, or run tests

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

Midscene Agent API

Midscene Agent API

Mandatory Rule: Use aiAct for User-Described Steps

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

aiAct(taskPrompt, opt?) — Primary API

aiAct(taskPrompt, opt?) —— 核心API

Common Mistakes

常见错误

Agent Configuration — aiActionContext

Agent配置 —— aiActionContext

How to Look Up More

如何查找更多信息

Mandatory Rule: Use
`aiAct`
for User-Described Steps

强制规则：使用
`aiAct`
实现用户描述的步骤

Agent Configuration —
`aiActionContext`

Agent配置 ——
`aiActionContext`