Testronaut

https://docs.testronaut.app
Admin
Testronaut is an autonomous UI testing framework that lets you write missions in plain...
Tokens:9,585
Snippets:138
Trust Score:5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run Welcome Mission

Source: https://docs.testronaut.app/docs/quickstart

Execute the default welcome mission provided by Testronaut to verify the installation.

```bash
npx testronaut welcome.mission.js  

```

--------------------------------

### Install Testronaut CLI

Source: https://docs.testronaut.app/docs/quickstart

Install the Testronaut command-line interface globally using npm.

```bash
npm i -g testronaut  

```

--------------------------------

### Project Configuration File

Source: https://docs.testronaut.app/docs/guides/model-selection-gemini

Example of a testronaut-config.json file defining the default model and project settings.

```json
{
  "initialized": true,
  "provider": "gemini",
  "model": "gemini-2.5-flash",
  "outputDir": "missions/mission_reports",
  "projectName": "your-project",
  "maxTurns": 20
}
```

--------------------------------

### Testronaut Project Directory Structure

Source: https://docs.testronaut.app/docs/quickstart

An example of the expected directory structure for a Testronaut project, including the missions folder.

```bash
missions/  
├── login.mission.js  
├── logout.mission.js  
└── dashboard.mission.js  

```

--------------------------------

### View CLI token usage output

Source: https://docs.testronaut.app/docs/guides/usage-costs

Example of the console output showing token consumption per turn during a mission.

```text
[model] → navigate login page  
[tool ] ← ✅ Success  
Tokens used this turn: 628 (≈ $0.0025 at GPT-4o-mini or Gemini-Flash rates)  
```

--------------------------------

### Write a Testronaut Mission File

Source: https://docs.testronaut.app/docs/quickstart

Example of a mission file written in JavaScript that defines a mission string and an asynchronous function to execute it using Testronaut's runMissions.

```javascript
import { runMissions } from 'testronaut';  
  
export const loginMission = `  
Visit ${process.env.URL}.  
Fill the username field with ${process.env.USERNAME}.   
Fill the password field with ${process.env.PASSWORD}.  
Take a screenshot.  
Submit the form.  
Wait for the dashboard to appear.  
Take another screenshot.  
Report SUCCESS if the dashboard is loaded, otherwise report FAILURE.  
`;  
  
export async function executeMission() {  
  await runMissions({  
    mission: loginMission  
  }, "Login Mission");  
}  

```

--------------------------------

### Upload Document Mission Example

Source: https://docs.testronaut.app/docs/guides/file-upload-download

This mission demonstrates how to upload a document using Testronaut. It includes steps for selecting the uploader, choosing a file, waiting for completion, and verifying the upload.

```javascript
import { runMissions } from 'testronaut';
import { loginMission } from './login.mission.js';
import { openDocumentsMission } from './openDocuments.mission.js';

export const uploadDocumentMission = `
  Select the document uploader and select the "about-chickens.pdf" file from the missions/files.
  It will take a several seconds for the upload to complete.
  Confirm that the document has been uploaded by checking to see if the document is at the top of the Documents list, if its not there wait a few seconds.
  Take a screenshot.
  If successful, report SUCCESS stating the reason why. 
  Otherwise, report FAILURE stating the reason why. 
`


export async function executeMission() {
  return await runMissions({
    preMission: [loginMission, openDocumentsMission],
    mission: uploadDocumentMission,
  }, "upload document mission");
}

```

--------------------------------

### Testronaut Environment Variables Configuration

Source: https://docs.testronaut.app/docs/quickstart

Example of a .env file for Testronaut, showing configurations for LLM API keys (OpenAI, Gemini) and mission-specific variables like URL, username, and password.

```dotenv
# Example: OpenAI  
OPENAI_API_KEY=sk-...  
  
# or Gemini  
GEMINI_API_KEY=AIza...  
  
# Mission variables  
URL=https://example.com/login  
USERNAME=example@example.com  
PASSWORD=********  

```

--------------------------------

### Configure GitHub Actions for Testronaut

Source: https://docs.testronaut.app/docs/guides/ci-github-actions

A standard workflow configuration that handles repository checkout, Node.js setup, Playwright browser caching, test execution, and artifact reporting.

```yaml
name: Run Testronaut Tests  
  
on:  
  push:  
    branches: [ main ]  
  pull_request:  
    branches: [ main ]  
  workflow_dispatch:  
  
jobs:  
  test:  
    runs-on: ubuntu-latest  
  
    steps:  
      - name: Checkout repository  
        uses: actions/checkout@v4  
  
      - name: Set up Node.js  
        uses: actions/setup-node@v4  
        with:  
          node-version: '22'  
          cache: 'npm'   
  
      - name: Install dependencies  
        run: npm ci  
  
      # Compute the Playwright version from your installed dependency  
      - name: Get Playwright version  
        id: pw  
        run: |  
          version=$(node -p 'require("playwright/package.json").version')  
          echo "version=$version" >> "$GITHUB_OUTPUT"  
  
      # Cache the Playwright browsers folder  
      - name: Cache Playwright browsers  
        uses: actions/cache@v4  
        with:  
          path: ~/.cache/ms-playwright  
          key: ${{ runner.os }}-playwright-${{ steps.pw.outputs.version }}  
          restore-keys: |  
            ${{ runner.os }}-playwright-  
  
      # Install system deps + ensure browsers present (will be a no-op if cache hit)  
      - name: Install Playwright browsers (with OS deps)  
        run: npx playwright install --with-deps  
  
      # Optional but often stabilizes CI chromium on GH runners  
      - name: Set CI flags for Chromium  
        run: echo "TESTRONAUT_CI_CHROMIUM=1" >> $GITHUB_ENV  
  
      - name: Run Testronaut missions (openAI Example)  
        env:  
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}  
          URL: ${{ secrets.URL }}  
          USERNAME: ${{ secrets.USERNAME }}  
          PASSWORD: ${{ secrets.PASSWORD }}  
        run: npx testronaut  
  
      # Login and upload steps to send reports to mission control  
      - name: Login to Testronaut  
        run: npx testronaut login --apiKey=${{ secrets.TESTRONAUT_API_KEY }}  
  
      - name: Upload Testronaut report  
        run: npx testronaut upload  
  
      # Optional Steps for preserving report artifacts  
      - name: Upload reports  
        if: always()  
        uses: actions/upload-artifact@v4  
        with:  
          name: testronaut-reports  
          path: missions/mission_reports/**  
  
      - name: Upload screenshots  
        if: always()  
        uses: actions/upload-artifact@v4  
        with:  
          name: testronaut-screenshots  
          path: missions/mission_reports/screenshots/*.png
```

--------------------------------

### Initialize Testronaut Project

Source: https://docs.testronaut.app/docs/category/reference

Use this command to set up a new Testronaut project. Ensure npx is available in your environment.

```bash
npx testronaut --init
```

--------------------------------

### Initialize Testronaut Project

Source: https://docs.testronaut.app/docs/quickstart

Initialize a new Testronaut project. This command creates the necessary directory structure and configuration files.

```bash
npx testronaut --init  

```

--------------------------------

### CLI Initialization

Source: https://docs.testronaut.app/docs/category/reference

Command to initialize a new Testronaut project.

```APIDOC
## CLI Command

### Description
Initializes the Testronaut environment in the current directory.

### Command
`npx testronaut --init`
```

--------------------------------

### Configure Environment Variables

Source: https://docs.testronaut.app/docs/guides/write-missions

Define credentials and API keys in a .env file for LLM providers and mission-specific variables.

```bash
# Example: OpenAI  
OPENAI_API_KEY=sk-...  
  
# or Gemini  
GEMINI_API_KEY=AIza...  
  
# Mission variables  
URL=https://example.com/login  
USERNAME=example@example.com  
PASSWORD=********  
```

--------------------------------

### Run Testronaut with Default Settings

Source: https://docs.testronaut.app/docs/guides/turn-tuning

Executes a mission using the default turn limit of 20.

```bash
npx testronaut
```

--------------------------------

### Define a Mission File

Source: https://docs.testronaut.app/docs/guides/write-missions

Create a mission file in the missions/ directory that exports a mission string and an executeMission function.

```javascript
import { runMissions } from 'testronaut';  
import { loginMission } from './login.mission.js';  
  
export const logoutMission = `  
    Ensure you are already logged in, if not, log in.  
    Locate the Logout button, you may need to expand the menu.  
    Take a screenshot.  
    Click the logout button.  
    Figure out if the logout worked.  
    Take a screenshot.  
    If successful, report SUCCESS stating the reason why.   
    Otherwise, report FAILURE stating the reason why.  
`  
  
export async function executeMission() {  
  return await runMissions({  
    preMission: loginMission,  
    mission: logoutMission  
  }, "logout mission");  
}  
```

--------------------------------

### Authenticate via CLI

Source: https://docs.testronaut.app/docs/guides/cli-auth

Initiates the login process for the Testronaut CLI, requiring an API key generated from the settings page.

```bash
npx testronaut login
```

--------------------------------

### Login and Upload Reports with Testronaut CLI

Source: https://docs.testronaut.app/docs/guides/report-upload

Use these commands to authenticate with Testronaut and upload your generated report files. Ensure you have run your tests first to generate the report.

```bash
npx testronaut login  
npx testronaut upload  

```

--------------------------------

### Run Exploratory Mission via CLI

Source: https://docs.testronaut.app/docs/guides/exploratory-test-mode

Execute the mission file using the Testronaut CLI with a specified turn limit to control the depth of exploration.

```bash
npx testronaut exploratory.mission.js --turns=200  
```

--------------------------------

### Configuration Reference

Source: https://docs.testronaut.app/docs/category/reference

Details regarding the testronaut.config.js file configuration.

```APIDOC
## Configuration (testronaut.config.js)

### Description
Defines the settings for the Testronaut application.

### Parameters
- **provider** (string) - Required - The LLM provider to be used (e.g., openai, gemini, etc.)
```

--------------------------------

### Basic Testronaut Configuration

Source: https://docs.testronaut.app/docs/reference/config

The primary configuration object for defining the LLM provider, model, and session settings.

```json
{
  "provider": "openai",
  "model": "gpt-5-mini",
  "initialized": true,
  "outputDir": "missions/mission_reports",
  "projectName": "name_of_your_repo",
  "maxTurns": 20,
  "sessionToken": "*******************"
}
```

--------------------------------

### Set Model via Environment Variable

Source: https://docs.testronaut.app/docs/guides/model-selection-openai

Configures the model for a test run using an environment variable, suitable for CI environments.

```bash
TESTRONAUT_MODEL=gpt-4.1-mini npx testronaut
```

--------------------------------

### Define an Exploratory Mission

Source: https://docs.testronaut.app/docs/guides/exploratory-test-mode

Create a mission file that provides the agent with high-level instructions for autonomous exploration. The mission string should define the scope, desired behavior, and success/failure criteria.

```javascript
import { runMissions } from 'testronaut';  
  
export const exploratoryMission = `  
Visit ${process.env.URL}.  
You are in exploratory mode, navigate the interface to understand what this app does.  
Click buttons, open menus, inspect pages, and capture screenshots as you go.  
Look for any broken links, unexpected popups, missing labels, or console errors.  
After exploring multiple areas (such as dashboards, menus, or modals), summarize your findings clearly.  
End with a SUCCESS message if exploration completed without crashes or blockers,  
or FAILURE if you encounter any major issues.  
`;  
  
export async function executeMission() {  
  return await runMissions({  
    mission: exploratoryMission  
  }, "exploratory mission");  
}  
```

```javascript
import { runMissions } from 'testronaut';  
import { loginMission } from './login.mission.js';  
  
export const exploratoryMission = `  
You are doing exploratory testing with a high turn budget.  
Goal: discover as many meaningful UI states and potential issues as possible.  
  
Rules of engagement:  
- Do NOT navigate to external sites.  
- Prefer non-destructive actions. Avoid deletes, payments, permanent data changes.  
- If you encounter forms, use obviously fake data (e.g., "Test User", "test+explore@example.com").  
- Take a screenshot whenever you reach a new page/major state, open a modal, or hit an error.  
- If you are uncertain what to click, call 'get_dom' and infer likely nav/menu links by their text or role.  
- Use small, focused actions per turn (click one thing, evaluate, repeat).  
- If a page looks dynamic (spinners/toasts), wait briefly for stability before continuing.  
- If the route changed or significant content appeared/disappeared, take a screenshot.  
  
What to look for:  
- Navigation coverage: top nav, sidebars, dashboard cards, settings/profile areas, and obvious primary flows.  
- Broken/obscure links, 404s, visible error banners, console errors (if surfaced), or dead-end states.  
- Accessibility hints: focus traps, missing labels, interactive elements not clickable by text.  
- Visual issues: overlapping UI, off-screen content, obvious layout glitches.  
  
Stop conditions (pick the earliest):  
1) You have visited ~15 distinct screens/components (count modals as screens),  
2) You detect a blocking error or crash view,  
3) You can no longer find meaningful actions that change state.  
  
Final report:  
- If exploration criteria met without blocking errors: respond with  
  "SUCCESS: <short summary>" then list:  
  - Unique areas visited (bullet list)  
  - Top 3–5 findings (issues/suspicions)  
  - Any suggested next probes (follow-ups)  
- If you were blocked or hit a crash repeatedly: respond with  
  "FAILURE: <why blocked / where>" and include last screenshots context.  
`;  
  
export async function executeMission() {  
  return await runMissions(  
    {   
      preMission: loginMission,  
      mission: exploratoryMission   
    },  
    "exploratory mission"  
  );  
}  
```

--------------------------------

### Resource Guard Configuration

Source: https://docs.testronaut.app/docs/reference/config

Settings to ensure resources like documents and files are fully processed before reporting success.

```json
"resourceGuard": {
  "enabled": true,
  "hrefIncludes": ["/document/", "/file/", "/download", "/attachment/"],
  "dataTypes": ["document", "file", "item", "row"]
}
```

--------------------------------

### Run a Specific Testronaut Mission

Source: https://docs.testronaut.app/docs/quickstart

Execute a specific mission file, such as 'login.mission.js', using the Testronaut CLI.

```bash
npx testronaut login.mission.js  

```

--------------------------------

### Testronaut Configuration - LLM Provider

Source: https://docs.testronaut.app/docs/category/reference

Specify the Language Model (LLM) provider for Testronaut in your configuration file. Supported providers include 'openai', 'gemini', and others.

```javascript
provider: LLM Provider (openai, gemini, etc...)
```

--------------------------------

### Testronaut CLI Commands

Source: https://docs.testronaut.app/docs/reference/cli

A collection of CLI commands for interacting with the Testronaut application.

```APIDOC
## CLI Commands

### npx testronaut --init
- **Description**: Scaffold missions and configuration files.

### npx testronaut --turns=<n>
- **Description**: Override the maximum number of turns for the current run.
- **Parameters**: n (integer) - Required - The number of turns.

### npx testronaut --model=<n>
- **Description**: Override the LLM model used for the current run.
- **Parameters**: n (string) - Required - The model identifier (must be from the same provider).

### npx testronaut <name of mission.mission.js>
- **Description**: Execute specific missions from the missions/ directory. If no file is specified, it runs all missions.

### npx testronaut login
- **Description**: Manage user authentication.

### npx testronaut upload
- **Description**: Upload the JSON report generated from a run.

### npx testronaut serve
- **Description**: View the most recent HTML report.

### npx testronaut view
- **Description**: Alias for the serve command to view the most recent HTML report.
```

--------------------------------

### Configure default model in testronaut-config.json

Source: https://docs.testronaut.app/docs/guides/model-selection-openai

Set the default provider and model in the project configuration file generated after initialization.

```json
{
  "initialized": true,
  "provider": "openai",
  "model": "gpt-4o",
  "outputDir": "missions/mission_reports",
  "projectName": "your-project",
  "maxTurns": 20
}
```

--------------------------------

### Verify Turn Override

Source: https://docs.testronaut.app/docs/guides/turn-tuning

Console output confirming the active turn limit override.

```text
🎯 Turn override: 30
```

--------------------------------

### Execute a Chained Mission

Source: https://docs.testronaut.app/docs/guides/chain-missions

Use runMissions to sequence login, navigation, form submission, and logout steps.

```typescript
import { runMissions } from 'testronaut';  
import { loginMission } from './login.mission.js';  
import { logoutMission } from './logout.mission.js';  
import { navigateToContactFormMission } from './navigateToContactForm.mission.js';  
  
export const fillContactFormMission =   
`Input the text "example@example.com" in the email field.  
Input the phone number (555)555-5555 into the phone number field.  
Click the submit button.  
Upon submission success there should be a toast notification indicating the form information was saved successfully.  
Take a screenshot.  
If found, report SUCCESS. Otherwise, report FAILURE.`  
  
export async function executeMission() {  
  await runMissions({  
    preMission: [loginMission, navigateToContactFormMission],  
    mission: fillContactFormMission,  
    postMission: logoutMission,  
  }, "Fill Contact Form Mission");  
}  
```

--------------------------------

### Set Model via Environment Variable

Source: https://docs.testronaut.app/docs/guides/model-selection-gemini

Set the TESTRONAUT_MODEL environment variable to define the model for the current session.

```bash
export TESTRONAUT_MODEL=gemini-2.5-flash
```

--------------------------------

### Override Model via CLI

Source: https://docs.testronaut.app/docs/guides/model-selection-openai

Specifies a model for a single test run, overriding the default configuration.

```bash
npx testronaut checkoutFlow.mission.js --model o3
```

--------------------------------

### Run Specific Mission with Model Override

Source: https://docs.testronaut.app/docs/guides/model-selection-gemini

Override the configured model for a single mission run.

```bash
npx testronaut checkoutFlow.mission.js --model gemini-2.5-pro
```

--------------------------------

### Override Model via CLI

Source: https://docs.testronaut.app/docs/guides/model-selection-gemini

Use the --model flag to specify a Gemini model during execution, which takes the highest precedence.

```bash
npx testronaut --model gemini-2.5-pro
```

--------------------------------

### Override model via CLI

Source: https://docs.testronaut.app/docs/guides/model-selection-openai

Use the --model flag to specify a model for a single execution run.

```bash
npx testronaut --model gpt-4.1-mini
```

```bash
npx testronaut downloadDocument.mission.js --model o3
```

--------------------------------

### Configure Retry Limits

Source: https://docs.testronaut.app/docs/guides/turn-tuning

Sets the number of retries allowed per turn to handle transient flakiness.

```json
{ "retryLimit": 5 }
```

```bash
npx testronaut --retry_limit=5
```

```bash
TESTRONAUT_RETRY_LIMIT=5 npx testronaut
```

--------------------------------

### Temporary Environment Override for CI/CD

Source: https://docs.testronaut.app/docs/guides/model-selection-gemini

Set the model inline for CI/CD pipelines or temporary test runs.

```bash
TESTRONAUT_MODEL=gemini-2.5-flash-8b npx testronaut
```

--------------------------------

### Locate Screenshot Files

Source: https://docs.testronaut.app/docs/faq

Screenshots captured during a mission are automatically saved to this directory.

```text
missions/mission_reports/screenshots/  
```

--------------------------------

### runMissions Function

Source: https://docs.testronaut.app/docs/guides/chain-missions

The `runMissions` function is used to sequence flows, control parallelism, and share memory/environment variables between missions. It allows for defining pre-mission, main mission, and post-mission steps.

```APIDOC
## runMissions Function

### Description
Sequences flows, controls parallelism, and shares memory/environment variables.

### Method
`runMissions`

### Parameters
#### Function Signature
`runMissions({ preMission, mission, postMission }: { preMission: string or array; mission: string or array; postMission: string or array; }, missionName: string)`

#### `preMission`
- **Type**: `string` or `array`
- **Description**: Missions to be executed before the main mission.

#### `mission`
- **Type**: `string` or `array`
- **Description**: The main mission to be executed.

#### `postMission`
- **Type**: `string` or `array`
- **Description**: Missions to be executed after the main mission.

#### `missionName`
- **Type**: `string`
- **Description**: A name for the mission sequence.

### Request Example
```javascript
import { runMissions } from 'testronaut';
import { loginMission } from './login.mission.js';
import { logoutMission } from './logout.mission.js';
import { navigateToContactFormMission } from './navigateToContactForm.mission.js';

export const fillContactFormMission = `Input the text "example@example.com" in the email field.
Input the phone number (555)555-5555 into the phone number field.
Click the submit button.
Upon submission success there should be a toast notification indicating the form information was saved successfully.
Take a screenshot.
If found, report SUCCESS. Otherwise, report FAILURE.`;

export async function executeMission() {
  await runMissions({
    preMission: [loginMission, navigateToContactFormMission],
    mission: fillContactFormMission,
    postMission: logoutMission,
  }, "Fill Contact Form Mission");
}
```

### Response
This function does not return a value directly but executes the specified missions.
```

--------------------------------

### Override model via environment variables

Source: https://docs.testronaut.app/docs/guides/model-selection-openai

Set the TESTRONAUT_MODEL environment variable to override the configuration file for the current session.

```bash
export TESTRONAUT_MODEL=gpt-4o-mini
npx testronaut
```

```powershell
$env:TESTRONAUT_MODEL="gpt-4o-mini"
npx testronaut
```

--------------------------------

### Testronaut Mission Report Location

Source: https://docs.testronaut.app/docs/quickstart

Specifies the default location where Testronaut saves mission execution reports, including a JSON file and an HTML summary.

```bash
missions/mission_reports/run_<runId>.json  

```

--------------------------------

### runMissions Function Signature

Source: https://docs.testronaut.app/docs/guides/chain-missions

The runMissions function accepts preMission, mission, and postMission as either a string or an array.

```typescript
runMissions({ preMission, mission, postMission }: {  
    preMission: string or array;  
    mission: string or array;  
    postMission: string or array;  
}, missionName: string)  
```

--------------------------------

### Override Turn Limits via CLI

Source: https://docs.testronaut.app/docs/guides/turn-tuning

Temporarily adjusts the maximum number of turns for a specific mission run.

```bash
npx testronaut --turns=30
```
Tokens:
Raw