Getting Started

Introduction

Start here if you are new to OrbitTest and want the mental model before writing tests.

Page1 of 28

Reading timeCalculating

Sections0

Documentation goal: this page is written as practical product documentation, with enough context to help a real QA engineer decide how to use the feature in a maintainable test suite.

What OrbitTest is for

OrbitTest is a browser and Android testing project built around a simple QA idea: tests should describe what the user can see and do. Instead of starting every browser test with CSS selectors or XPath, OrbitTest lets you click visible labels, type into fields by their user-facing names, and assert text that appears on the page.

That approach makes tests easier to read during review and easier to maintain after UI refactors. If a developer changes a class name but the button still says "Sign in", a user did not experience a different workflow and your test should not fail for a purely internal change.

Who should use it

OrbitTest is useful for QA engineers, developers, and small product teams who want end-to-end coverage without writing a heavy framework around the test runner. It is also useful for teams that need browser reports, CI artifacts, screenshots, traces, and Android evidence in one workflow.

The project is intentionally practical. It does not try to replace unit tests, API tests, manual exploratory testing, or product review. It gives teams a way to automate critical journeys while keeping those automated checks readable.

A first mental model

Think of each OrbitTest test as a user story with evidence. A test opens a page, performs user-visible actions, waits for meaningful state, and records what happened. When it fails, the report should help you decide whether the application broke, the environment broke, or the test no longer describes the product correctly.

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

test('user can reach the dashboard', async (orbit) => {
  await orbit.open('https://app.example.com');
  await orbit.click('Sign in');
  await orbit.type('Email', 'qa@example.com');
  await orbit.type('Password', 'secret');
  await orbit.click('Continue');

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

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.

Was this page useful?

Your response is saved in this browser and helps shape the docs experience.