Visual Intelligent Smartphone Test Operator
Describe a mobile test in plain language. An AI looks at the screen, taps through your app and tells you whether it actually works.
No selectors. No page objects. No brittle scripts that break when a button moves.
A real run on a USB-connected Android phone, recorded from the web console: one goal, the AI's reasoning as it works, then its verdict. The waiting between steps is sped up 4Γ.
Warning
Visto is a work in progress. Android and iOS work end to end today, from the CLI and the web console. iOS needs more setup than Android (a Mac with Xcode and a signed WebDriverAgent; see Quick start (iOS)). APIs, prompts and storage formats may still change. Early testers and contributors are very welcome.
Traditional mobile end-to-end tests describe how to click: element IDs, XPath, waits, retries. They break whenever the UI changes, and a green run only shows that the clicks happened.
Visto starts from the goal:
Goal: Create a note titled "Groceries".
Expected result: The note appears at the top of the list.
Constraints: Do not delete existing notes.
One multimodal AI conversation then takes over:
- Observe: take a fresh screenshot of the real device.
- Judge: did the previous action have the intended effect?
- Plan: adjust the plan to what is actually on screen.
- Act: issue one typed command (tap, swipe, type, backβ¦), or wait, or ask you a question.
- Conclude:
passed,failedorinconclusive, with a short explanation that cites the observations it relied on.
flowchart LR
G([Your goal]) --> O[Observe<br/>screenshot]
O --> J{Judge previous<br/>effect}
J --> P[Adapt plan]
P --> A[Act<br/>one typed command]
A --> O
P -->|enough evidence| C([passed / failed / inconclusive<br/>with cited evidence])
P -.->|unsure| Q[/Ask you a question/]
Q -.-> P
| π― Goal-driven tests | Describe goal, expected result and constraints in natural language, or dictate them by voice. |
| π Vision first | The AI reasons on screenshots like a human tester, so tests survive layout changes, redesigns and A/B variants. |
| βοΈ AI-owned verdicts | A successful tap never counts as a successful test. The AI judges every effect and decides the semantic outcome. |
| π§Ύ Traceable evidence | Every decision is linked to the screenshots that led to it. Export runs as HTML or JSON reports. |
| π Distinct outcome types | Product failure, insufficient evidence, device/provider infrastructure failure and user cancellation are kept apart. |
| ποΈ Live control | Pause, resume or cancel a run, and answer the AI's questions from the web console. |
| πΈ Budgets and costs | Hard caps on wall time, actions and inferences. Run statistics with cost estimates from daily-updated prices. |
| π Safe by design | The AI cannot reach a shell, only typed, timeout-bound device commands. One owner per device. Uncertain mutations are never retried blindly. |
| π» Runs on your machine | Backend, console and Appium run locally: Windows, Linux or macOS for Android, macOS for iOS. |
| Platform | Status | Device backend |
|---|---|---|
| Android | β Working (8.0 / API 26+, USB or wireless debugging) | Appium + UiAutomator2, adb |
| iOS | β Working on a real iPhone by USB cable (macOS with Xcode only). One-time signing setup required: see Quick start (iOS). Simulators are supported but not yet exercised live | Appium + XCUITest, WebDriverAgent |
The core is platform-agnostic by design. The domain and application layers know about observations and commands, not about Android. The iOS adapter is a second device adapter behind the same port; the AI loop stays the same.
You need:
- uv, the only tool you install by hand (it also provides Python);
- an API key for one AI provider: OpenAI, Anthropic or Google Gemini;
- an Android 8+ device with USB debugging enabled, connected and authorized.
Copy the wheel URL of the release you want from the releases page, then:
uv tool install https://github.com/alevittoria/visto/releases/download/v<version>/visto-<version>-py3-none-any.whl
uv tool update-shell # once: puts uv's tool folder on PATH; then open a new terminal
visto start # first start downloads Node, a JDK, the Android SDK tools and AppiumIf visto is not recognised as a command, the terminal was opened before
uv tool update-shell: open a new one. The first visto start asks you to accept
the Android SDK license and installs its toolchain into ~/.visto; later starts
reuse it. Visto installs nothing system-wide and changes no environment variable;
Android Studio is not needed. start runs Appium and opens the console at
http://127.0.0.1:8000/. While no provider key is configured, the console opens on
its Settings page: choose the AI provider and paste its API key there, then pick your device, describe the
goal and start the run. visto doctor checks the setup when something does not
work.
- Full installation guide, proxies, upgrade and uninstall: installation
- Device preparation and wireless debugging: Android setup
- iOS simulators and iPhones (macOS only): Quick start (iOS)
- First run from the terminal CLI: first device tests
- Web console guide: web console
iOS takes more preparation than Android, because Apple only lets a phone be driven through WebDriverAgent, a small test app that you sign with your own Apple account and install on the phone. Visto cannot do that step for you. Plan about half an hour the first time; afterwards a run starts like on Android.
You need:
- a Mac with Xcode installed and opened once (it accepts its license and installs its components);
- an Apple ID added in Xcode (Settings βΊ Accounts); a free personal team is enough;
- for a physical phone, a USB cable: the phone is reached only by cable, not over Wi-Fi;
- Visto installed as in the Android quick start. On a Mac,
the first
visto startalso installs the iOS driver.
A simulator needs no signing: boot it from Xcode (or
xcrun simctl boot <simulator-id>), then pick it in the console. Steps 1β4 below
are for a physical iPhone.
1. Prepare the phone (once). Connect it by cable, unlock it and tap Trust when it asks to trust the Mac. Turn on Developer Mode (Settings βΊ Privacy & Security βΊ Developer Mode; the phone restarts and asks you to confirm) and UI Automation (Settings βΊ Developer).
2. Build and install WebDriverAgent (once, then again when the signature expires).
- Run
visto doctor(or open the console's Settings page) and note the WebDriverAgent project path. Open that.xcodeprojin Xcode. - Select the
WebDriverAgentRunnertarget βΊ Signing & Capabilities: choose your team and change the bundle identifier to one unique to you, for examplecom.<yourname>.WebDriverAgentRunner. Choose the same team forWebDriverAgentLib. - Pick the
WebDriverAgentRunnerscheme and your phone as destination, then run Product βΊ Test. Stop it once the runner app is installed on the phone. - On the phone, trust your developer certificate: Settings βΊ General βΊ VPN & Device Management βΊ Apple Development: β¦ βΊ Trust.
3. Tell Visto how WebDriverAgent was signed. In the console's Settings βΊ iOS signing (shown only on macOS), fill in and save:
| Field | Value |
|---|---|
| Development team ID | your team ID (Xcode βΊ Settings βΊ Accounts) |
| Signing identity | Apple Development (not the full certificate name) |
| WebDriverAgent bundle ID | the bundle identifier you chose in step 2 |
| Use a prebuilt WebDriverAgent | ticked |
| Derived data folder | the ~/Library/Developer/Xcode/DerivedData/WebDriverAgent-β¦ folder of that build |
4. Start Visto and run. visto start asks for your Mac administrator
password once: on macOS it opens the tunnel through which Appium reaches iPhones
with iOS 17 or later, and that needs root. (--no-ios-tunnel skips it, but then only
simulators and Android work.) Before every run, connect the phone by cable, unlock
it and open the app under test in its starting state. Visto neither installs nor
launches apps. Then pick the iPhone in the console and start the run. Do not rotate
or touch the phone while the run is going.
Note
With a free Apple team the signature expires after seven days. When runs
stop starting, repeat step 2 (the same values work) and trust the profile on the
phone again. Repeat step 2 as well after a Visto release that updates the iOS
driver: visto doctor and the Settings page say when that is needed.
If a run ends with xcodebuild failed with code 65 or Unable to launch WebDriverAgent, it is almost always the signing setup: an untrusted profile, a
wrong derived data folder or a full certificate name as signing identity. The
iOS setup guide maps each error to
its fix and covers the tunnel, simulators and recovery in detail.
Important
Screenshots, goals and the AI's reasoning are sent to the configured AI provider and stored locally as run history. Use test devices, test accounts and synthetic data. See provider setup and artifact storage.
React console ββ ββ CLI
βΌ βΌ
βββββββββββββββββββββ FastAPI / runner ββββββββββββββββββββββ
β adapters AI provider Β· Android + iOS (Appium) Β· SQLite β
β screenshots Β· reports Β· pricing β
β βββββββββββββββββββββββββββββ β² ββββββββββββββββββββββββ β
β application one conversational run loop, budgets, β
β cancellation, pause/resume, questions β
β βββββββββββββββββββββββββββββ β² ββββββββββββββββββββββββ β
β domain immutable runs, observations, commands β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- Stack: Python 3.12 + FastAPI, React + TypeScript (Vite), SQLite, Appium.
- Clean Architecture:
domain β application β adapters. The core never imports FastAPI, Appium, provider SDKs or database drivers, so a provider, a storage engine or a device platform can be swapped. - Deliberately absent: no hard-coded UI predicates, label dictionaries or app-specific verification rules. Semantic judgement belongs to the AI; technical validity, locks, cancellation and budgets belong to code.
More: architecture Β· product vision Β· API contract Β· report export.
- Conversational AI run loop with AI-owned verdicts
- Android device adapter (Appium/UiAutomator2)
- Terminal CLI, web console, HTML/JSON reports
- Voice dictation, run statistics and cost estimates
- iOS device adapter (Appium/XCUITest)
- iOS verified against real devices
- OpenAI, Anthropic and Google Gemini providers (Anthropic and Gemini not yet run live)
- Attached reference files (PNG, JPG, PDF), for example layouts the AI compares with each screen (not yet run live)
- Labelled evaluation suite to measure judgement quality across models
- CI-friendly headless mode and exit codes for pipelines
- Optional accessibility-tree observations (as extra data, never as a verifier)
- Batches of tests and scheduling
Contributions are very welcome. Good first areas: new AI providers, console UX, documentation, and real-world test scenarios built on fictional sample apps.
Read CONTRIBUTING.md to set up the project, run the checks
(python scripts/verify.py) and open a pull request. Bug reports and ideas go in
GitHub issues. Report security issues privately as described in
SECURITY.md.
This repository is developed with role-based AI coding agents. AGENTS.md and docs/ai-context hold the instructions, architecture notes and current status they work from. Human contributors can ignore them or use them as a map of the codebase.
MIT Β© 2026 Alessandro Oddo and Visto contributors.