Architecture

The layered design

OrbitTest is organized as seven internal modules, each with one responsibility. You never interact with most of them directly, but knowing the map makes the tool predictable, error messages, logs, and the docs all use these names.

Module	Responsibility
Orbit Shell	CLI entry point: parses commands and flags, discovers test files.
Orbit Core	The public API: test(), expect(), hooks, and the orbit object.
Mission Control	Scheduling: workers, retries, sharding, collecting results.
Capsule	Isolation: a fresh browser profile per test.
Surface	Locator resolution: turning “the Login button” into a real element.
Signal	Chrome DevTools Protocol communication with the browser.
Launchpad	Browser lifecycle: finding, starting, and stopping Chrome.

How a click travels through the stack

Follow one await orbit.click("Login") from your test file to the browser and back:

1. Orbit Core receives the call from your test and records it for tracing.
2. Surface resolves the target: it searches visible text, roles, labels, and accessible names for something a user would call “Login”, and reports ambiguity if several things match.
3. Signal sends the actual click over the Chrome DevTools Protocol, at real coordinates, with the red marker dot rendered first.
4. The browser (started and owned by Launchpad, inside a Capsule profile) performs the click like a real user input.
5. The result flows back up; Mission Control attributes it to the right test, attempt, and worker; reports record it.

This is why the layers stay separate: browser launching knows nothing about assertions, locator resolution knows nothing about CI sharding, and reports consume run data without ever controlling the browser. When something breaks, the layer names in the error tell you where to look.

The Android side

Mobile automation swaps the bottom of the stack while keeping the top. Your tests still go through Core and Mission Control, but instead of Signal and Launchpad talking CDP to Chrome, the @orbittest/mobile provider talks to ADB and reads UI state from UIAutomator. Orbittest Studio sits alongside as a desktop layer, and its Companion app on the device adds session support for screen mirroring and diagnostics.

Your test (orbittest/mobile API)
        |
   Orbit Core + Mission Control      (same as web)
        |
   @orbittest/mobile provider        (selector matching, artifacts, doctor)
        |
   ADB  +  UIAutomator               (device commands + UI hierarchy)
        |
   Android device  [Companion app]   (bridge, OrbiStream capture)

The mobile stack. The web and mobile providers are siblings under the same runner.

Why this matters to you as a user

• Reproducibility: Capsule’s per-test profiles are why state never leaks between tests, and why you must save/load sessions explicitly.
• Error quality: Surface owns ambiguity errors; if a locator fails, the explanation comes from the layer that actually searched.
• Portability: because providers plug in under the same Core, a web test and a mobile test look like siblings, and hybrid tests can hold both contexts.
• Stability: the public API (Core) is the contract. Internal layers can be reorganized, the current cleanup freeze is doing exactly that, without breaking your suites.

Frequently asked questions

Do I need to know these module names to use OrbitTest?

No. They are here so the docs, logs, and error messages have consistent names, and so contributors know where code lives.

Why CDP instead of WebDriver?

The Chrome DevTools Protocol gives direct, fast access to browser internals, console errors, network failures, HttpOnly cookies, screenshots, which is what powers traces and Smart Report. The trade-off is Chromium-only support.

Could other browsers be supported later?

The layering would allow another Signal/Launchpad implementation, but Firefox/WebKit support is not on the current roadmap.

Related pages

• Overview — Feature status, how a test run works from CLI to report, and which OrbitTest surface to use for each job.
• Roadmap — Current status and direction: browser diagnostics, mobile and Studio plans, API testing, and what is deliberately not planned.
• Contributing — How to propose changes, write bug reports that get fixed, follow the code standards, and report security issues privately.
• Mobile Testing — Android automation with ADB and UIAutomator through @orbittest/mobile: setup, configuration, hybrid tests, and evidence.