✦ Rova CLI

Rova CLI is the autonomous AI testing companion that brings the power of the Rova Brain directly to your local development environment. It allows you to run complex, goal-oriented tests against your web and mobile applications using natural language goals.

🚀 Getting Started

1. Installation

Install the Rova CLI globally via npm:

npm install -g @scandiumsys/rova-cli

2. Initialization

Set up Rova in your project by running the initialization wizard. This creates a rova.config.js file in your root directory.

rova init

The wizard will ask for your default test URL and browser preferences.

3. Authentication

You need a Rova API Key to communicate with the Brain. Log in to your product of choice:

rova auth login --product web
# or
rova auth login --product mobile

This will prompt you for your API Key and securely store it in ~/.rova/credentials.json.

You can obtain an API Key for the web product from your workspace dashboard @ https://app.rova.qa/settings/workspace/apikeys

Or for the mobile product @ https://mobile.rova.qa/settings/api-keys

🛠 Running Tests

The core of Rova is the run command. You provide a Goal (what you want to achieve) and a URL (where to start).

Simple Autonomous Run

The AI will take control of the browser and attempt to achieve the goal automatically.

rova run web --url https://example.com --goal "Create a new user account and verify the welcome email"

Options & Flags

| Flag | Description | | ---------------- | -------------------------------------------------------------------------- | | -g, --goal | Required. The natural language goal for the AI. | | -u, --url | Target URL (required for web). | | --turbo | Turbo Mode: AI returns action sequences for 2-3x faster execution. | | --interactive | Interactive Mode: AI will pause and ask you for help if it gets stuck. | | --step-by-step | Debug Mode: Pauses after every single action for inspection. | | --headed | Run the browser with a visible window (default is headless). | | --max-steps | Limit the number of actions the AI can take (default: 50). | | --json | Output the final result as a JSON string (ideal for CI/CD). | | --output | File path to save the final execution result (e.g., test-results.json). | | --sync | Upload the results, screenshots, and logs to the Rova Dashboard. | | --project-id | Associate the execution with a specific Rova Project ID. | | --suite-name | Provide a custom suite name for dashboard reporting. | | -c, --context | Context Injection: Pass persistent info (e.g. login credentials). | | --suite-mode | Execution Mode: sequential, parallel, or continuity. | | --debug | Print raw HTTP traffic between CLI and Brain API. |

⚡️ Advanced Features

🏎 Turbo Mode (--turbo)

In standard mode, the AI takes one action at a time (Click -> Analyze -> Type -> Analyze). In Turbo Mode, the Brain can return a sequence of actions to execute at once (e.g., Fill email, Fill password, Click Login). This significantly reduces test duration and API latency.

📄 YAML Test Definitions (--file)

For repeatable test suites, you can define tests in a .rova.yml file.

Example tests.rova.yml:

context: "Default user: [email protected] / pass: rova123"

tests:
  - name: "Login Check"
    url: "http://localhost:3000/login"
    goal: "Login using the credentials provided in context"
    turbo: true

  - name: "Product Search"
    goal: "Search for 'Headphones' and add the first result to cart"

Run the entire file:

rova run web --file tests.rova.yml --suite-mode parallel

🧠 Suite Execution Modes (--suite-mode)

When running a test file, you can control how tests are executed:

• sequential (Default): Tests run one after another.
• parallel: Tests run concurrently using your local CPU cores.
• continuity: Reuses a single browser session for all tests in the file. Ideal for flows where one test sets up the state for the next.

🪄 AI Test Generation (rova generate)

Generate test suites automatically based on your code changes or a natural language description.

From Git Diff: Analyzes your current Git changes (or a target branch) and suggests relevant tests.

rova generate --diff-target origin/main

From Prompt: Describe the features you want to test.

rova generate "Generate positive and edge cases for the checkout flow"

The generated tests will be appended to your tests.rova.yml file.

☁️ Remote Mode (--remote)

If you don't want to run Playwright locally, you can offload the execution to Rova's infrastructure. The CLI will stream the live progress back to your terminal via SSE.

rova run web --remote --goal "..."

⚙️ Configuration (rova.config.js)

The rova.config.js file allows you to define lifecycle hooks and project-wide defaults.

/** @type {import('@scandiumsys/rova-cli').ProjectConfig} */
export default {
  web: {
    defaultBrowser: 'chromium',
    headless: false,

    // Called once before the test starts
    beforeTest: async ({ url, goal }) => {
      // Seed database or set auth cookies
    },

    // Called after every AI action
    afterStep: async ({ step, action, result }) => {
      console.log(`Executed: ${action.type}`);
    },

    // Called after test completion
    afterTest: async (result) => {
      console.log(`Test finished with status: ${result.status}`);
    },
  }
};

📖 Command Reference

rova auth

Manage your Rova credentials.

• login: Authenticate with an API Key.
• logout: Clear local credentials.
• whoami: Show currently authenticated workspace.

rova run

Execute autonomous tests.

• web: Run a browser-based test.
• mobile: Run an Appium-based mobile test.

rova generate

Auto-generate YAML test suites using AI.

• Analyze Git diffs or use a text prompt to create .rova.yml tests.

rova init

Initialize a project with a config file.

🔍 Troubleshooting

• Browser binaries missing: Rova CLI will automatically attempt to install Playwright browsers on the first run. If this fails, run npx playwright install.
• Stuck AI: Use --interactive mode to give the AI a "hint" when it can't find an element.
• Debug Logs: Use the --debug flag to see raw HTTP communication with the Brain API.

✦ Happy Testing with Rova!
For more information, visit docs.rova.qa