Quick Start

Step 1: Create a project

From the root of any folder, run the init command:

npx orbittest init

This creates the minimum structure you need:

orbittest.config.js   # configuration (the defaults are fine to start)
tests/
  example.test.js     # a working sample test
reports/              # where run results land

Files created by orbittest init.

When possible, init also adds a test:e2e script to your package.json so the suite runs with npm run test:e2e.

Step 2: Write your first test

Create tests/home.test.js. A first test should check one real thing, not a whole user journey:

const { test, expect } = require("orbittest");

test("home page loads", async (orbit) => {
  await orbit.open("https://example.com/");

  expect(await orbit.hasText("Example Domain")).toBe(true);
});

tests/home.test.js

Three things are happening here. test() registers a test with a readable name. The callback receives orbit, the object you use for every browser action. And expect() is the assertion: the test passes only if the page really shows that text.

Step 3: Run it

npx orbittest run

A Chrome window opens (tests are visible by default on your local machine, hidden in CI), the test runs, and you get a clean summary:

Passed: 1
Failed: 0
Report: reports/runs/<run-id>/report.html

Typical output of a passing run.

You can also target one file or one folder:

npx orbittest run tests/home.test.js
npx orbittest run tests

Step 4: Read the report

Open the HTML report path printed at the end of the run. Even for a passing test, it is worth a look: you will see the test name, duration, and status laid out the way your team will see them when something fails in CI.

Now break the test on purpose. Change the expected text to something wrong and run again. Two things happen: OrbitTest captures a failure screenshot, and on local machines it starts a small report server and opens the failed report in your browser automatically. This is the debugging loop you will live in, so it is worth seeing once with a failure you understand.

Note

You can suppress the auto-opening report with --no-open-report-on-failure, or pin its port with --report-port 9323. In CI it never opens.

Step 5: A more realistic test

Real flows involve typing, waiting, and multiple assertions. Here is the shape of a login test:

const { test, expect } = require("orbittest");

test("login flow", async (orbit) => {
  await orbit.open("https://example.com/login");

  await orbit.type("Email", "user@example.com");
  await orbit.type("Password", "secret");
  await orbit.click("Login");

  await orbit.waitForText("Dashboard", { timeout: 10000 });

  expect(await orbit.hasText("Dashboard")).toBe(true);
});

A login test using only visible labels.

Notice waitForText. Modern pages update after navigation, so you wait for a meaningful state instead of sleeping for a fixed time. This single habit prevents most flaky tests; the Working with Elements page goes deeper.

Where to go next

• Test Basics — how to structure tests that stay readable as the suite grows.
• Locators — what to do when visible text is ambiguous.
• Configuration — workers, retries, timeouts, and environments.
• Reports & Diagnostics — traces, Smart Report, and debugging failures.

Frequently asked questions

Do I need a website of my own to practice?

No. You can point tests at any public site, or use data:text/html,... URLs to load inline HTML, which is how many examples in these docs work without any server.

Why did a browser window open during the run?

Locally, OrbitTest shows the browser by default so you can watch what the test does. Hide it with --hide-browser, or set browser.display in config. CI runs are hidden automatically.

Where are my old test results?

Every run is kept under reports/runs/<run-id>/, and reports/latest.html always points at the newest one. Clean old runs with orbittest clean-reports.

Related pages

• Test Basics — How to structure readable end-to-end tests: arrange-act-assert, the orbit object, per-test options, and strong assertions.
• Locators — Target elements by visible text first, then by role, test ID, CSS, or XPath when needed, and which selectors to avoid.
• Configuration — Every orbittest.config.js option explained: workers, retries, timeouts, browser display, CI behavior, and named environments.
• Reports & Diagnostics — HTML, JSON, and JUnit reports, trace timelines, Smart Report browser evidence, step mode, and report cleanup.