Quick start: install FinalRun and run your first test

Install the FinalRun CLI, configure your AI provider key, write a YAML test spec, and execute it on an Android emulator or iOS simulator.

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:

   Google Gemini

   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
   

   Field	Description
   app.packageName	Android package identifier
   app.bundleId	iOS bundle identifier
   env	Default environment name (can be omitted if not using env files)
   model	Default 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=[e-mail]
   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.

   Android

   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

• YAML test format — learn all test spec fields, suite manifests, and placeholder syntax
• CLI reference — full list of commands and flags
• Workspace configuration — app identity, per-environment overrides, and --app flag