appwright

library0.1.45jsnpmunverified

Appwright (current version 0.1.45) is an open-source end-to-end testing framework designed for native mobile applications on both iOS and Android platforms. It differentiates itself by providing a Playwright-like API for mobile automation, building upon the industry-standard Appium for device interaction and leveraging Playwright's robust test runner and reporting capabilities. This integrated approach combines the automation driver, test runner, and test reporter into a single package, aiming to simplify mobile E2E testing which often involves complex setups. Appwright exposes an ergonomic API that includes auto-waiting and auto-retrying mechanisms for UI elements, making tests more readable and resilient to timing issues. As a relatively new project, it is currently in pre-1.0.0 development, indicated by its frequent patch releases, and is actively seeking community feedback and contributions to mature towards a stable major release. It supports testing on local devices, emulators, and remote device farms like BrowserStack and LambdaTest.

testing web-framework

npm install appwright

github ↗package ↗

INSTALL

IMPORT

SIG · APPWRIGHT

appwright

testingjavascriptv0.1.45

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

test, expect

✓ import { test, expect } from 'appwright';

✗ const { test, expect } = require('appwright');

Appwright is primarily designed for ESM and TypeScript environments. CommonJS require() is not officially supported and may lead to issues.

defineConfig, Platform

✓ import { defineConfig, Platform } from 'appwright';

✗ const { defineConfig, Platform } = require('appwright');

These symbols are used for configuring Appwright, typically in `appwright.config.ts`.

device

✓ test('My test', async ({ device }) => { /* ... */ });

The `device` fixture is automatically provided to your test functions and represents the mobile device under test. It is the primary API for interacting with the application.

Demonstrates how to install Appwright, set up a basic configuration for Android and iOS projects, and write a simple E2E test to simulate user login.

import { defineConfig, Platform, test, expect } from "appwright"; // appwright.config.ts export default defineConfig({ projects: [ { name: "android", use: { platform: Platform.ANDROID, device: { provider: "emulator" }, buildPath: "app-release.apk" // Replace with your actual APK path } }, { name: "ios", use: { platform: Platform.IOS, device: { provider: "emulator" }, buildPath: "app-release.app" // Replace with your actual .app/.ipa path } } ] }); // tests/login.spec.ts test("User can login successfully", async ({ device }) => { await device.getByText("Username").fill("admin"); await device.getByText("Password").fill("password"); await device.getByText("Login").tap(); await expect(device.getByText("Welcome, admin!")).toBeVisible(); }); // To run: // npm install --save-dev appwright // touch appwright.config.ts (copy config above) // npx appwright test --project android

appwright --version

Debug

Known issues

gotchaAppwright requires Node.js version 18.20.4 or higher. Running with older Node.js versions may lead to installation failures or runtime errors.

fix

Ensure your Node.js environment meets the minimum requirement. Use nvm or your package manager to update Node.js to a supported version (e.g., `nvm install 18.20.4` or `nvm use 18.20.4`).

affects: <=0.1.45

gotchaWhen using remote device providers like BrowserStack or LambdaTest, you must configure authentication credentials (e.g., API keys, usernames) in your environment or Appwright configuration. Failure to do so will result in authentication errors when attempting to connect to the device farm.

fix

Refer to the documentation of your chosen cloud provider (BrowserStack, LambdaTest, etc.) for how to obtain and securely configure your API keys or access credentials, typically via environment variables or direct config properties.

affects: >=0.1.0

gotchaThe `buildPath` in `appwright.config.ts` must point to the correct application binary for the specified platform and provider. For Android, this is an `.apk` file. For iOS, it's typically a `.app` file for emulators or an `.ipa` file for real devices. Incorrect paths or file types will prevent tests from running.

fix

Verify the `buildPath` points to the correct, existing application file. Ensure the file type (`.apk`, `.app`, `.ipa`) matches the `platform` (Android/iOS) and `device.provider` (emulator/local-device/cloud-provider) requirements.

affects: >=0.1.0

gotchaAppwright is in active pre-1.0.0 development. While patch releases primarily focus on bug fixes, minor versions may introduce API changes or new features that could require adjustments to existing test code or configuration. Early adoption means a higher likelihood of needing to adapt to updates.

fix

Regularly review release notes for new versions. Consider pinning to specific patch versions (e.g., `~0.1.45`) in your `package.json` and testing updates in a controlled environment before deploying to critical CI/CD pipelines.

affects: <1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'appwright/appwright.config.ts'

The Appwright configuration file `appwright.config.ts` (or `.js`) is missing or incorrectly named in the project root.

fix

Create `appwright.config.ts` in your project's root directory and populate it with a valid Appwright configuration, as shown in the quickstart example.

Error: Project 'android' not found in appwright.config.ts. Available projects: [...]

The project name specified with `npx appwright test --project <name>` does not match any `name` property defined in the `projects` array within your `appwright.config.ts`.

fix

Ensure the project name passed via the `--project` flag exactly matches one of the `name` fields in your `appwright.config.ts`. Double-check for typos and casing.

Error: Build file not found at path: /path/to/your/app-release.apk

The `buildPath` specified in your `appwright.config.ts` points to a non-existent or inaccessible application binary file.

fix

Verify that the `buildPath` is correct and that the application binary file (e.g., `.apk`, `.app`, `.ipa`) actually exists at that location and is readable by the test runner.

TypeError: device.getByText is not a function

This typically occurs if the `device` fixture is not correctly destructured in the test function signature or if the Appwright setup is incomplete, preventing the device context from being correctly initialized.

fix

Ensure your test function properly destructures the `device` object from the fixture, e.g., `test('My test', async ({ device }) => { ... })`. Also, confirm that `appwright.config.ts` is correctly set up and Appwright is installed.

Upgrade

Version history

0.1.45latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/empirical-run/appwright ↗

packagehttps://www.npmjs.com/package/appwright ↗