Appwright: Mobile E2E Testing Framework

0.1.45 verified Sun Apr 19 auth: no javascript

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.

Common errors

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

cause 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 Error: Project 'android' not found in appwright.config.ts. Available projects: [...] ↓

cause 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 Error: Build file not found at path: /path/to/your/app-release.apk ↓

cause 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.

error TypeError: device.getByText is not a function ↓

cause 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.

Warnings

gotcha Appwright 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`).

gotcha When 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.

gotcha The `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.

gotcha Appwright 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.

Install

npm install appwright

yarn add appwright

pnpm add appwright

Imports

test, expect
wrong
```
const { test, expect } = require('appwright');
```
correct
```
import { test, expect } from 'appwright';
```
Appwright is primarily designed for ESM and TypeScript environments. CommonJS require() is not officially supported and may lead to issues.
defineConfig, Platform
wrong
```
const { defineConfig, Platform } = require('appwright');
```
correct
```
import { defineConfig, Platform } from '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.

Quickstart

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