GitHub - final-run/finalrun-agent: AI QA Agent for mobile apps

finalrun.app • Blog • Cloud Device Waitlist • Join Slack Community

Follow us on

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:

Read your source code to understand the UI and infer the app's package name / bundle ID
Set up .finalrun/config.yaml and environment bindings in .finalrun/env/
Propose a test plan with file paths and cleanup strategy for your approval
Generate YAML specs under .finalrun/tests/auth/ and a suite under .finalrun/suites/
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

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

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.