Environment:Nightwatchjs Nightwatch Android Mobile Testing
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Mobile_Testing |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Android mobile testing environment requiring `ANDROID_HOME`, the `@nightwatch/mobile-helper` package, and Appium configuration for device automation.
Description
Nightwatch.js supports Android mobile testing through Appium integration. This environment requires the Android SDK with `ANDROID_HOME` properly configured, the `@nightwatch/mobile-helper` optional package for device management, and Nightwatch configured with `selenium.use_appium: true`. Android platform detection works through either `platformName: 'android'` in capabilities or by specifying `androidPackage` in Chrome/Firefox options. The mobile helper assists with SDK path resolution, device listing, and binary location.
Usage
Use this environment when running Nightwatch tests on Android devices or emulators. It is required for mobile web testing (Chrome/Firefox on Android) and native app testing via Appium. This environment is activated when `desiredCapabilities.platformName` is set to `'android'` or when Chrome/Firefox options include an `androidPackage` field. Parallel test execution is automatically disabled for mobile platforms when not using a remote WebDriver server.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, Windows | Android SDK is cross-platform |
| Runtime | Node.js >= 18.20.5 | Base Nightwatch requirement |
| Android SDK | Android SDK with platform-tools | For ADB and device management |
| Java | JDK 11+ | Required by Android SDK tools |
| Device | Android emulator or physical device | Connected via USB or emulator |
| Appium | Appium server | For WebDriver-to-device communication |
Dependencies
System Packages
- Android SDK (platform-tools, build-tools)
- Java JDK 11+
- Appium server (global or local installation)
Node.js Packages
- `nightwatch` >= 3.15.0
- `@nightwatch/mobile-helper` (must be installed as project dependency)
Credentials
The following environment variable must be set:
- `ANDROID_HOME`: Path to the Android SDK installation directory. Must be a valid, resolvable path. Nightwatch throws `AndroidHomeError` if this is not set or not a valid path.
Quick Install
# Set Android SDK path
export ANDROID_HOME="$HOME/Android/Sdk"
# Install Nightwatch with mobile helper
npm install nightwatch @nightwatch/mobile-helper --save-dev
# Install Appium
npm install -g appium
Code Evidence
Android platform detection from `lib/utils/mobile.js:32-46`:
function isAndroid(desiredCapabilities = {}){
const {platformName} = desiredCapabilities;
if (platformName && platformName.toLowerCase() === 'android') {
return true;
}
const options = desiredCapabilities['goog:chromeOptions'] ||
desiredCapabilities['moz:firefoxOptions'];
if (options && options.androidPackage) {
return true;
}
return false;
}
ANDROID_HOME requirement from `lib/utils/mobile.js:140-146`:
function getSdkRootFromEnv() {
const androidHome = process.env.ANDROID_HOME;
if (androidHome) {
return process.env.ANDROID_HOME = path.resolve(untildify(androidHome));
}
throw new AndroidHomeError(androidHome);
}
Mobile helper import with version check from `lib/utils/mobile.js:10-25`:
function requireMobileHelper() {
try {
return require('@nightwatch/mobile-helper');
} catch (err) {
if (err.code === 'MODULE_NOT_FOUND') {
err.message = `@nightwatch/mobile-helper needs to be installed as a project
dependency. You can install @nightwatch/mobile-helper from NPM using:\n\n
npm i @nightwatch/mobile-helper --save-dev`;
} else if (!semver.satisfies(process.version, '>=14.0.0')) {
err.message = 'You are using Node ' + process.version +
', but @nightwatch/mobile-helper requires Node >= v14.0.0.';
}
throw err;
}
}
Parallelism disabled for mobile from `lib/runner/cli/cli.js:471-478`:
if (isMobile(desiredCapabilities) && !this.usingServer(this.testEnvSettings[env])) {
if (Concurrency.isWorker()) {
Logger.info('Disabling parallelism while running tests on mobile platform');
}
return false;
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ANDROID_HOME environment variable is NOT set or is NOT a valid path!` | Missing or invalid `ANDROID_HOME` | Set `export ANDROID_HOME="$HOME/Android/Sdk"` |
| `@nightwatch/mobile-helper needs to be installed as a project dependency` | Missing mobile helper package | `npm i @nightwatch/mobile-helper --save-dev` |
| `You are using Node vX, but @nightwatch/mobile-helper requires Node >= v14.0.0` | Node.js version too old for mobile helper | Upgrade Node.js (should already be >= 18.20.5 for Nightwatch) |
| `Disabling parallelism while running tests on mobile platform` | Parallel mode not supported for local mobile | Use a remote WebDriver server for parallel mobile tests |
Compatibility Notes
- Android Emulator: Fully supported. Requires Android SDK emulator and system images.
- Physical Android Device: Supported via USB debugging. ADB must detect the device.
- Chrome on Android: Set `goog:chromeOptions.androidPackage` to `'com.android.chrome'`.
- Firefox on Android: Set `moz:firefoxOptions.androidPackage` to `'org.mozilla.firefox'`.
- Parallel Execution: Disabled automatically for mobile platforms when using local drivers. Use BrowserStack or Selenium Grid for parallel mobile testing.
- iOS: Separate environment; uses `platformName: 'ios'` and `safari:useSimulator` capability.