Metadata-Version: 2.4
Name: watchr-mcp
Version: 0.15.0
Summary: iOS, Android & Web QA agent — MCP server for Claude Code
License: MIT
Requires-Python: <3.14,>=3.11
Requires-Dist: fb-idb>=1.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: playwright<2,>=1.55
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# Watchr — iOS, Android & Web QA Agent

AI-powered app testing for iOS, Android, and web. Tell Claude Code what to test in plain English — it drives the simulator/emulator/browser or physical device, finds bugs, checks accessibility, and catches crashes automatically.

## Supported Platforms

| Platform | How it works |
|----------|-------------|
| **iOS Simulator** | `xcrun simctl` + `idb` — auto-detected |
| **iOS Physical Device** | WatchrRunner XCTest server via USB — guided setup |
| **Android Emulator** | `adb` — auto-detected, zero setup |
| **Android Physical Device** | `adb` via USB debugging — auto-detected, zero setup |
| **Web Browser** | Playwright (Chromium, headless) — `device="web"` |

## Install (one time)

```bash
# Add watchr to Claude Code
claude mcp add --scope user watchr -- uvx --python 3.12 --upgrade watchr-mcp
```

That's it. One command. `uvx` downloads everything automatically. The `--scope user` flag makes watchr available in every project.

### Platform-specific prerequisites

**iOS Simulator:**
```bash
brew install idb-companion
```

**Android (emulator or physical):**
- Android Studio installed (for `adb`)
- For physical devices: USB debugging enabled

**iOS Physical Device:**
- Xcode installed, device connected via USB
- Watchr guides you through the one-time XCTest runner setup

**Web (browser testing):**
```bash
pip install playwright && playwright install chromium
```

> If you're missing anything, watchr will tell you exactly what to install when it starts.

## Usage

Open Claude Code in any project and tell it what to test:

```
Boot the simulator, launch com.yourapp.bundleid, and test the sign-up flow
```

Claude Code will:
- Auto-detect your device (iOS simulator, Android emulator, or USB-connected phone)
- Launch your app
- Navigate the flow you described
- Take screenshots at each step
- Report any bugs, crashes, or issues it finds

### Switch platforms manually

If watchr picks the wrong device, tell it:

```
Use set_device with mode "android"
Use set_device with mode "simulator"
Use set_device with mode "physical"
```

## QA After Code Changes

Use watchr as part of your dev workflow — save a baseline before changes, then compare after.

```
"Save a baseline of the home screen called 'home'"
```

Make your code changes, rebuild, then:

```
"Compare the home screen with the baseline 'home' and report any visual differences"
```

For a full regression check after a feature branch:

```
"Launch the app, test sign-up, onboarding, and settings — check for crashes and accessibility issues"
```

Works great in CI or as a pre-merge check. One prompt replaces a manual test checklist.

## Web Testing

Test web apps with the same tools as mobile:

```
"Navigate to https://myapp.com and test the sign-up flow"
```

Or be explicit:
```
navigate("https://myapp.com", device="web")
observe(device="web")
perform(action="tap_element", label="Sign In", device="web")
```

Watchr launches a headless Chromium browser via Playwright. Fast, no extensions needed. Console errors are automatically captured in `observe` output.

## Cross-Platform Testing (iOS + Android + Web)

Test both platforms at the same time — each tool call targets a specific device independently:

```
"Test the sign-up flow on both iOS and Android — report any differences"
```

```
observe(device="simulator")   # iOS screenshot + UI tree
observe(device="android")     # Android screenshot + UI tree
```

No switching, no conflicts. Both devices in the same session.

## Example Prompts

```
"Test the sign-up flow end to end and report any bugs"

"Go to settings, verify all options are visible, check accessibility"

"Run monkey testing on the home screen for 30 seconds"

"Save a baseline screenshot of the landing page, then compare after my changes"

"Navigate to the payment screen and check if the app crashes"
```

## What It Can Do

| Capability | Description |
|-----------|-------------|
| **Navigate any flow** | Describe a user journey in English — it taps, swipes, types, and scrolls through it |
| **Crash Detection** | Checks if the app is still alive after every action, reads crash logs |
| **Accessibility Audit** | Mobile: missing labels & sub-44pt targets. Web: axe-core (WCAG 2.2 AA + best practice) |
| **Visual Regression** | Saves golden screenshots, diffs against them to catch UI changes (mobile + web) |
| **Performance** | Mobile: screen load timings. Web: Core Web Vitals (LCP/INP/CLS) via `perf_audit` |
| **Monkey Testing** | Random taps/clicks and swipes/scrolls to find crashes scripted tests would miss (mobile + web) |
| **Network Mocking** | `mock_route(pattern, status, body, latency, failure_rate)` for fixture replay & chaos (web) |
| **Trace Recording** | `start_trace`/`stop_trace` produce a Playwright trace zip for time-travel debugging (web) |
| **Security Scan** | Checks CSP/HSTS/headers, mixed content, exposed API keys/JWTs in HTML+JS (web) |
| **SEO Audit** | Title/description/canonical/OG/Twitter/JSON-LD/h1/alt coverage (web) |
| **Text Verification** | Asserts specific text is on screen, like Playwright's `expect` |
| **Auto Bug Reports** | Files GitHub issues automatically with device info and error context |
| **Personas** | `define_persona` + `use_persona` — run flows as different archetypes (first-time visitor, screen-reader user, mobile-only) with isolated cookies/storage per persona. Locale, timezone, viewport, UA, network throttle baked in. |
| **Usability Audit** | `usability_audit` — Nielsen heuristics + Fitts/Hick + WCAG cognitive criteria, deterministic DOM scan (web) |
| **Frustration Signals** | `install_frustration_tracking` + `read_frustration_signals` — rage-clicks, dead-clicks, hesitations, back/forward regret signals (web) |

## First run / troubleshooting

After installing, check your setup from a terminal:

```bash
watchr-mcp --doctor    # report what's ready vs missing, with fix commands
watchr-mcp --setup     # the above, and auto-install the safe dependencies
```

If watchr "doesn't connect," run `watchr-mcp --doctor` — it works independently of the
MCP connection and tells you exactly what to install (Playwright browser, Xcode tools,
idb, Android SDK, a booted simulator/emulator, …).

| Problem | Fix |
|---------|-----|
| MCP server won't start | Run `uvx watchr-mcp` in terminal to see errors |
| "No booted simulator found" | Boot one: `xcrun simctl boot "iPhone 16 Pro"` |
| "No Android device found" | Start an emulator or connect device with USB debugging |
| `idb` commands fail | Run `idb connect UDID` with your simulator's UDID |
| Screenshots are blank | Make sure the Simulator/Emulator is open and visible |
| Physical device not working | Run `setup_device("your.bundle.id")` and follow the guide |

## Update

Watchr updates automatically — `uvx` fetches the latest version from PyPI each time Claude Code starts the server.

To force an update:
```bash
uvx --upgrade watchr-mcp
```
