{"id":"8d66f01c-2a9a-488b-a2d0-1ac6c49c954f","slug":"visiontest","kind":"mcp","name":"visiontest","summary":"Vision Test is an MCP (Model Context Protocol) server that provides a standardized way for AI agents and Large Language Models to interact with mobile devices.","owner":"docer1990","repoUrl":"https://github.com/docer1990/visiontest","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-05-02T00:38:08.000Z","addedAt":"2026-10-21T15:09:14.052Z","logoUrl":"https://avatars.githubusercontent.com/u/68859017?u=d0cd983581cfdec88749f419a4957bdd0ef6f265&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","memory-knowledge"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T15:09:22.707Z","sample":false,"url":"https://conduits.dev/tools/visiontest","language":"Kotlin","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# VisionTest\n\nBuilding a mobile app means moving constantly between code and the app itself.\nYou change a screen, open it on a device, try an interaction, and notice something\nthat sends you back to the editor. That feedback shapes the next change.\n\nWorking with a coding agent adds another participant to this process. The agent\ncan help implement a feature or investigate a bug, and access to the running app\ngives it more context to work with. A reproducible interaction, an observed UI\nstate, or a screenshot can make the next conversation more concrete.\n\nVisionTest grew out of a desire to make that feedback easier to obtain and share.\nIt lets developers and coding agents inspect Android apps and iOS simulators,\nexercise specific flows, and collect evidence about what happened.\n\nThe developer guides the work, chooses what matters, and evaluates the experience.\nVisionTest supports that process with checks that can be repeated as the app changes.\n\n## The thinking behind it\n\nMobile automation already has established tools and frameworks. VisionTest\nfocuses on the checks a developer and a coding agent repeat while changing an\napp. In that workflow, UI observations become model input, extra interactions\nadd latency, and unreliable actions can send the agent through repeated attempts.\nToken consumption, execution time, and flakiness are central design constraints.\n\nThree priorities guide development.\n\n- Keep token consumption focused on the task. Compact, filtered UI results and\n  targeted queries give the agent relevant information. The skill encourages\n  reusing known selectors and reserves screenshots for questions that need images.\n- Keep execution time focused on useful work. Flows batch known actions in one\n  CLI invocation. The skill reuses verified setup and avoids redundant discovery\n  and readiness checks. Built-in waits respond to UI conditions instead of\n  requiring fixed sleeps.\n- Make checks repeatable. Stable selectors, actionability waits, and explicit\n  outcome checks address sources of UI-test flakiness. Structured results expose\n  failures, and an uncertain action outcome must be inspected before retrying.\n\nVisionTest builds on Android's UIAutomator through instrumentation and Apple's\nXCUITest. These native test frameworks expose UI elements and accessibility\nproperties. VisionTest combines that access with structured results and an\nagent workflow designed around these priorities.\n\nThe main development goal is to make everyday checks more reliable and less\nexpensive to repeat. Improvements to token usage, execution time, and flakiness\ntake priority over growing the feature list. New features should solve a concrete\ntesting need and justify the execution and context costs they introduce.\n\nUse the CLI with the project-local VisionTest skill to guide the agent through\nsetup, selector discovery, actions and outcome checks. MCP is also supported\nfor users who prefer a connected tool interface.\n\n## Requirements\n\n- JDK 17 or newer, on macOS or Linux (arm64 or x86_64).\n- Android Platform Tools and an authorized Android device or emulator for Android.\n- macOS, full Xcode and a compatible simulator runtime for iOS. Physical iOS\n  devices are not supported. Prebuilt iOS test bundles are available on macOS arm64.\n- An application built and installed using its own repository's instructions.\n\nVisionTest handles UI testing and its automation server. Your application's\nAGENTS.md or equivalent remains the authority for builds, artifacts, variants and\ninstallation. The skill documents native ADB/simctl commands for lifecycle setup.\n\n## Install and prepare your agent\n\nInstall the latest release:\n\n```bash\ncurl -fsSL https://github.com/docer1990/visiontest/releases/latest/download/install.sh | bash\n```\n\nThe installer verifies downloads and installs the launcher under `~/.local/bin`.\nIt installs the JAR and Android APK pair, plus the prebuilt iOS bundle on macOS\narm64. Add `~/.local/bin` to PATH if needed. See the\n[installation guide](docs/installation.md) for platform setup, custom paths and\nthe iOS source fallback.\n\nIn the application repository, check the installed version and install the skill\nfor the agents you use:\n\n```bash\nvisiontest --version\nvisiontest init --agent claude,opencode,codex\n```\n\n`init` writes self-contained instructions for Claude Code, OpenCode and Codex.\nIt works offline and does not configure MCP. After upgrading VisionTest, rerun\n`init` in each project to replace the selected skill files with the instructions\nembedded in that version. Local edits to those generated files are overwritten.\n\nAsk your agent for a concrete check, for example:\n\n> Test that continuing from the welcome screen opens Home. Follow this project's\n> build instructions, verify the result, and report the evidence.\n\n## A first CLI test\n\nThis Android example assumes the app is already installed. Replace the app ID,\nselector and expected text with values from your app. Check each command's result\nbefore continuing. Install the automation APK pair on first use or after an update;\nreuse a healthy server on subsequent tests.\n\n```bash\nvisiontest available_device -p android --json\nvisiontest install_automation_server -p android\nvisiontest start_automation_server -p android\nvisiontest launch_app -p android com.example.app\nvisiontest get_interactive_elements -p android --compact\n```\n\nIf the complete requested scenario is Continue opening Home, and its starting\nstate, selector and expected result are known, record it even on its first execution.\nBefore every recorded test, close the app on the established device:\n\n```bash\nadb -s \"SERIAL\" shell am force-stop com.example.app\n```\n\nInspect the result, then relaunch separately:\n\n```bash\nvisiontest launch_app -p android com.example.app\n```\n\nCheck the launch result before running the recorded flow. This example assumes the\napp opens on the welcome screen; include any required navigation in the flow:\n\n```bash\nvisiontest flow -p android --record --json \\\n  --step 'tap_on_element --resource-id com.example.app:id/continue' \\\n  --step 'wait_for_element --text \"Home\" --timeout 10000'\n```\n\nInspect the report's `success`, step results and recording status/path. The tap\nwaits for an actionable control; the explicit wait checks that Home appeared.\nNeither a successful tap nor a saved video alone proves the app behaved correctly.\nUse `find_element --json` for an immediate functional check, or `wait_for_element\n--json` to await a change. No fixed sleep or manual polling loop is needed.\nThis also applies after app launch or a swipe. Inspect launch diagnostics before\ncontinuing; await a known ready selector or immediately discover controls if none\nis known. Selector taps and targeted input already wait for actionability.\n\nDuring exploration, batch known actions with `flow --json` without `--record` and\ninspect structured UI data at unknown branches. Start recording only when the\ncomplete scenario, starting state, selectors, data and assertions are defined and\nthat requested test still needs execution. Use one recorded flow for the scenario,\nnot a video per exploratory segment. Termination and relaunch are required before\neach recorded flow, even if the app is already on the correct screen. Unrecorded\nexploration does not require restarting the app. Keep the healthy automation server\nrunning; restarting the app does not clear its persisted data.\nRecording remains an explicit CLI flag and\ncan fail the flow even after successful UI steps. Report user opt-out or concrete\nrecorder, flow or budget limitations before omitting recording from a ready test.\nDo not replay completed checks just to obtain video or routinely analyze recordings.\n\nUse structured CLI results as functional evidence without per-step screenshots.\nCapture screenshots only to document an observed app bug or an assertion the CLI\nqueries cannot resolve, such as pixel appearance or occlusion. State the reason\nfor capture and inspect the image before visual claims. A generic request for\nevidence or a \"visual verification\" label does not require a screenshot when the\nstructured results answer the assertion.\nSee [flows and recording](docs/cli-flow.md) for supported steps and time limits.\n\nAt the end of the testing task, wait for the last flow to return, inspect its\nresults and finalized recording, and collect any needed bug evidence. If the app\nshould be closed and no pending test needs its state, terminate it with the\nestablished device identifier, for example on Android:\n\n```bash\nadb -s \"SERIAL\" shell am force-stop com.example.app\n```\n\nOn iOS, the equivalent is `xcrun simctl terminate \"UDID\" \"com.example.app\"`.\nThese are native commands outside flow. Inspect their exit status and diagnostics;\ndo not close the app while recording finalizes. Finish evidence collection before\nthe mandatory restart for the next recorded test; exploratory flows may reuse state.\nStop the automation server only if you started it:\n\n```bash\nvisiontest stop_automation_server -p android\n```\n\nFor iOS, use `-p ios`, an installed simulator app and the iOS automation bundle;\n`install_automation_server` is Android-only. Scope element commands to the app\nwith `--bundle-id com.example.app`. Flow steps need their own app scope; an outer\n`--bundle-id` scopes observations. See the [iOS setup guide](docs/installation.md)\nand [CLI examples](docs/cli-usage.md).\n\n## How the skill guides testing\n\nThe project-local skill translates these principles into CLI instructions for\nthe agent. It follows the application's build/install instructions and uses\nnative lifecycle commands for deep links, termination and scenario-specific\nresets. Deep links must not skip navigation under test. iOS uninstall/reinstall\ndoes not guarantee removal of Keychain, shared or remote state.\n\nThe [compact inspection evaluation](docs/benchmarks/compact-inspection.md),\n[performance tracing guide](docs/performance.md), and\n[guidance trials](docs/benchmarks/cli-agent-guidance.md) document measurements,\nmethods and limitations. Simulated command choices and smaller payloads alone\ndo not establish token savings or faster end-to-end execution.\n\nVisionTest currently assumes one selected target. There is no CLI device-selection\nflag, and a running backend does not expose its identity for cross-checking against\nnative commands or recording. Configure one intended target consistently.\n\n## Output and command reference\n\nDevice commands require `--platform android` or `--platform ios` (`-p`). `init`,\nroot `--help` and root `--version` do not. Run `visiontest --help` for commands.\n\nPrefer `--json` where supported and `--compact` for selector discovery. JSON\nstdout contains one object without JSON-RPC framing. Diagnostics go to stderr;\nroutine INFO logs are suppressed by default. Do not filter with `grep -v INFO`\nor discard stderr. Check both the exit status and result fields. Standalone\ncommands can return `success:false` or an operation `error` with exit 0;\nflows return nonzero for those failures. An action timeout may leave its outcome\nuncertain, so inspect the app before retrying.\n\n- [Interactions, waits, gestures and exit codes](docs/cli-usage.md)\n- [JSON schemas and compact inspection](docs/cli-json.md)\n- [Sequential flows, evidence and recording](docs/cli-flow.md)\n- [Installation and platform setup](docs/installation.md)\n\n## MCP alternative\n\nMCP exposes supported automation operations to clients that prefer tool discovery.\nCLI commands and MCP tools call shared operation implementations. The flow\nbatching and recording commands described above are CLI features.\n\nConnect VisionTest to an MCP client:\n\n```bash\n# Claude Code\nclaude mcp add visiontest java -- -jar ~/.local/share/visiontest/visiontest.jar\n\n# OpenAI Codex CLI\ncodex mcp add visiontest -- java -jar ~/.local/share/visiontest/visiontest.jar\n```\n\n<details>\n<summary>Configuration for Claude Desktop, Copilot CLI, and OpenCode</summary>\n\nJSON configuration files require an absolute JAR path; they do not expand `~`.\n\nClaude Desktop uses `~/Library/Application Support/Claude/claude_desktop_config.json`\non macOS or `~/.config/Claude/claude_desktop_config.json` on Linux:\n\n```json\n{\n  \"mcpServers\": {\n    \"visiontest\": {\n      \"command\": \"java\",\n      \"args\": [\"-jar\", \"/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar\"]\n    }\n  }\n}\n```\n\nGitHub Copilot CLI uses `~/.copilot/mcp-config.json` and the same server object\nwith `\"type\": \"stdio\"`. OpenCode uses this entry in a project or user\n`opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"visiontest\": {\n      \"type\": \"local\",\n      \"command\": [\"java\", \"-jar\", \"/ABSOLUTE/PATH/TO/.local/share/visiontest/visiontest.jar\"]\n    }\n  }\n}\n```\n\n</details>\n\nFor MCP, launch the JAR without CLI arguments (or with `serve`). Keep stdout\nreserved for the protocol. Use discovered tool schemas instead of CLI flags.\n\n## Configuration\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `VISION_TEST_LOG_LEVEL` | `PRODUCTION` | Error detail: `PRODUCTION`, `DEVELOPMENT`, or `DEBUG` |\n| `VISION_TEST_APK_PATH` | auto-detected | Explicit Android test APK path |\n| `VISION_TEST_IOS_PROJECT_PATH` | auto-detected | Explicit iOS `.xcodeproj` path |\n| `VISIONTEST_DIR` | `~/.local/share/visiontest` | Install directory under `$HOME` |\n\nAndroid uses port 9008 with automatic ADB forwarding. iOS uses port 9009 on the\nsimulator host network.\n\n## Reference\n\n- [CLI contract](docs/agentico/specs/cli.md)\n- [JSON output](docs/cli-json.md)\n- [Tests and performance benchmark commands](benchmarks/README.md)\n- [Local performance tracing](docs/performance.md)\n- [Command benchmarks and baseline collection](docs/benchmarks/http-baseline.md)\n- [Element waits](docs/agentico/specs/element-waits.md)\n- [Element swipe](docs/agentico/specs/element-swipe.md)\n- [Missing interactions](docs/agentico/specs/missing-interactions.md)\n- [Screenshots](docs/agentico/specs/screenshots.md)\n- [Release process](docs/release.md)\n- [1.0.1 release notes](docs/releases/1.0.1.md)\n- [Contributing](CONTRIBUTING.md)\n- [Open issues](https://github.com/docer1990/visiontest/issues)\n\n## License\n\nVisionTest is available under the [MIT License](LICENSE).\n"}