expect-test

Files (1)

• SKILL.md

SKILL.md (first lines)

# Expect Test — AI Browser Testing

Run AI-generated browser tests against your dev server using [expect-cli](https://github.com/millionco/expect). No test files to write — the AI reads your git diff, generates a test plan, and executes it in a real Playwright-driven browser.

## When to Use

- After making UI changes — verify they work visually
- After fixing bugs — confirm the fix in a real browser
- To test user flows (login, navigation, forms)
- As part of `/validate` to add browser verification
- When you need visual confirmation, not just build passes

## Prerequisites

Requires Claude Code (already running if you're reading this).

## Setup & Installation

```bash
# Check if expect-cli is installed
if ! command -v expect-cli &>/dev/null; then
  echo "Installing expect-cli..."
  npm install -g expect-cli@latest
fi

# Verify
expect-cli --version
```

### First-run Playwright browser install (gotcha)

expect-cli ships with its OWN pinned `playwright-core` version. The system-wide `npx playwright install` installs whatever's LATEST, which expect-cli won't find. First-run symptom:

```
Failed to launch browser: ... Executable doesn't exist at
.../chromium_headless_shell-1217/...
```

**Fix** — install via expect-cli's bundled playwright:

```bash
# Headed mode (uses chromium)
node $(npm root -g)/expect-cli/node_modules/playwright-core/cli.js install chromium

# Headless mode (uses chromium-headless-shell)
node $(npm root -g)/expect-cli/node_modules/playwright-core/cli.js install chromium-headless-shell
```

That downloads the exact version expect-cli pins. **Without this, the TUI's LLM-driven planner will detect the missing binary and wander into setup/install tangents that burn 2-3 minutes of tokens on `npx playwright install` + `ls node_modules` + project introspection BEFORE running any actual browser step.**

## Usage

### Auto-detect changes and test

```bash
# Test unstaged changes (default) — auto-detects dev server
expect-cli

# Test with a specific instruction
expect-cli -m "test the login flow works correctly"

# Test a whole branch diff
expect-cli -t branch

# Skip plan review (CI mode)
expect-cli -y

# Show browser window during test
expect-cli --headed

# Verbose logging
expect-cli --verbose
```

### Targeted testing

```bash
# Test specific feature
expect-cli -m "verify the Future/Past toggle on events calendar switches views correctly"

# Test a fix
expect-cli -m "confirm the modal has a solid dark background, not transparent"

# Test a flow
expect-cli -m "sign in as coach, navigate to perform, check events show only future events"
```

## Running in tmux (for agents)

**Always run in tmux** — expect-cli `tui` has an interactive TUI that blocks the terminal.

### CLI syntax changed — use the `tui` subcommand

Recent expect-cli versions (≥0.1.2) moved the test runner under the `tui` subcommand.
`expect-cli -m "..."` without `tui` will print `error: unknown option '-m'`.

```bash
# ✅ CORRECT — tui subcommand
expect-cli tui -m "short description" --browser-mode headed -y

# ❌ WRONG on v0.1.2+
expect-cli -m "short description" --headed -y
```

### TUI is deprecated — prefer the MCP server going forward

On first run, expect-cli prints a banner:
> ⚠ The TUI is deprecated. Use /expect from your coding agent instead. Run `npx expect-cli@latest init` to set up.

For new projects, install the MCP server (`expect-cli init`) so Claude Code can call
the atomic tools (`expect open`, `expect screenshot`, `expect network_requests`, etc.)
directly. The `tui` command still works but will be removed in a future release.

### Safe pattern for long missions (the ONLY way that's robust)

Put the mission in a file via heredoc. Inline `-m "..."` strings with apostrophes,
embedded double-quotes, or newlines break the shell chain: `tmux send-keys` →
`bash -c` → expect-cli argv parser. Symptom: `error: too many arguments for 'tui'. Expected 0 arguments but got 4`.

From stevengonsalvez/ainb-toolkit, MIT.

More from stevengonsalvez/ainb-toolkit