mobilewright

library0.0.41jsnpmunverified

Mobilewright is a mobile device automation framework for iOS and Android, inspired by Playwright's architecture and developer experience. Current stable version is 0.0.41, released as a pre-1.0 alpha with frequent updates. It provides a cross-platform API for tapping, filling, and asserting on mobile apps using semantic locators (getByRole, getByLabel, getByText) and built-in auto-waiting. Unlike Appium (verbose WebDriver, manual waits) and Detox (React Native only), Mobilewright offers a zero-config setup, accessibility-tree-based interaction optimized for AI agents, and remote device support via mobilecli. It is ESM-only, requires Node >=18, and ships TypeScript types.

testing

npm install mobilewright

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MOBILEWRIGHT

mobilewright

testingjavascriptv0.0.41

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ios

✓ import { ios } from 'mobilewright'

✗ const mobilewright = require('mobilewright'); const ios = mobilewright.ios;

Mobilewright is ESM-only. reqire will fail in Node <22 with --experimental-require-module.

android

✓ import { android } from 'mobilewright'

✗ import { android, ios } from 'mobilewright/ios'

Both iOS and Android launchers are exported from the main package. No subpath exports.

expect

✓ import { expect } from 'mobilewright'

✗ import { expect } from '@mobilewright/test'

expect is also re-exported from the main package for standalone use. @mobilewright/test is for Playwright Test integration.

Launches an iOS app, fills login fields, taps Sign In, asserts welcome text visible, and takes a screenshot.

import { ios, expect } from 'mobilewright'; const device = await ios.launch({ bundleId: 'com.example.myapp' }); const { screen } = device; await screen.getByLabel('Email').fill('user@example.com'); await screen.getByLabel('Password').fill('password123'); await screen.getByRole('button', { name: 'Sign In' }).tap(); await expect(screen.getByText('Welcome back')).toBeVisible(); const screenshot = await screen.screenshot(); await device.close();

Debug

Known issues

breakingVersion 0.x: frequent breaking changes; lock to exact version in production

fix

Pin exact version in package.json: "mobilewright": "0.0.41"

affects: <1.0.0

gotchaESM-only package; CommonJS require() throws an error in Node <22 without experimental flags

fix

Use import syntax or upgrade Node >=22 and set --experimental-require-module

affects: >=0.0.0

gotcha`ios.launch()` and `android.launch()` require a valid bundleId/packageName; no autodetect for installed apps

fix

Always pass `bundleId` for iOS or `packageName` for Android

affects: >=0.0.0

deprecated`screen.find()` / `screen.findAll()` are deprecated in favor of `screen.getBy*` locators

fix

Replace with `screen.getByRole()`, `screen.getByLabel()`, etc.

affects: >=0.0.20

Errors

Common errors & fixes

Error: Could not resolve 'mobilewright' (ESM)

Using require() in a CommonJS project

fix

Convert to ESM ("type": "module" in package.json) or use dynamic import: const { ios } = await import('mobilewright')

TypeError: ios.launch is not a function

Wrong import: imported the default export (which doesn't exist) instead of named export

fix

Use `import { ios } from 'mobilewright'` instead of `import ios from 'mobilewright'`

Error: No booted simulator found

No iOS simulator or Android emulator running

fix

Boot a simulator: `xcrun simctl boot <device>` (iOS) or `emulator -avd <avd> &` (Android), then run `npx mobilewright doctor`

Error: bundleId is required

Attempting to launch iOS without specifying the app's bundle identifier

fix

Pass `bundleId` to `ios.launch()`: `await ios.launch({ bundleId: 'com.example.app' })`

Upgrade

Version history

0.0.41latest on npm

Audit

Dependencies

mobileclirequiredUnderlying device communication protocol (iOS/Android automation backend)

Agent activity

3 hits · last 30 days

node

Resources

githubhttps://github.com/mobile-next/mobilewright ↗

packagemobilewright ↗

homepagehttps://mobilewright.dev ↗