Quick Start

Step 1: Create a project

Open Studio and click New Project, or open an existing folder. A Studio project is just a directory; keep tests under a tests/ folder so runs and reports stay organized:

my-qa-project/
  tests/
    smoke.test.js
  .orbitest/
    runs/          # created automatically, one folder per run

Step 2: Connect a device

Plug in the phone (USB debugging enabled, Companion installed, see Studio Installation if you have not done this). The device appears in the Devices panel. Click Ping on the device card to confirm the Companion bridge is alive, then open the Live panel to see the mirror.

Step 3: Write a smoke test

Create tests/smoke.test.js. Start with the smallest test that proves the whole pipeline: device wakes, app launches, expected screen appears:

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

test("login smoke test", async (orbit) => {
  // Wake the device and launch the app
  await orbit.wakeUp();
  await orbit.launchApp("com.example.myapp", "com.example.myapp.MainActivity");

  // Interact by resource ID
  await orbit.waitForId("username_field", 10000);
  await orbit.tapById("username_field");
  await orbit.typeText("testuser@example.com");

  await orbit.tapById("password_field");
  await orbit.typeText("Test@123");

  await orbit.tapByText("Sign In");

  // Wait for the next screen, then assert
  await orbit.waitForText("Welcome", 10000);
  expect(await orbit.hasText("Welcome")).toBe(true);
});

tests/smoke.test.js — the canonical first mobile test.

Not sure what the resource IDs are? Open the Inspector, click the element on the hierarchy, and copy the generated tap code. That loop, inspect, copy, paste, is how most Studio tests get written.

Step 4: Run it

1. Select your device in the Devices panel.
2. With the test file open in the editor, choose a Run Configuration, Quick Run is right for a first test.
3. Click Run.
4. Watch the Console panel for live output while the mirror shows the device doing the work.

Each run writes a complete artifact folder:

<project>/.orbitest/runs/<timestamp>-<run-id>/
  run.json               # run metadata
  stdout.log              # everything the test printed
  studio-report.html      # the report
  final-screenshot.png    # device screen at the end
  device-recording.mp4    # video of the whole run

Run artifacts. The video alone settles most “what happened?” debates.

Step 5: Review the evidence

Open the Reports panel and select the run. The HTML report shows status, the step-by-step action log, the final screenshot, and the device recording in the frame evidence player. Get into the habit of reviewing evidence even for passing runs at first, it confirms the test is checking what you think it is checking, which is the difference between a test suite and a green light generator.

From here: the Mobile Test API reference covers everything orbit can do on a device, and Troubleshooting covers what to do when steps misbehave.

Frequently asked questions

Where do I find the app package and activity names?

Ask the developers, or with the app open run adb shell dumpsys window | findstr mCurrentFocus, the output shows package/activity. Studio’s device tooling can also surface the current activity.

Which Run Configuration should I default to?

Quick Run for everyday work, trace off, Smart Report on, video always. Switch to Trace Run or Evidence Run when investigating, and Minimal Run when you need maximum speed and no artifacts.

Can I run the same test from the terminal?

Yes: orbittest run tests/smoke.test.js with the mobile provider configured. Studio tests are plain OrbitTest files, that is the design.

Related pages

• Mobile Test API — The complete orbittest/mobile reference: app lifecycle, gestures, selectors, typing, waits, device state, and evidence capture.
• Features — A tour of Studio: OrbiStream live mirror, UI Inspector, logcat filters, the test runner with evidence reports, and the built-in IDE.
• Troubleshooting — Fixes for unauthorized devices, missing devices, blocked Companion installs, black mirror screens, and empty log panels.
• Mobile Testing — Android automation with ADB and UIAutomator through @orbittest/mobile: setup, configuration, hybrid tests, and evidence.