Installation

Requirements

You need two things before installing OrbitTest:

Node.js 18 or newer. Check with node --version. If you see 16 or lower, install the current LTS from nodejs.org.
A Chromium-based browser. OrbitTest uses Puppeteer’s managed Chrome by default and can download a compatible browser during install, so on most machines you do not have to install anything manually.

For Android testing you additionally need ADB (the Android Debug Bridge, bundled with Android Studio or available standalone as platform-tools) and a device with USB debugging enabled. That part is covered in Mobile Testing and Studio Installation; you can skip it entirely for browser-only work.

Install as a project dependency (recommended)

Installing into the project keeps the OrbitTest version locked in package.json, so every teammate and every CI run uses the same version. This is how you should set up anything you plan to keep.

npm install --save-dev orbittest
npx orbittest --version

Project-local install. Use npx to run the locally installed CLI.

Add an npm script so nobody has to remember the command:

{
  "scripts": {
    "test:e2e": "orbittest run"
  }
}

package.json

Install globally (for trying it out)

A global install is convenient when you just want to experiment from any folder:

npm install -g orbittest
orbittest --version

Global installs have a real downside for teams: your machine might run version 3.4 while CI runs 3.2, and you will chase failures that are really version differences. If the project matters, add the local dev dependency too.

Browser setup and custom Chrome paths

OrbitTest looks for Chrome in this order:

Puppeteer’s managed Chrome (downloaded during install).
The path in the ORBITTEST_CHROME_PATH environment variable.
A local system Chrome or Chromium installation.

On locked-down corporate machines or minimal CI images, point OrbitTest at a specific executable:

# Windows (PowerShell)
$env:ORBITTEST_CHROME_PATH = "C:\Path\To\chrome.exe"
orbittest run

# macOS / Linux
ORBITTEST_CHROME_PATH=/usr/bin/chromium orbittest run

Using a custom browser binary.

If you want to skip the Chrome download during install (for example, on a CI image that already ships Chromium):

# PowerShell
$env:PUPPETEER_SKIP_DOWNLOAD = "1"
npm install -g orbittest

# bash
PUPPETEER_SKIP_DOWNLOAD=1 npm install -g orbittest

Verify the installation

Run the environment check before writing your first test. It verifies Node, the browser, and (if configured) ADB and devices:

npx orbittest doctor

If doctor reports everything healthy, move on to the Quick Start. If it does not, the messages it prints are written to be actionable; fix them in order from top to bottom, because a missing browser will cause every later check to fail too.

Frequently asked questions

Does OrbitTest work on Windows, macOS, and Linux?

Yes, the framework and CLI run anywhere Node.js 18+ runs. Only Orbittest Studio (the desktop IDE) is Windows-only.

How big is the install?

The package itself is small; the managed Chrome download is the large part, comparable to installing Chrome normally. Skip it with PUPPETEER_SKIP_DOWNLOAD=1 if you already have Chrome.

Can I use it behind a corporate proxy?

The npm install respects your npm proxy settings. At runtime, tests talk to your target site through Chrome, which uses normal system networking.

Quick Start — Create a project with orbittest init, write and run a first browser test, and read the HTML report, in five short steps.
Environment Variables — ORBITTEST_CHROME_PATH, sharding, CI flags, ADB and device selection, and how to keep secrets out of test files.
Configuration — Every orbittest.config.js option explained: workers, retries, timeouts, browser display, CI behavior, and named environments.
Installation — Install Orbittest Studio on Windows, enable USB debugging on Android, and deploy the Companion app, step by step.