Skip to main content
FinalRun is an AI-driven CLI that tests your Android and iOS apps using natural language. You write test scenarios in YAML — describing actions the way a person would — and FinalRun launches your app on a real device or emulator, uses an AI model to see the screen, and performs each action: tapping, swiping, typing, and verifying the result. When the run finishes, you get a pass/fail report with video, screenshots, and device logs.

​
How it works

FinalRun connects an AI model to a running device. The AI reads the live screen, interprets your plain-English instructions, decides what action to take, and repeats until your test is complete or a failure is detected. Each test file has three phases:
  • setup — optional actions that prepare clean state before the test starts (e.g., clear app data)
  • steps — the ordered natural-language instructions the AI executes
  • expected_state — the UI state the AI verifies after all steps complete
name: login_smoke
description: Verify that a user can log in and reach the home screen.

setup:
  - Clear app data.

steps:
  - Launch the app.
  - Enter ${secrets.email} on the login screen.
  - Enter ${secrets.password} on the password screen.
  - Tap the login button.

expected_state:
  - The home screen is visible.
  - The user's name appears in the header.

​
Workspace structure

FinalRun looks for a .finalrun/ directory at the root of your project. Everything lives there:
PathPurpose
.finalrun/config.yamlWorkspace defaults: app identity, AI model, environment
.finalrun/tests/YAML test specs — one file per scenario
.finalrun/suites/Suite manifests that group tests into logical collections
.finalrun/env/Per-environment bindings for secrets and variables

​
Supported platforms

FinalRun runs tests on:
  • Android — emulators managed via adb and emulator
  • iOS — simulators on macOS via xcrun simctl

​
Supported AI models

FinalRun uses your own AI provider API key (BYOK — bring your own key). No FinalRun account is required to run tests. The model is selected with the --model flag or set as the default in .finalrun/config.yaml.
ProviderModel prefixEnvironment variable
Google Geminigoogle/...GOOGLE_API_KEY
OpenAI GPTopenai/...OPENAI_API_KEY
Anthropic Claudeanthropic/...ANTHROPIC_API_KEY
Test runs consume tokens from your configured AI provider. Standard API billing from your provider applies.

​
Where to go next

Quick Start

Install FinalRun and run your first test in five minutes.

YAML test format

Learn the full test spec format: fields, placeholders, and suites.

CLI reference

Every command, flag, and option available in the finalrun CLI.

Workspace configuration

Set up your app identity, default model, and environments.