Installation

Prerequisites

Use Node.js 18 or later. A Chromium-based browser is required at runtime. OrbitTest can use the system Chrome installation, or you can set a custom executable path through the environment.

For Android testing, install Android platform-tools and make sure `adb devices` can see the target device. USB debugging must be enabled on the phone.

Local install

Most projects should install OrbitTest as a development dependency. This keeps the test runner version locked with the project and makes CI reproducible.

Global install

A global install is convenient for trying commands quickly, but production projects should still keep a project-local dependency so the whole team and CI use the same version.

Practical checklist

• Keep the workflow readable enough that a QA engineer, developer, or product teammate can understand the intent without opening application source code.
• Prefer user-visible names, stable configuration, and clear evidence over hidden assumptions or brittle implementation details.
• Run the smallest useful check locally before adding it to CI, then verify that failures produce screenshots, logs, traces, or reports that explain what happened.
• Review this part of the suite regularly so outdated examples, stale setup, and obsolete workarounds do not reduce trust in the automation.

Common mistakes to avoid

• Do not add automation only to increase test count. Each page and test should protect a clear user journey, release risk, or debugging need.
• Do not hide important behavior inside helpers so deeply that the test no longer explains what the user is doing.
• Do not rely on fixed sleeps when the application can expose a meaningful ready state such as visible text, URL change, element availability, or completed evidence capture.
• Do not ignore failing artifacts. A report, screenshot, trace, or log entry should feed back into better product code, better waits, or clearer test data setup.