Overview
Feature status at a glance
Section titled “Feature status at a glance”Before you build a test suite on any tool, you should know which parts are stable and which are still moving. OrbitTest is explicit about this:
| Feature | Status |
|---|---|
| UI automation (click, type, navigate, assert) | Stable |
| Test lifecycle hooks | Stable |
| Intent-based locator engine | Stable |
| Browser storage and session management | Stable |
| Alerts, notifications, windows and tabs | Stable |
| Frames and Shadow DOM traversal | Stable |
| HTML / JSON / JUnit reports | Stable |
| CI mode: sharding, fail-fast, annotations | Stable |
| Step trace and trace timeline | Stable |
| Smart Report (browser evidence collection) | Stable |
| OrbitTest UI local dashboard | Stable |
| Forge test recorder | Stable |
| Android mobile provider (@orbittest/mobile) | Phase 1 |
| Visual automation (canvas, WebGL, pixel checks) | Experimental |
| API testing | Planned |
Anything marked Stable is safe to build a production suite on. Phase 1 means the feature works and is shipping, but the API surface may still grow. Experimental features are usable but their edge cases are less covered.
How a test run works
Section titled “How a test run works”It helps to know what actually happens when you type orbittest run. The flow has six steps:
- The CLI reads
orbittest.config.jsand discovers test files matching yourtestMatchpatterns (by defaulttests/**/*.test.jsandtests/**/*.spec.js). - A scheduler assigns tests to workers. With
workers: 1everything runs in sequence; with more workers, tests run in parallel. - Each test gets a fresh Chrome profile, so cookies or storage from one test can never leak into another.
- Your test code runs. Every
orbit.*call goes through the locator engine, which resolves visible text, labels, and roles into real page elements over the Chrome DevTools Protocol. - If a test fails and retries are enabled, it runs again. A test that fails then passes is recorded as flaky, not silently green.
- Reports are written: an HTML dashboard for humans, JSON for scripts, JUnit XML for CI systems, plus screenshots and traces under
reports/runs/<run-id>/.
The pieces and when to use them
Section titled “The pieces and when to use them”OrbitTest is one npm package, but you interact with it through several surfaces. Each has a clear job:
| Surface | Command | Use it when |
|---|---|---|
| Test runner | orbittest run | You want to run tests locally or in CI. |
| Local dashboard | orbittest ui | You want to run tests, toggle trace or Smart Report, and browse old reports without touching folders. |
| Forge recorder | orbittest forge | You want a starting script generated from clicking through a flow yourself. |
| Doctor | orbittest doctor | Something is wrong with your environment and you want a diagnosis. |
| Device list | orbittest devices | You are doing Android work and want to see connected devices. |
| Studio | Desktop app | You do Android QA daily and want mirror, inspector, logs, editor, and runner in one window. |
What OrbitTest deliberately does not do
Section titled “What OrbitTest deliberately does not do”Knowing the boundaries saves you time. OrbitTest does not run Firefox or Safari; it is built on the Chrome DevTools Protocol. It does not include an API testing client yet (that is planned). It does not use Appium, WebdriverIO, Detox, or Maestro for mobile work; the Android provider talks to ADB and UIAutomator directly, which keeps the stack small but also means iOS is out of scope for now.
It also does not try to be a unit test runner. Use it for user journeys: login, search, checkout, onboarding, the flows that would embarrass you if they broke in production.
Frequently asked questions
Section titled “Frequently asked questions”How is this different from Playwright or Cypress?
Section titled “How is this different from Playwright or Cypress?”The main difference is the locator philosophy: OrbitTest resolves visible text and labels first, so most tests contain no selectors at all. It also bundles an Android provider and a desktop IDE for mobile QA, which neither tool offers.
Can I mix web and mobile tests in one project?
Section titled “Can I mix web and mobile tests in one project?”Yes. A hybrid test can receive both a page (browser) and an orbit (Android) context, so you can verify that an account created on the web works in the app. See Mobile Testing.
Does parallel execution need extra setup?
Section titled “Does parallel execution need extra setup?”No. Set workers in config or pass --workers 4 on the command line. For splitting across CI machines, use --shard 1/4 style sharding.
Related pages
Section titled “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.
- Architecture — The seven internal modules, how a click travels from your test to the browser, and how the Android stack swaps in.
- CLI Reference — Every OrbitTest command and flag: run, init, ui, forge, devices, doctor, and clean-reports, with recommended npm scripts.