Metadata-Version: 2.4
Name: watchr-mcp
Version: 0.7.1
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** | Finds missing labels, small touch targets, unlabeled buttons |
| **Visual Regression** | Saves golden screenshots, diffs against them to catch UI changes |
| **Performance Timing** | Measures screen load times, flags slow screens (>3s) |
| **Monkey Testing** | Random taps and swipes to find crashes scripted tests would miss |
| **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 |

## Troubleshooting

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