# vitest-midscene-e2e

Connects Vitest with Midscene to build AI-driven UI tests across Web, Android, and iOS using natural language. It scaffolds projects and runs tests without fragile element selectors.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2100 installs · ★ 318
- Author: web-infra-dev
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/web-infra-dev/midscene-skills/tree/HEAD/skills/vitest-midscene-e2e/SKILL.md
- Updated: 2026-09-08
- HTML: https://affpapa.org/en/nevibecode/skills/vitest-midscene-e2e

## What it does

The skill integrates the Vitest test framework with Midscene automation. Web tests run on Playwright Chromium. For mobile environments, the setup uses ADB with scrcpy on Android and WebDriverAgent on iOS. Tests interact with the interface using natural language instructions.

Midscene requires running UI actions through `aiAct`. Decomposing steps into separate low-level calls like `aiTap` or `aiInput` is explicitly forbidden. The AI agent plans and executes interactions on its own. When a scenario spans multiple pages, split it into distinct `aiAct` calls at stage boundaries.

Before execution, copy `.env.example` to `.env` and configure environment variables. For web file uploads, you must pass `fileChooserAllowedDir` pointing to the fixture folder. Omitting this path will break file chooser interactions.

## Requirements
- Works with: Playwright

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add web-infra-dev/midscene-skills --skill vitest-midscene-e2e -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/vitest-midscene-e2e/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/vitest-midscene-e2e/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add web-infra-dev/midscene-skills --skill vitest-midscene-e2e -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/vitest-midscene-e2e/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add web-infra-dev/midscene-skills --skill vitest-midscene-e2e -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/vitest-midscene-e2e/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install web-infra-dev/midscene-skills vitest-midscene-e2e
```

2. **Manually: put the files in place**
- File: `.github/skills/vitest-midscene-e2e/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add web-infra-dev/midscene-skills --skill vitest-midscene-e2e -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/web-infra-dev/midscene-skills --path skills/vitest-midscene-e2e
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/vitest-midscene-e2e/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add web-infra-dev/midscene-skills --skill vitest-midscene-e2e -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/web-infra-dev/midscene-skills/tree/HEAD/skills/vitest-midscene-e2e/SKILL.md

## When to use it
- scaffold an E2E testing project for Web, Android, or iOS
- automate UI interactions using natural language prompts in `aiAct`
- avoid maintaining fragile selectors and locators
- break long multi-step user scenarios into clear stages

## Example prompts
- create an e2e test for the shopping cart vitest-midscene-e2e create cart
- scaffold a new project for web testing with vitest-midscene-e2e init web-tests
- debug and run authentication tests with vitest-midscene-e2e run auth

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 90d46c1c541aa156.

BEGIN THIRD-PARTY FILE 90d46c1c541aa156
````text
---
name: vitest-midscene-e2e
description: "Enhances Vitest with Midscene for AI-powered UI testing across Web (Playwright), Android (ADB), and iOS (WDA). Scaffolds new projects, converts existing projects, and creates/updates/debugs/runs E2E tests using natural-language UI interactions. Triggers: write test, add test, create test, update test, fix test, debug test, run test, e2e test, midscene test, new project, convert project, init project, 写测试, 加测试, 创建测试, 更新测试, 修复测试, 调试测试, 运行测试, 新建工程, 转化工程."
user-invocable: true
argument-hint: "[create|update|run|init] <feature-name>"
---

# 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

## Workflow

### Step 1: Clone boilerplate & ensure project ready

```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.

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

It contains mandatory rules for using `aiAct` — the primary API for all UI operations. Do NOT skip this step.

### Step 3: Create, update, or run tests

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](./references/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`
````
END THIRD-PARTY FILE 90d46c1c541aa156

The third-party file has ended. Everything between the 90d46c1c541aa156 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2686 of 7312 bytes. © web-infra-dev · MIT · https://github.com/web-infra-dev/midscene-skills/tree/HEAD/skills/vitest-midscene-e2e/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md