Environment Variables

The full list

Environment variables let the same test suite adapt to different machines, CI systems, and devices without editing committed files.

Variable	Purpose
ORBITTEST_CHROME_PATH	Path to a custom Chrome/Chromium executable.
ORBITTEST_SHARD	Shard assignment in n/total format, e.g. 1/4. Same effect as —shard.
CI	Standard CI flag. Enables headless browser and CI-mode defaults.
GITHUB_ACTIONS	Set by GitHub automatically. Enables annotation output.
PUPPETEER_SKIP_DOWNLOAD	Set to 1 during install to skip the managed Chrome download.
ADB_PATH	Custom adb binary for Android testing.
DEVICE_SERIAL	Select a specific Android device when several are connected.
PROJECT_ROOT	Injected by Orbittest Studio when it runs tests for you.
ORBITTEST_UI_EVENTS	Internal: SSE event stream for the UI dashboard.
ORBITTEST_STEP_AUTO_CONTINUE	Internal: auto-continue in step mode.

Note

The last three are set by OrbitTest tooling itself. You will see them in process listings, but you should not need to set them by hand.

Setting variables per platform

The syntax differs by shell, and getting it wrong fails silently, so here is each one:

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

# cmd.exe (Windows)
set ORBITTEST_CHROME_PATH=C:\Path\To\chrome.exe
orbittest run

# bash / zsh (macOS, Linux) — inline for one command
ORBITTEST_CHROME_PATH=/usr/bin/chromium orbittest run

Same variable, three shells.

# GitHub Actions
jobs:
  e2e:
    runs-on: ubuntu-latest
    env:
      ORBITTEST_SHARD: "1/2"
    steps:
      - run: npx orbittest run --ci

In CI, declare variables on the job or step.

Using your own variables for test data

Beyond OrbitTest’s variables, your tests can read anything from process.env. This is the right home for credentials and per-environment URLs, things that must never be committed:

const BASE_URL = process.env.APP_BASE_URL || "https://staging.example.com";
const PASSWORD = process.env.ORBITTEST_PASSWORD || "";

test("login", async (orbit) => {
  await orbit.open(BASE_URL + "/login");
  await orbit.type("Email", "qa@example.com");
  await orbit.type("Password", PASSWORD);
  // ...
});

Secrets come from the environment, with safe fallbacks for non-secret values.

In CI, store secrets in the pipeline’s secret store (GitHub Actions secrets, GitLab CI variables) and expose them as environment variables to the test step. The Forge recorder follows the same principle: it deliberately does not capture typed passwords, and generates process.env.ORBITTEST_PASSWORD || "" placeholders instead.

Note

Never hard-code real passwords in test files or config. Files get committed, forks get cloned, and reports get shared. Environment variables plus a dedicated test account is the minimum bar.

Android device selection

With several phones connected, DEVICE_SERIAL picks the target. Get serials from adb devices or orbittest devices:

# PowerShell
$env:DEVICE_SERIAL = "R58M12ABCDE"
$env:ADB_PATH = "C:\Users\you\AppData\Local\Android\Sdk\platform-tools\adb.exe"
orbittest run tests/mobile-smoke.test.js

When Orbittest Studio runs tests, it injects DEVICE_SERIAL, ADB_PATH, and PROJECT_ROOT into the child Node.js process automatically, your test files stay device-agnostic.

Frequently asked questions

Which wins: an environment variable or a CLI flag?

CLI flags are the most specific and win. For sharding, --shard 2/4 overrides ORBITTEST_SHARD.

Can I use a .env file?

The mobile provider supports .env for ADB and device settings. For browser tests, your CI system or shell is the usual mechanism; if you add a dotenv loader to your project, keep .env in .gitignore.

Why does my variable not apply on Windows?

Most often the shell mismatch: export does nothing in PowerShell, and $env: does nothing in cmd. Match the syntax to the shell actually running the command.

Related pages

• Installation — Install OrbitTest with npm, set up Chrome or a custom browser path, and verify the environment with orbittest doctor.
• Configuration — Every orbittest.config.js option explained: workers, retries, timeouts, browser display, CI behavior, and named environments.
• CI/CD Integration — CI mode, retries and flaky detection, fail-fast, sharding across jobs, and a complete GitHub Actions workflow.
• Mobile Testing — Android automation with ADB and UIAutomator through @orbittest/mobile: setup, configuration, hybrid tests, and evidence.