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:

expect-cli --version

If the command is not found, install it globally:

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

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

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:

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