✦ Rova CLI

Rova CLI is the autonomous AI testing companion that brings the power of the Rova Brain directly to your local development environment and CI/CD pipelines. It allows you to run complex, goal-oriented tests against your web and mobile applications using natural language goals or trigger existing test suites defined in Rova Web.

🚀 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

In CI/CD environments, supply your API Key via the ROVA_API_KEY environment variable.

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

🔄 CI/CD & Existing Test Suite Execution

Rova CLI connects your CI/CD pipelines (GitHub Actions, GitLab CI, CircleCI, Jenkins) to your curated TestSuites defined in Rova Web.

1. List Available Test Suites (rova suites)

Discover test suites available in your Rova Web project:

rova suites

2. Execute an Existing Test Suite (--suite)

Trigger execution of an existing test suite by name or ID, overriding target URLs for preview deployments (e.g. Vercel, Netlify) or device viewports:

rova run web --suite "Core Regression Suite" --url https://pr-42.preview.myapp.com --preset mobile-safari --blocking

3. Official GitHub Action (GetScandium/rova-github-action@v1)

Use the official GitHub Action in your .github/workflows/ci.yml pipeline:

- name: Run Rova E2E Regression
  uses: GetScandium/rova-github-action@v1
  with:
    api-key: ${{ secrets.ROVA_API_KEY }}
    suite-name: "Core Regression Suite"
    url: ${{ steps.preview-deployment.outputs.url }}
    preset: "desktop-chrome"
    blocking: true

🛠 Running Local & Autonomous Tests

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

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 | | :--- | :--- | | -s, --suite <nameOrId> | CI/CD Mode: Name or ID of an existing test suite in Rova Web to execute. | | -u, --url / --preview-url | Target URL or dynamic preview deployment URL override. | | --preset <preset> | Device viewport preset (mobile-safari, desktop-chrome, tablet-ipad, mobile-android). | | --blocking | Wait for run completion and exit with 0 (pass) or 1 (fail) for CI gating (default: true). | | -g, --goal | The natural language goal for single test runs. | | --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. |

📱 Device Viewport Presets (--preset)

Override device viewports on the fly during CI execution without changing test definitions in the UI:

• desktop-chrome: 1280 × 800 (Desktop Chrome)
• mobile-safari / iphone-14: 390 × 844 (Mobile Safari)
• tablet-ipad: 820 × 1180 (iPad Tablet)
• mobile-android / pixel-7: 412 × 915 (Android Chrome)

rova run web --suite "Checkout Suite" --preset mobile-safari

⚡️ 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 "..."

🌐 Testing VPN & Private Staging Apps (rova tunnel)

If your company's staging or development website can only be opened when you are connected to your company's VPN (like OpenVPN, Cisco AnyConnect, WireGuard, or Tailscale), Rova's cloud runners won't be able to reach it on their own because it's behind a private security wall.

The Solution: You can use your laptop as a secure bridge so Rova Cloud can test your private website!

🚦 Step-by-Step Guide:

1. Turn on your VPN: Connect to your company's VPN on your work laptop as you normally do.
2. Start the tunnel: Open your Terminal and run:

   rova tunnel

   You will see a confirmation message:

   ✔ ✦ Tunnel Connected and Ready!
     🟢 Cloud test runners will now route private traffic through this machine.

3. Run your tests: That's it! Go to the Rova Web Dashboard (or use rova run) and trigger your tests on your private staging URL (e.g. https://staging.internal.yourcompany.com).
4. When you are finished: Press Ctrl + C in your terminal to close the tunnel.

💡 Good to know:

• Keep your terminal window open and your laptop awake while tests are running.
• Your laptop only routes test traffic for your own workspace—nothing else is shared.

⚙️ 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 tunnel

Open a secure bridge to allow Rova Cloud to reach websites behind your VPN or internal network.

• --workspace <id>: Manually specify a workspace ID (optional).
• --debug: Show real-time connection and packet debug logs.

rova suites

Discover and list test suites configured in Rova Web.

• --project-id: Filter suites by project ID.
• --search: Search suites by name.

rova run

Execute autonomous tests or existing test suites.

• web --suite <nameOrId>: Execute an existing test suite.
• web --url <url> --goal <goal>: Run an autonomous goal-based web test.
• mobile: Run an Appium-based mobile test.

rova auth

Manage your Rova credentials.

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

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