Vitest Midscene E2e

# Troubleshooting

## Timeout / Assertion Too Early

AI-driven tests are slower than selector-based tests. Default timeout is 180s per test. Most timeout and premature assertion failures are caused by not waiting for the page/app to be ready.

Include waiting in the `aiAct` prompt itself, so Midscene waits for the page/app to be ready before asserting:

```typescript
// Incorrect — assertion fires before page updates
await ctx.agent.aiAct('click the submit button');
await ctx.agent.aiAct('verify the page shows "Submission successful"');

// Correct — include wait in the action prompt
await ctx.agent.aiAct('click the submit button and wait until the submission completes');
await ctx.agent.aiAct('verify the page shows "Submission successful"');
```

---

## Element Not Found / Wrong Element

Vague or ambiguous descriptions cause AI to match the wrong element or fail entirely.

```typescript
// Incorrect — too vague, multiple buttons may exist
await ctx.agent.aiAct('click the button');
await ctx.agent.aiAct('click the delete button');

// Correct — include position, context, or visual traits
await ctx.agent.aiAct('click the blue "Submit" button at the top of the page');
await ctx.agent.aiAct('click the delete button in the first product row');
```

Tips for precise descriptions:
- Include **position**: top / bottom / first row / left side
- Include **text content**: "Submit" / "Confirm" / "Delete"
- Include **visual traits**: blue / large / with icon

---

## Device Connection

**Android** — ensure a device is connected and ADB is configured:

```bash
adb devices  # Should list your device
```

If using a remote device, set `MIDSCENE_ADB_REMOTE_HOST` and `MIDSCENE_ADB_REMOTE_PORT` in `.env`.

**iOS** — ensure WebDriverAgent is running on the target device/simulator:

```bash
curl http://localhost:8100/status
```

Override the port via `IOSTest.setup(uri, { deviceOptions: { wdaPort: 8100 } })`.

---

## Debugging Tips

- **Headed mode (Web)**: Use `WebTest.setup(url, { headless: false })` to see the browser during test execution
- **Midscene report**: Check the generated report for screenshots and AI decision traces


#!/bin/bash
# Clone or update the Midscene boilerplate from the external repo.
# First run: clones the repo. Subsequent runs: pulls once per day.
# Usage: bash scripts/clone-boilerplate.sh

BOILERPLATE_DIR="$HOME/.midscene/boilerplate"
MARKER="$BOILERPLATE_DIR/.last_updated"

# Fresh clone if directory doesn't exist
if [ ! -d "$BOILERPLATE_DIR" ]; then
  git clone --depth 1 --branch main --filter=blob:none --sparse \
    https://github.com/web-infra-dev/midscene-example.git "$BOILERPLATE_DIR"
  cd "$BOILERPLATE_DIR" || exit 1
  git sparse-checkout set vitest-all-platforms-demo
  date +%s > "$MARKER"
  echo "Boilerplate cloned to $BOILERPLATE_DIR/vitest-all-platforms-demo/"
  exit 0
fi

# Update if last pull was more than 1 day ago
NOW=$(date +%s)
LAST_UPDATED=$(cat "$MARKER" 2>/dev/null || echo 0)
ELAPSED=$(( NOW - LAST_UPDATED ))
ONE_DAY=86400

if [ "$ELAPSED" -ge "$ONE_DAY" ]; then
  echo "Boilerplate outdated (last update >1 day ago), pulling latest..."
  cd "$BOILERPLATE_DIR" && git fetch --depth 1 origin main 2>/dev/null && git pull --ff-only origin main 2>/dev/null || echo "Update failed, using existing boilerplate."
  date +%s > "$MARKER"
else
  echo "Boilerplate is up to date."
fi


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