finalrun-agent is an AI-driven CLI that tests your Android and iOS apps using natural language. You write a plain-English test in YAML, FinalRun launches your app on an emulator or simulator, uses an AI model (Gemini, GPT, or Claude) to see the screen and perform each step — tapping, swiping, typing — and produces a pass/fail report with video and device logs.

Demo

Install

curl -fsSL https://raw.githubusercontent.com/final-run/finalrun-agent/main/scripts/install.sh | bash

Sets up Node.js, the CLI, AI coding agent skills, and platform tools. Run finalrun doctor to verify host readiness.

Write and Run Your First Test Using AI Agents

FinalRun ships skills that let your AI coding agent generate tests, validate workspaces, and run tests — all from chat.

Generate tests

/finalrun-generate-test skill reads your app's source code, infers the app identity, and generates complete test specs with setup, steps, and expected state — organized by feature folder.

Example:

/finalrun-generate-test Generate tests for the authentication feature — cover login with valid credentials, login with wrong password, and logout

The agent will:

1. Read your source code to understand the UI and infer the app's package name / bundle ID
2. Set up .finalrun/config.yaml and environment bindings in .finalrun/env/
3. Propose a test plan with file paths and cleanup strategy for your approval
4. Generate YAML specs under .finalrun/tests/auth/ and a suite under .finalrun/suites/
5. Run finalrun check to validate everything

Run tests

/finalrun-generate-test skill validates and run the test once your tests are generated.

Example:

/finalrun-use-cli Run the auth tests on Android

Debug and fix failing tests

/finalrun-test-and-fix skill orchestrates the full generate → run → diagnose → fix loop. It authors tests via finalrun-generate-test, runs them via finalrun-use-cli, reads the CLI artifacts (result.json, actions/, screenshots, device.log) on failure, classifies whether the bug is in the app code or the test, applies the narrowest fix, and re-runs until the run is green.

Example:

/finalrun-test-and-fix Verify and fix the checkout feature end-to-end on Android

How to auto trigger Finalrun to generate and test once feature development is completed

Add this content to your AGENTS.md to auto-trigger Finalrun, so you don’t have to explicitly ask your agent to generate and run tests everytime. This will also let your agent fix issues if there is any error while development

API Keys (BYOK — Bring Your Own Key)

FinalRun uses your own AI provider API key to run tests.

echo "GOOGLE_API_KEY=your-key-here" > .env

| Provider | Environment variable | |---|---| | google/... | GOOGLE_API_KEY | | openai/... | OPENAI_API_KEY | | anthropic/... | ANTHROPIC_API_KEY |

Test runs consume API tokens from your configured provider — standard API billing applies.

Running Tests manually with CLI

finalrun test smoke.yaml --platform android --model google/gemini-3-flash-preview

finalrun suite auth_smoke.yaml --platform android --model google/gemini-3-flash-preview

Documentation

Full docs: docs.finalrun.app

• Autotrigger FinalRun tests (AI agents) — when coding agents should generate, validate, and run tests after UI work
• YAML Tests — test format, fields, suites, and environment placeholders
• CLI Reference — all commands, flags, and report tools
• Configuration — workspace config, app identity, --app flag, and per-environment overrides
• Environment & Secrets — dotenv load order, provider keys, and platform prerequisites
• Troubleshooting — common errors and fixes

Development

See CONTRIBUTING.md for monorepo structure, build commands, and contributor guidelines.

• CODE_OF_CONDUCT.md
• SECURITY.md
• CHANGELOG.md
• LICENSE