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)
# 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:
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):
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) |
| Screenshots to Disk | screenshot(save_path="~/bug.jpg") writes a full-resolution JPEG to a file (and still returns the image inline) — for bug reports, galleries, diffs, or handoff (all platforms) |
| 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:
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:
uvx --upgrade watchr-mcp
1 maintainer
Release files for watchr-mcp 0.28.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| watchr_mcp-0.28.0.tar.gz | 162.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| watchr_mcp-0.28.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 315.2 kB
Release files / watchr_mcp-0.28.0.tar.gz
| Download URL | watchr_mcp-0.28.0.tar.gz |
|---|---|
| Size | 162.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f038cdc6fe3863932aa43d24fde9781bd93e0829311c39359aca679689e3f843
|
|
BLAKE2b-256 checksum How to use checksums |
4cb0176d284f7735f6a6e54c1f67957aac990190a846ce161a33b83de4400970
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / watchr_mcp-0.28.0-py3-none-any.whl
| Download URL | watchr_mcp-0.28.0-py3-none-any.whl |
|---|---|
| Size | 152.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a55f7e567b776241ee8ff7da971093cf8ae292247c9121a8f624acd35641237
|
|
BLAKE2b-256 checksum How to use checksums |
08f035d15514aa45e8005d29140d62bf68449e2964ce894f4e707bea205ac2b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
