Skip to main content
This guide walks you through installing FinalRun, creating a minimal workspace, writing a test, and executing it on a connected Android emulator or iOS simulator. By the end you’ll have a working test run and know where to look for results.
1

Install FinalRun

Run the one-line install script. It sets up Node.js (if needed), installs the CLI globally, and installs the platform driver assets for Android and iOS.
curl -fsSL https://raw.githubusercontent.com/final-run/finalrun-agent/main/scripts/install.sh | bash
Alternatively, if you already have Node.js 20 or later, you can install via npm:
npm install -g @finalrun/finalrun-agent
2

Verify installation

Check that the CLI is available and that your host has the required platform tools:
finalrun --help
finalrun doctor
finalrun doctor checks for adb, emulator, scrcpy (Android), and Xcode command line tools (iOS). Fix any issues it reports before continuing.
Run finalrun check from inside your project directory before executing tests. It validates your workspace config, environment bindings, and suite manifests without launching a device.
3

Set up your AI provider key

FinalRun uses your own AI provider API key. Create a .env file at the root of your project with the key for your chosen provider:
echo "GOOGLE_API_KEY=your-key-here" > .env
Add .env to your .gitignore so secrets are never committed.
Each test run makes real AI API calls that consume tokens. Standard billing from your AI provider applies.
4

Create the workspace structure

Create the .finalrun/ directory and a folder for your test specs:
mkdir -p .finalrun/tests
Then create .finalrun/config.yaml with your app’s identity and default settings:
app:
  name: MyApp
  packageName: com.example.myapp
  bundleId: com.example.myapp
env: dev
model: google/gemini-3-flash-preview
FieldDescription
app.packageNameAndroid package identifier
app.bundleIdiOS bundle identifier
envDefault environment name (can be omitted if not using env files)
modelDefault AI model in provider/model format
At least one of app.packageName or app.bundleId is required.
5

Write your first test

Create .finalrun/tests/login_smoke.yaml with a basic login scenario:
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.
The ${secrets.email} and ${secrets.password} placeholders are resolved from your .env file or environment variables at runtime. To use them, add the values to your .env:
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=password123
Then declare the bindings in .finalrun/env/dev.yaml:
secrets:
  email: ${TEST_USER_EMAIL}
  password: ${TEST_USER_PASSWORD}
6

Run the test

Run your test on Android or iOS. The --model flag can be omitted if you set a default in config.yaml.
finalrun test login_smoke.yaml --platform android --model google/gemini-3-flash-preview
FinalRun will boot the emulator or simulator, install the app, and begin executing the test steps. You’ll see live output as the AI works through each action.
7

View results

List your recent test runs:
finalrun runs
Open the local report UI in your browser to see screenshots, video, and device logs:
finalrun start-server

​
What’s next