Get started
Verify
Run code-driven end-to-end checks on Revyl browsers, devices, and computers
Verify is an open-source SDK for end-to-end checks on Revyl. Write natural-language instructions and validations for a cloud browser, iOS simulator, or Android emulator, and call them from a script, a test runner, a coding-agent loop, or CI. The same library runs commands and works with files on Mac computers.


To have a coding agent set it up, give it this prompt:
Set up Verify in this project.
Read https://docs.revyl.com/verify.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.
Use the SDK for this project's language: @revyl/verify on Node.js 22.18 or later for Node.js or TypeScript, revyl-verify on Python 3.10 or later for Python (install it with pip or uv), or the github.com/RevylAI/verify/go module for Go. Write the iOS Settings example in that language: open the com.apple.Preferences bundle, run one instruction, and run one validation that checks the operating system version. Ask before starting a paid cloud session, then run the example.
You're done when the example has opened iOS Settings, the operating system version validation has passed, and the session has closed.
Ask me before anything that needs my login or approval.import { open } from '@revyl/verify';
const session = await open({
platform: 'ios',
app: { bundleId: 'com.apple.Preferences' },
});
try {
await session.instruction('Open General, then About');
await session.validation('The screen shows the operating system version');
await session.screenshot({ path: '.verify/screen.png' });
} finally {
await session.close();
}Steps describe what to do and what must be true, not selectors, and every run gives you a live viewer link, ordered step results, and a report after the session closes.
Quick start
npx @revyl/verify init --platform iosThe initializer installs Verify with your project's package manager (npm, pnpm, or Yarn, including Plug'n'Play projects), writes verify.config.ts and verify/example.mts, adds .verify/ to .gitignore, and prints the command that runs the example. --platform picks the target: web, ios, android, or mac. In a terminal you can leave it out and answer the question instead; a coding agent or CI job has no terminal, so it must pass --platform. Without an app ID, the iOS and Android examples open the built-in Settings app by bundle ID; pass --app-id to open your own uploaded app. Web targets need a Revyl Web app ID, created as in Web builds, and a public HTTPS URL because the cloud browser cannot reach localhost. With --url set to your own site, the web example only checks that the page loads; replace it with your own steps.
A config is optional. To run the example above as is, install the package with npm install @revyl/verify, save the example as verify/check.mts, and run node verify/check.mts. Use appId instead of bundleId to open your own uploaded app. To pick the simulator or emulator, add device: { model: 'iPhone 16', osVersion: 'iOS 18.5' } or device: { model: 'Pixel 7', osVersion: 'Android 14' } to the target, with the names Revyl uses. A model or OS version Revyl doesn't offer throws INVALID_ARGUMENT listing the ones it accepts, and no session starts.
On the first interactive run, Verify opens the Revyl browser approval flow once and saves the login in ~/.revyl/credentials.json for the CLI and SDK to share. It then prints progress like this (durations vary):
[verify] ios: starting ios session https://app.revyl.ai/sessions/…
[verify] ios: ready
[verify] ios: ✓ instruction "Open General, then About" (12.0s)
[verify] ios: ✓ validation "The screen shows the operating system version" (9.8s)
[verify] ios: closedThe session URL is the live viewer while the run is active and the report afterward. A failed validation throws VALIDATION_FAILED with the step and the reason, so an uncaught failure makes the script exit non-zero; keep the try/finally block so the session closes when a step fails.


CI
In a non-interactive process or a job with CI set, Verify never opens a browser. Set REVYL_API_KEY through the job's secret store and never put a key in source, argv, or logs; Authentication explains how to create one. A failed instruction or validation exits non-zero and fails the job:
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 24
cache: npm
- run: npm ci
- run: node verify/example.mts
env:
REVYL_API_KEY: ${{ secrets.REVYL_API_KEY }}Inside a revyl-macos job, currentComputer() attaches to the job's computer without creating or owning one. See Use the Verify SDK in a Mac CI job.
Exact actions
When you know exactly what to press, skip the agent. Tap, double-tap, long-press, drag, type, swipe and press keys yourself, by a description Revyl locates on screen or by coordinates, in the same script as your steps. Early access, since TypeScript (@revyl/verify) 0.4.0, Python (revyl-verify) 0.2.0 and Go v0.3.0. doubleTap, longPress, drag, typeFocused, goHome, and Web keys and modifiers in pressKey, are new in TypeScript 0.5.0, Python 0.3.0 and Go v0.4.0. On a Mac computer's screen, tap (by point or by description), screenSize, typeFocused and pressKey are new in TypeScript 0.6.0, Python 0.4.0 and Go v0.5.0. The Python and Go READMEs show the same calls with each language's names.
On iOS Settings:
import { open } from '@revyl/verify';
const session = await open({ platform: 'ios', app: { bundleId: 'com.apple.Preferences' } });
try {
await session.tap({ target: 'General row' }); // Revyl finds the element you describe
await session.tap({ target: 'About row' });
await session.validation('The screen shows the operating system version');
await session.tap({ target: 'Back button' }); // iOS has no back(), so tap the button
await session.tap({ target: 'Back button' });
await session.swipe('down'); // the finger moves down, so the list scrolls to the top
const search = await session.locate('Search field'); // a point in screenshot pixels
await session.tap(search); // a tap by coordinates
await session.type(search, 'Accessibility');
await session.pressKey('enter');
await session.instruction('Open the Accessibility result'); // hand the fuzzy part to the agent
await session.validation('The Accessibility settings are shown');
await session.goHome(); // the home screen
await session.longPress({ target: 'Settings app icon' }); // press and hold, 1.5 s by default
await session.validation('A menu for the Settings app is shown');
await session.goHome();
await session.launchApp('com.apple.Preferences');
await session.drag({ target: 'General row' }, { target: 'Search field' }); // the list follows the finger
} finally {
await session.close();
}On a web store:
import { open } from '@revyl/verify';
const session = await open('web'); // https://www.saucedemo.com in examples/web-store
try {
await session.type({ target: 'Username field' }, 'standard_user'); // Revyl finds the element you describe
await session.type({ target: 'Password field' }, 'secret_sauce');
await session.pressKey('enter');
await session.validation('A list of products is shown');
await session.swipe('up'); // the finger moves up, so the page scrolls down
await session.instruction('Add the Sauce Labs Onesie to the cart'); // hand the fuzzy part to the agent
await session.swipe('down'); // back to the top, so the cart icon is on screen
const cart = await session.locate('Shopping cart icon'); // where Revyl finds it, in screenshot pixels
await session.tap(cart); // a tap by coordinates
await session.validation('The cart lists the Sauce Labs Onesie');
await session.back(); // browser history
await session.validation('A list of products is shown');
await session.tap({ target: 'Open Menu button' });
await session.pressKey('escape'); // closes the menu
await session.validation('The side menu is closed');
await session.doubleTap({ target: 'Products heading' }); // a double-click
await session.pressKey('a', { modifiers: ['ctrl'] }); // a chord: a lowercase letter or digit with modifiers
} finally {
await session.close();
}On Web, typeFocused(text) types into the field that already has focus, without clicking, and replaces its text unless you pass { clear: false }; focus the field first with tap() or pressKey('tab'). For shortcuts such as select all, copy and paste, use 'ctrl': Revyl's cloud browser is Chromium on Linux, where 'meta' is not Command, so Meta+A does nothing. On iOS and Android it throws NOT_AVAILABLE_ON_PLATFORM, so type with type(location, text), which taps the field first.
On a Mac computer, click, type and press keys at points you read off screenshot():
import { open } from '@revyl/verify';
const computer = await open({ platform: 'mac' });
try {
await computer.writeFile('notes.txt', 'Notes\n');
await computer.exec(['open', '-a', 'TextEdit', 'notes.txt']); // exec runs in the workspace
await new Promise((resolve) => setTimeout(resolve, 3_000)); // let the window open
await computer.screenshot({ path: '.verify/mac.png' }); // open it and find the text
await computer.tap({ x: 400, y: 300 }); // the point as you read it
await computer.typeFocused('First line\nSecond line', { clear: false });
await computer.pressKey('a', { modifiers: ['meta'] }); // Command+A selects all
await computer.typeFocused('Replacement', { clear: false }); // typing replaces the selection
} finally {
await computer.close();
}Screen sizes differ between computers, so read the size with screenSize() instead of assuming one. On a computer, typeFocused needs { clear: false }: it types where the cursor is and clears nothing, so select text first to replace it. 'meta' is Command and 'alt' is Option there, unlike Web. tap({ target: 'the Help menu in the menu bar' }) clicks a description and returns the point it clicked. It takes several seconds and can click a look-alike, or something else when the target isn't on the screen, so check the point or take a screenshot afterwards, and use tap({ x, y }) from a screenshot for anything that's hard to undo. locate() isn't available on computers. A script keeps control of the screen for 120 seconds after its last action, so a teammate can't take control in the viewer until then; while someone does, actions throw SESSION_BUSY and nothing happens. The computer guide lists the screen's errors.
Which call works where
| Call | Web | iOS | Android | Mac computer |
|---|---|---|---|---|
tap({ x, y }), tap({ target }), screenSize | Yes | Yes | Yes | Yes |
locate | Yes | Yes | Yes | No, use tap({ target }), which returns the point it clicked, or read the point off screenshot() |
doubleTap, longPress, type, swipe, drag | Yes | Yes | Yes | No |
pressKey(key, { modifiers }) | Yes: 'enter', 'backspace', 'tab', 'escape', arrows and more, with modifiers | 'enter' and 'backspace' only | 'enter' and 'backspace' only | Yes: the Web keys and modifiers, where 'meta' is Command |
typeFocused(text, { clear }) | Yes, types into the focused field | No, use type(location, text) | No, use type(location, text) | Yes, with { clear: false } |
back() | Yes, browser history | No, tap the on-screen back control | Yes, the system back button | No |
goHome() | No, use openUrl or navigate | Yes, the home screen | Yes, the home screen | No |
openUrl(url) | Yes, loads an http(s) URL in the tab | Yes, a URL or deep link | Yes, a URL or deep link | No |
launchApp(bundleId) | No, use openUrl or navigate | Yes | Yes | No |
navigate(url) | Yes | No, use openUrl | No, use openUrl | No |
instruction, validation, your own model | Yes | Yes | Yes | No, use exec() and the screen calls above |
screenshot() | Yes | Yes | Yes | Yes |
exec, files, processes | No, open a Mac computer | No, open a Mac computer | No, open a Mac computer | Yes |
Prefer a description, such as tap({ target: 'Sign in button' }): Revyl finds the element on the current screen, and you never handle coordinates. Otherwise a point is { x, y } in screenshot pixels on every platform: whole numbers from the top-left corner of the image screenshot() returns. So a position you read off a screenshot goes to tap(), type(), swipe() and every other exact action unchanged. screenSize() returns the screenshot's width and height, and locate() and the points tap(), doubleTap(), longPress() and type() return use the same pixels. A point outside the screenshot is refused with INVALID_ARGUMENT before any action is sent, and the message names the valid range. On iOS, Verify converts the pixels to the screen's points for you. On Web they equal CSS pixels at the default device scale factor of 1, and you still pass screenshot pixels at any other. This holds from TypeScript 0.4.1, Python 0.2.1 and Go v0.3.1; earlier versions took iOS points. On a Mac computer a point is in screenshot pixels too, and tap({ target }) returns the point it clicked in the same pixels. Verify refuses a negative or fractional point before sending it, and Revyl refuses one past the screen's edge without clicking; both throw INVALID_ARGUMENT naming the valid range.
A call a platform doesn't support throws NOT_AVAILABLE_ON_PLATFORM, and its message names the alternative.
A failed action throws ACTION_FAILED. One whose outcome Revyl can't confirm throws ACTION_UNCERTAIN or TIMEOUT, so check the session before acting again. Actions are never repeated. If Verify can't reach Revyl, the action fails with API_ERROR and isn't resent either, so check the session before trying it again. Exact actions return when Revyl has accepted them, not when the screen has finished changing. After swipe, drag, goHome, openUrl or launchApp, let the screen settle or check it before you locate or tap coordinates. locate returns Revyl's best match on the current screen and can return a point for an element that is off screen, so bring the element on screen first. A point outside screenSize() is off screen, and an action at it is refused. The mobile and web guides cover locations and platform differences, and the API reference lists every call. With your own model, your model uses tap, doubleTap, longPress, type, swipe, drag, pressKey, openUrl and, where the platform has them, typeFocused, back and goHome inside instruction().
Your own model
Steps run on Revyl's agent unless you pass a model. With open('ios', { model: 'anthropic/claude-sonnet-5-5' }) the agent loop runs on your machine with your key, and Revyl provides the device and finds the elements your model names. Use your own model covers the providers, picking a model, what Revyl still sees, limits and troubleshooting. Early access, since TypeScript (@revyl/verify) 0.4.0, Python (revyl-verify) 0.2.0 (model=) and Go v0.3.0 (verify.WithModel); see the Python and Go READMEs.
Packages
| Package | Install | Status |
|---|---|---|
@revyl/verify | npm install @revyl/verify | TypeScript SDK and CLI, 0.6.2 on npm. Node.js 22.18 or later. |
| Go module | go get github.com/RevylAI/verify/go@v0.5.2 | v0.5.2, versioned separately from npm. Go 1.26.9 or later. |
revyl-verify | pip install revyl-verify or uv add revyl-verify | 0.4.2 on PyPI, versioned separately from npm. Python 3.10 or later; like TypeScript, the first interactive open() signs in through the browser and the session prints its live link to stderr. See the Python guide. |
Platforms
| Platform | Instructions and validations | Exact actions | Commands, files, and processes | Screenshots |
|---|---|---|---|---|
| Web | Yes | Yes | — | Yes |
| iOS simulator | Yes | Yes | — | Yes |
| Android emulator | Yes | Yes | — | Yes |
| Mac computer | — | Screen only | Yes | Yes |
Which call works where breaks exact actions down by call.
Web is available to every organization.
Each instruction and validation runs the agent again; there is no replay cache or shared memory between steps. Keep steps short and describe visible outcomes rather than implementation details.
Mac computers are available on request: contact support@revyl.ai. Organizations on a paid plan, Pro included, already have them. Computers use exec(argv), file, process, screenshot, and screen calls (tap, typeFocused, pressKey) instead of instructions and validations; check the computer guide before using one.


Reference
The TypeScript reference for 0.6.2 lives with the package: API, configuration, computers, and errors. The npm package also ships these pages in node_modules/@revyl/verify/docs/. For Go, see the Go SDK guide. To use Revyl from an IDE or coding agent, see MCP and IDE setup.