Mobile Testing

How OrbitTest does Android

OrbitTest keeps mobile support in a separate provider package, @orbittest/mobile, so the web runner stays small. The provider talks to Android devices directly through ADB (the Android Debug Bridge) and reads UI state through UIAutomator. There is no Appium server, no WebdriverIO, no Detox, no Maestro: one less moving part to install, version-match, and keep alive in CI.

npm install orbittest @orbittest/mobile

Requirements before anything will run:

• Android SDK platform-tools installed (for adb).
• USB debugging enabled on the device (Settings → About Phone → tap Build Number 7 times → Developer Options → USB Debugging).
• adb devices lists the phone as device, not unauthorized.
• A USB data cable. Charge-only cables are the single most common cause of “device not found”.

Configuration

module.exports = {
  use: {
    mobile: {
      provider: "@orbittest/mobile",
      platform: "android",
      adbPath: process.env.ADB_PATH || "adb",
      deviceSerial: process.env.DEVICE_SERIAL,
      apk: "./app.apk",
      appPackage: "com.myapp",
      appActivity: ".MainActivity",
      artifactsDir: "orbittest-results",
      screenshotOnFailure: true,
      logcatOnFailure: true,
      uiDumpOnFailure: true
    }
  }
};

The use.mobile block in orbittest.config.js.

The three *OnFailure switches are worth leaving on: when a mobile test fails, the provider saves a screenshot, the UIAutomator hierarchy dump, logcat output, and device/app metadata under orbittest-results/, exactly the evidence you need to debug a failure on a device you may no longer have in hand.

Writing a mobile test

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

test("mobile smoke test", async ({ orbit }) => {
  await orbit.wakeUp();
  await orbit.installApp();
  await orbit.launchApp();
  await orbit.waitForText("Login", 10000);
  await expect(orbit).toHaveText("Login");
});

Lifecycle, wait, assert: the smallest useful mobile test.

Mobile tests get mobile assertions: expect(orbit).toHaveText(), toHaveId(), and toMatchScreenshot() for visual comparison. The full method list, gestures, waits, selectors, evidence capture, lives on the Mobile Test API page.

Hybrid web + mobile tests

A test can receive both contexts and verify a flow that crosses devices, for example an account created on the web working in the app:

test("same user works on web and mobile", async ({ page, orbit }) => {
  await page.goto("https://app.example.com");
  await page.clickText("Create account");

  await orbit.installApp();
  await orbit.launchApp();
  await orbit.waitForText("Welcome");
});

Devices, doctor, and reports

orbittest devices   # list connected Android devices
orbittest doctor    # diagnose adb, device authorization, environment
orbittest run tests/mobile-smoke.test.js

Mobile test reports include a Mobile Evidence section: device and app details, screenshot preview, a UIAutomator summary, and links to the saved artifacts. Combined with the on-failure captures, a red mobile test in CI arrives with everything attached.

Common problems

Symptom	Fix
Device shows as unauthorized	Unlock the phone and accept the “Allow USB debugging?” prompt. If it never appears, unplug, replug, and confirm USB debugging is still enabled.
Device missing from adb devices	Swap to a known data cable and another USB port. Then check that platform-tools is installed and on PATH, or set ADB_PATH.
UIAutomator dump fails	Make sure the screen is awake (orbit.wakeUp()) and no system permission dialog is covering the app.
Studio-run tests cannot find the device	Confirm Studio passes DEVICE_SERIAL, ADB_PATH, and PROJECT_ROOT to the child Node.js process; orbittest doctor shows what the process actually sees.

For deeper Android troubleshooting, including mirroring and Companion app issues, see the Studio Troubleshooting page.

Frequently asked questions

Why not Appium?

Appium is powerful and cross-platform, but it adds a server, drivers, and version-matching overhead. For Android-only QA, talking to ADB and UIAutomator directly is simpler to install and debug. If you need iOS today, Appium remains the right tool.

Can I run mobile tests in CI?

Yes, if the CI runner can reach a device: a physical device farm, an emulator started in the pipeline, or a self-hosted runner with phones attached. The provider only needs a working adb connection.

Do mobile and web tests share the same report?

Yes. They run under the same runner and land in the same HTML/JSON/JUnit outputs, with mobile tests adding their Mobile Evidence section.

Related pages

• Mobile Test API — The complete orbittest/mobile reference: app lifecycle, gestures, selectors, typing, waits, device state, and evidence capture.
• What is Studio? — Orbittest Studio explained: a Windows desktop IDE that puts device mirror, inspector, logcat, editor, and test runner in one app.
• Troubleshooting — Fixes for unauthorized devices, missing devices, blocked Companion installs, black mirror screens, and empty log panels.
• Environment Variables — ORBITTEST_CHROME_PATH, sharding, CI flags, ADB and device selection, and how to keep secrets out of test files.