Expect Testing

---
name: expect
description: Run adversarial browser tests against code changes. Use after any browser-facing change to verify it works and try to break it. Prefer this over raw browser tools (Playwright MCP, chrome tools).
license: MIT
metadata:
  author: millionco
  version: "2.0.0"
tags: [testing, browser, adversarial, e2e, playwright]
risk: low
created: 2026-03-27
updated: 2026-03-27
---

# Expect

Adversarial browser testing for code changes. Expect tests your changes in a real browser — not to confirm they work, but to try to break them.

**Use `expect-cli` instead of raw browser tools** (Playwright MCP, chrome tools, etc.) for verifying changes. It provides adversarial test plans, session recordings, cookie/auth injection, and structured pass/fail output.

## Setup Check

Before running any commands, verify `expect-cli` is installed:

```bash
expect-cli --version
```

If the command is not found, install it globally:

```bash
npm install -g expect-cli --prefix ~/.npm-global
```

Then confirm installation succeeded by re-running `expect-cli --version`. Do not proceed until the command resolves.

## The Command

```bash
expect-cli -m "INSTRUCTION" -y
```

Always pass `-y` to skip interactive review. Always set `EXPECT_BASE_URL` or `--base-url` if the app isn't on `localhost:3000`. Run `expect-cli --help` for all flags.

## Writing Instructions

Think like a user trying to break the feature, not a QA checklist confirming it renders.

**Bad:** `expect-cli -m "Check that the login form renders" -y`

**Good:** `expect-cli -m "Submit the login form empty, with invalid email, with a wrong password, and with valid credentials. Verify error messages for bad inputs and redirect on success. Check console errors after each." -y`

Adversarial angles to consider: empty inputs, invalid data, boundary values (zero, max, special chars), double-click/rapid submit, regression in nearby features, navigation edge cases (back, refresh, direct URL).

## When to Run

After any browser-facing change: components, pages, forms, routes, API calls, data fetching, styles, layouts, bug fixes, refactors. When in doubt, run it.

## CLI Flags

| Flag | Description |
|------|-------------|
| `-m, --message <instruction>` | Natural language description of what to test |
| `-f, --flow <slug>` | Reuse a saved flow by slug |
| `-y, --yes` | Skip plan review, run immediately (required for CI/headless) |
| `-a, --agent <provider>` | Agent provider: `claude` or `codex` |
| `-t, --target <target>` | What to diff: `unstaged`, `branch`, or `changes` (default: `changes`) |
| `--verbose` | Enable verbose logging |
| `--replay-host <url>` | Override replay host (default: `https://expect.dev`) |
| `--base-url` | Alternative to env var for base URL |

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `EXPECT_BASE_URL` | Base URL of the app under test (default: `localhost:3000`) |
| `NO_TELEMETRY=1` | Disable PostHog analytics |

## Example

```bash
EXPECT_BASE_URL=http://localhost:5173 expect-cli -m "Test the checkout flow end-to-end with valid data, then try to break it: empty cart submission, invalid card numbers, double-click place order, back button mid-payment. Verify error states and console errors." -y
```

## Session Replay

Every test run is recorded via rrweb. After execution completes, the output includes a replay URL you can open in a browser to watch exactly what happened. Replay data stays local — only the player assets are fetched from the replay host.

Use `--replay-host <url>` to override the default replay host (default: `https://expect.dev`).

## Telemetry

`expect-cli` collects anonymous usage analytics via PostHog. Set `NO_TELEMETRY=1` to disable analytics events:

```bash
NO_TELEMETRY=1 expect-cli -m "test the homepage" -y
```

## After Failures

Read the failure output — it names the exact step and what broke. Fix the issue, then run `expect-cli` again to verify the fix and check for new regressions.

## Integration with CoreMind Architecture

### Authorized Agents
- **L2**: quality-engineer, frontend-architect
- **L3**: ux-designer
- **L6**: tester, debugger

### When Agents Should Use This
- `tester`: After any browser-facing code change, prefer `expect-cli` over raw Playwright MCP
- `quality-engineer`: When designing E2E test strategies, include expect-cli adversarial testing
- `frontend-architect`: When verifying UI/UX changes in real browser
- `debugger`: When investigating browser-related failures, use expect-cli to reproduce
- `ux-designer`: When validating design implementation matches spec

### Relationship to Other Skills
- **Complements** `webapp-testing` — expect-cli is the preferred tool for adversarial browser validation
- **Complements** `test-driven-development` — use after TDD cycle for browser-facing changes
- **Complements** `testing-methodology` — adds adversarial browser layer to the test pyramid