Installation & Setup

Install Mobilewright with npm, scaffold a project, understand the config file, and verify your environment with the doctor command.

Installing Mobilewright

Mobilewright is installed from npm like any other Node.js package. You need two packages: mobilewright (the engine and CLI) and @mobilewright/test (the test runner API).

npm install mobilewright @mobilewright/test

Next, scaffold a new project. This one command creates the configuration file and an example test for you. If either file already exists, it is skipped — so it is always safe to run:

npm init mobilewright@latest

Directory Layout

After initialization your project looks like this — one config file and a tests folder:

mobilewright.config.ts
package.json
package-lock.json
tests/
  example.test.ts

The Config File

The config file is the heart of your project. It tells Mobilewright which platform to target, which app to install and launch, and which device to use. You can write it in TypeScript (mobilewright.config.ts) or JavaScript (mobilewright.config.js) — both work out of the box.

import { defineConfig } from 'mobilewright';

export default defineConfig({
  platform: 'ios',
  bundleId: 'com.example.myapp',
  deviceName: /iPhone 16/,
  installApps: './builds/myapp.ipa',
  timeout: 10_000,
});

const { defineConfig } = require('mobilewright');

module.exports = defineConfig({
  platform: 'ios',
  bundleId: 'com.example.myapp',
  deviceName: /iPhone 16/,
  installApps: './builds/myapp.ipa',
  timeout: 10_000,
});

Each option is simple: platform is 'ios' or 'android', bundleId is your app's identifier, deviceName is a pattern to match a simulator or device, installApps points to your IPA/APK build, and timeout is the default wait time in milliseconds.

Verify Your Environment

Before running anything, let Mobilewright check that your machine is ready. The doctor command inspects Node.js, Xcode, the Android SDK, connected devices, and more — and tells you exactly what is missing:

npx mobilewright doctor

# System
#   ✓  Node.js   v22.19.0
#   ✓  mobilecli devices  2 online devices
# iOS
#   ✓  Xcode 26.0.1, 62 simulators available
# Android
#   ✓  ADB, Emulator, ANDROID_HOME
# Summary: Ready for mobile development!

Run the Example Test

npx mobilewright test

If you see a green checkmark, your setup is complete. In the next chapter we will look at what is actually inside that test file.