Configuration

The config file

OrbitTest reads orbittest.config.js from your project root. Every field is optional; the defaults are sensible, and you should only add settings the project actually needs. Here is the full annotated reference:

module.exports = {
  // Test discovery
  testDir: "tests",
  testMatch: ["**/*.test.js", "**/*.spec.js"],

  // Output
  reportsDir: "reports",

  // Shared hooks file(s)
  globalSetup: [],

  // Parallelism
  workers: 1,
  maxWorkers: 4,

  // Retry policy
  retries: 0,

  // Timeouts in milliseconds
  testTimeout: 30000,
  actionTimeout: 0,

  // Browser visibility: "auto" | "show" | "hide"
  browser: { display: "auto" },

  // Experimental features
  experimental: {
    ui: true,
    visualAutomation: true,
    apiTesting: false
  },

  // Local failure report server
  openReportOnFailure: {
    enabled: !process.env.CI,
    port: 0
  },

  // CI behavior (see the CI/CD page)
  ci: {
    enabled: Boolean(process.env.CI),
    retries: 1,
    trace: "on-failure",
    screenshot: "on-failure",
    failFast: false,
    maxFailures: 0,
    shard: process.env.ORBITTEST_SHARD || null,
    summary: true,
    junit: true,
    githubAnnotations: Boolean(process.env.GITHUB_ACTIONS)
  },

  // Smart Report evidence collection
  smartReport: false,
  smartReportSlowRequestMs: 2000,

  // Named environments
  environments: {
    staging: {
      reportsDir: "reports/staging"
    }
  }
};

orbittest.config.js with every option shown.

The settings that matter first

Workers and parallelism

workers controls how many tests run at the same time on one machine. Start with 1 while the suite is small. When runs get slow, raise it gradually; each worker is a full Chrome instance, so CPU and memory are the real limits. maxWorkers is a safety cap.

Retries

retries: 0 locally is the right default: while developing, you want to see every failure. In CI, ci.retries: 1 is a pragmatic middle ground. A test that fails and then passes is reported as flaky rather than quietly passing, so retries never hide instability from you.

Timeouts

testTimeout (30 seconds by default) is the budget for a whole test. actionTimeout: 0 means individual actions have no extra cap. Raise the test timeout for genuinely slow flows on a per-test basis rather than globally:

test("slow checkout", { retries: 1, timeout: 60000 }, async (orbit) => {
  // ...
});

Per-test options beat global config changes.

Browser display

"auto" shows the browser on your machine and hides it in CI, which is what nearly every team wants. --show-browser and --hide-browser override per run. Step-debug mode (--step) always shows the browser, because live debugging needs something to watch.

Local versus CI behavior

A common mistake is using one configuration for both worlds. Local runs should give fast, visible feedback; CI runs should be deterministic and rich in artifacts. The config above already splits on process.env.CI, and the ci block only activates in pipelines. The practical result:

Behavior	Local run	CI run
Browser	Visible	Hidden
Failure report server	Opens automatically	Disabled
Retries	0	1 (failures become “flaky” if they pass on retry)
Trace / screenshots	On demand via flags	Captured on failure
Outputs	HTML report	HTML + summary.json + junit.xml

Named environments

The environments block lets one config serve several targets. Activating an environment merges its values over the base config:

orbittest run --env staging

Use this for things that legitimately differ between targets: report directories, base URLs your tests read from config, longer timeouts for a slow staging cluster. Do not use it to make tests behave differently; a test that only passes in one environment is telling you something about the product or the test, and an env switch just hides it.

Frequently asked questions

Can the config file be JSON or TypeScript?

The config is a CommonJS JavaScript file (module.exports = {...}). Because it is JavaScript, you can compute values, read environment variables, and add comments, which JSON does not allow.

What happens with no config file at all?

Everything runs on defaults: tests discovered under tests/, one worker, no retries, 30-second timeout, reports in reports/. orbittest init writes a starter config you can trim.

How do I point tests at different base URLs per environment?

Define the URL in the environment block (or an environment variable) and read it inside your tests from process.env. Keep credentials out of the config file; see Environment Variables.

CLI Reference — Every OrbitTest command and flag: run, init, ui, forge, devices, doctor, and clean-reports, with recommended npm scripts.
CI/CD Integration — CI mode, retries and flaky detection, fail-fast, sharding across jobs, and a complete GitHub Actions workflow.
Environment Variables — ORBITTEST_CHROME_PATH, sharding, CI flags, ADB and device selection, and how to keep secrets out of test files.
Lifecycle Hooks — beforeAll, beforeEach, afterEach, and afterAll: testInfo fields, global setup files, and using hooks without hiding test intent.