🚀 OrbitTest

Intent-based browser automation testing made simple

OrbitTest is a lightweight end-to-end testing tool that lets you write tests using what users see instead of complex selectors.

⚡ Quick Example

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

test("Login flow", async (orbit) => {
  await orbit.open("https://example.com");
  await orbit.click("Login");
  await orbit.type("Email", "[email protected]");

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

👉 No CSS 👉 No XPath 👉 Just intent

🎯 Why OrbitTest?

OrbitTest focuses on simplicity and readability.

Instead of writing:

await orbit.click("#login-btn");

You can write:

await orbit.click("Login");

Benefits

• ✔ Faster test creation
• ✔ Less maintenance
• ✔ Human-readable tests
• ✔ Works with modern UI

📦 Installation

npm install 
npm install -g orbittest

Check installation:

orbittest --version

🚀 Getting Started

Initialize project

orbittest init

This creates:

orbittest.config.js
tests/
  example.test.js
reports/

Run tests

orbittest run

Or:

npm run test:e2e

🧪 Writing Tests

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);
});

Hooks and per-test options are supported:

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

beforeEach(async (orbit, testInfo) => {
  console.log(`Starting ${testInfo.name}`);
});

afterEach(async (orbit, testInfo) => {
  console.log(`Finished ${testInfo.name}`);
});

test("retry a slow flow", { retries: 1, timeout: 30000 }, async (orbit) => {
  await orbit.open("https://example.com");
});

🌐 Browser Actions

Configuration

OrbitTest reads orbittest.config.js from your project root:

module.exports = {
  testDir: "tests",
  testMatch: ["**/*.test.js", "**/*.spec.js"],
  reportsDir: "reports",
  workers: 1,
  maxWorkers: 4,
  retries: 0,
  testTimeout: 30000,
  actionTimeout: 0,
  environments: {
    staging: {
      reportsDir: "reports/staging"
    }
  }
};

CLI flags override config values, for example orbittest run --workers 2 --retries 1 --timeout 30000 --env staging.

Test files are run by the CLI, so you do not need run() in each test file.

Open a page

await orbit.open("https://example.com");

Click by visible text

await orbit.click("Login");

Mouse actions

await orbit.hover("Menu");
await orbit.doubleClick("Open");
await orbit.rightClick("File");

Click actions show a short red dot at the actual browser coordinate. This makes live debugging and trace screenshots easier to follow.

await orbit.click("Login");
await orbit.doubleClick("Open");
await orbit.rightClick("File");

Disable the marker for a single action when needed:

await orbit.click("Login", { visualize: false });

Type into input

await orbit.type("Email", "[email protected]");

Matches using:

• label
• placeholder
• name
• accessible text

Check visible text

const exists = await orbit.hasText("Welcome");

Take screenshot

await orbit.screenshot("reports/home.png");

⏳ Waiting for Page Changes

Modern apps update dynamically. Use waits before interacting.

Wait for text

await orbit.waitForText("Dashboard");

Wait for element

await orbit.waitFor(orbit.css(".toast"));

Custom timeout

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

Avoid fixed waits

await orbit.wait(1000); // avoid when possible

Prefer:

await orbit.waitFor("Dashboard");

🎯 Locators (When Needed)

OrbitTest is intent-first, but supports locators for precision.

CSS

await orbit.click(orbit.css("#login"));

XPath

await orbit.click(orbit.xpath("//button[text()='Login']"));

Role

await orbit.click(orbit.getByRole("button", "Login"));

Attribute

await orbit.click(orbit.getByAttribute("data-testid", "submit"));

Direct object

await orbit.click({ css: "#login" });

👉 Use text-based actions by default 👉 Use locators when needed

🔍 Working with Elements

Check if element exists

expect(await orbit.exists(orbit.css(".success"))).toBe(true);

Read element text

const title = await orbit.text(orbit.getByRole("heading", "Dashboard"));

📊 Reports

After each run:

reports/latest.html
reports/latest.json

Includes

• Total tests
• Passed / Failed
• Duration
• Error details
• Stack trace
• Screenshot path

Step trace

Use --trace when you want a step-by-step report after the run:

orbittest run tests/login.test.js --trace

The HTML report links to each trace. A trace includes every orbit.* step, status, duration, URL/title, and screenshots under:

reports/artifacts/<run-id>/traces/

Use --step when you want live, step-by-step debugging:

orbittest run tests/login.test.js --step

Step mode opens a small Orbit Inspector window in OrbitTest's managed testing browser, not your default browser. It runs with one worker, disables test/action timeouts, pauses before each orbit.* action, and keeps the browser open until you continue at the end. It also writes a trace automatically.

Click actions are marked with a red dot in the test browser, so you can see exactly where OrbitTest clicked while stepping through the test.

Failure screenshots

reports/artifacts/

🧠 Best Practices

• Prefer intent-based actions:

  await orbit.click("Login");

• Wait before interacting:

  await orbit.waitFor("Dashboard");

• Use locators only when needed

• Avoid fixed delays

⚠️ Common Issues

Element not found

→ Ensure text is visible → Use waitFor() before clicking

Multiple matches

→ Use locator for precision

Slow page

→ Increase timeout

await orbit.waitForText("Dashboard", 10000);

🔍 Test Discovery

OrbitTest automatically finds:

tests/**/*.test.js
tests/**/*.spec.js

🖥️ CLI Usage

Run all tests:

orbittest run

Run specific file:

orbittest run tests/login.test.js

Run folder:

orbittest run tests

Run in parallel:

orbittest run --workers 4

Or set workers in orbittest.config.js.

Create a step-by-step trace:

orbittest run tests/login.test.js --trace

Live step debugging:

orbittest run tests/login.test.js --step

Override config from the CLI:

orbittest run --retries 2 --timeout 30000 --reports-dir reports/debug

🌍 Browser Behavior

• Fresh browser per test
• No cookies or cache
• No extensions
• Fully isolated environment

⚙️ Custom Browser

set ORBITTEST_CHROME_PATH=C:\Path\To\chrome.exe
orbittest run

🚧 Current Limitations

• Limited smart matching
• Basic wait system

🚀 Roadmap

• Smart element detection
• Improved wait system
• Headless mode
• CI integrations

🧠 Philosophy

Test what users see, not what developers write.

🤝 Contributing

Contributions are welcome.

1. Fork
2. Create branch
3. Submit PR

📄 License

Apache-2.0

Keywords

browser automation, testing, e2e, test runner, Chrome, CDP