npm package: @samsara-dev/appwright
Description: E2E mobile app testing done right, with the Playwright test runner
Author: bheem.reddy@samsara.com
Latest version: 0.13.0

# Appwright

![NPM Version](https://img.shields.io/npm/v/@samsara-dev/appwright?color=4AC61C)

Appwright is a test framework for e2e testing of mobile apps. Appwright builds on top of [Appium](https://appium.io/docs/en/latest/), and can
run tests on local devices, emulators, and remote device farms — for both iOS and Android.

Appwright is one integrated package that combines an automation driver, test runner and test
reporter. To achieve this, Appwright uses the [Playwright](https://github.com/microsoft/playwright) test runner internally, which is
purpose-built for the e2e testing workflow.

Appwright exposes an ergonomic API to automate user actions. These actions auto-wait and auto-retry
for UI elements to be ready and interactable, which makes your tests easier to read and maintain.

```ts
import { test, expect } from "@samsara-dev/appwright";

test("User can login", async ({ device }) => {
  await device.getByText("Username").fill("admin");
  await device.getByText("Password").fill("password");
  await device.getByText("Login").tap();
});
```

Links to help you get started.

- [Example project](https://github.com/empirical-run/appwright/tree/main/example)
- [Launch blog post](https://www.empirical.run/blog/appwright)
- [Documentation](#docs)

## Usage

### Minimum requirements

- Node 24.12.0 or higher (Appium 3 requirement)

### Install

```sh
npm i --save-dev @samsara-dev/appwright
touch appwright.config.ts
```

### Configure

```ts
// In appwright.config.ts
import { defineConfig, Platform } from "@samsara-dev/appwright";
export default defineConfig({
  projects: [
    {
      name: "android",
      use: {
        platform: Platform.ANDROID,
        device: {
          provider: "emulator", // or 'local-device' or 'browserstack'
        },
        buildPath: "app-release.apk",
      },
    },
    {
      name: "ios",
      use: {
        platform: Platform.IOS,
        device: {
          provider: "emulator", // or 'local-device' or 'browserstack'
        },
        buildPath: "app-release.app", // Path to your .app file
      },
    },
  ],
});
```

### Configuration Options

- `platform`: The platform you want to test on, such as 'android' or 'ios'.

- `provider`: The device provider where you want to run your tests.
              You can choose between `browserstack`, `lambdatest`, `emulator`, `local-device`, or `aws-device-farm`.

- `buildPath`: The path to your build file. For Android, it should be an APK file.
               For iOS, if you are running tests on real device, it should be an `.ipa` file. For running tests on an emulator, it should be a `.app` file.

### Run tests

To run tests, you need to specify the project name with `--project` flag.

```sh
npx appwright test --project android
npx appwright test --project ios
```

#### Run tests on BrowserStack

Appwright supports BrowserStack out of the box. To run tests on BrowserStack, configure
the provider in your config.

```ts
{
  name: "android",
  use: {
    platform: Platform.ANDROID,
    device: {
      provider: "browserstack",
      // Specify device to run the tests on
      // See supported devices: https://www.browserstack.com/list-of-browsers-and-platforms/app_automate
      name: "Google Pixel 8",
      osVersion: "14.0",
      appiumVersion: "3.1.0", // Override if your BrowserStack account does not yet support Appium 3
      appProfiling: true, // Optional: enable BrowserStack App Performance profiling
      idleTimeout: 300, // Optional: max session idle time in seconds (default: 180)
    },
    buildPath: "app-release.apk",
  },
},
```

#### iOS App Settings (BrowserStack)

Configure iOS permissions by default in your config:

```ts
{
  name: "ios",
  use: {
    platform: Platform.IOS,
    device: {
      provider: "browserstack",
      name: "iPhone 16 Pro",
      osVersion: "18",
      updateAppSettings: {
        "Permission Settings": {
          Location: {
            "ALLOW LOCATION ACCESS": "Always",
            "Precise Location": "ON"
          }
        }
      }
    },
    buildPath: "bs://<app-id>",
  },
}

// Tests run with permissions already granted - no setup needed!
```

See the [iOS App Settings documentation](./docs/ios-app-settings-browserstack.md) for more details.

#### Run tests on LambdaTest

Appwright supports LambdaTest out of the box. To run tests on LambdaTest, configure
the provider in your config.

```ts
{
  name: "android",
  use: {
    platform: Platform.ANDROID,
    device: {
      provider: "lambdatest",
      // Specify device to run the tests on
      // See supported devices: https://www.lambdatest.com/list-of-real-devices
      name: "Pixel 8",
      osVersion: "14",
      appiumVersion: "3.1.0", // Override if your LambdaTest account does not yet support Appium 3
    },
    buildPath: "app-release.apk",
  },
},
```

#### Run tests on AWS Device Farm

Appwright can connect to AWS Device Farm remote access sessions. Configure the provider in your config and supply either a Device Farm `appArn` or a local `buildPath` that Appwright can upload during global setup.

```ts
{
  name: "ios",
  use: {
    platform: Platform.IOS,
    appBundleId: "com.example.myapp",
    buildPath: "./builds/MyApp.ipa",
    device: {
      provider: "aws-device-farm",
      projectArn: "arn:aws:devicefarm:us-west-2:123456789012:project:abc123",
      deviceArn:
        "arn:aws:devicefarm:us-west-2::device:Apple:iPhone.15.Pro:17.5",
      interactionMode: "VIDEO_ONLY",
      sessionName: "smoke-suite",
    },
  },
},
```

Set the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and (optionally) `AWS_SESSION_TOKEN` & `AWS_REGION` environment variables before running the tests.

Appwright always requests Device Farm video recordings and attaches the MP4 to Playwright reports once the session completes.

## Run the sample project

To run the sample project:

- Navigate to the `example` directory.

```sh
cd example
```

- Install dependencies.

```sh
npm install
```

- Run the tests

Run the following command to execute tests on an Android emulator:

```sh
npx appwright test --project android
```

To run the tests on iOS simulator:

- Unzip the `wikipedia.zip` file

```sh
npm run extract:app
```
- Run the following command:

```sh
npx appwright test --project ios
```

## GPT Driver Integration

Appwright supports [GPT Driver](https://docs.mobileboost.io/gpt-driver-sdk) for AI-powered test automation. This enables natural language commands and AI assertions.

### Setup

Set the `GPT_DRIVER_API_KEY` environment variable:

```sh
export GPT_DRIVER_API_KEY=your-api-key
```

### Usage

```ts
import { test } from "@samsara-dev/appwright";

test("User can add item to cart", async ({ device }) => {
  // Natural language commands
  await device.gptDriver.aiExecute("tap on the login button");
  await device.gptDriver.aiExecute("enter 'admin' in the username field");

  // AI-powered assertions
  await device.gptDriver.assert("welcome message is visible");
  await device.gptDriver.assert("cart shows 1 item");
});
```

### Data Privacy Notice

GPT Driver sends screenshots to Mobileboost's external API for AI processing. Do not use GPT Driver in tests that handle sensitive data displayed on screen.

Tests skip automatically when `GPT_DRIVER_API_KEY` is not set.

## Docs

- [Basics](docs/basics.md)
- [Configuration](docs/config.md)
- [Locators](docs/locators.md)
- [Assertions](docs/assertions.md)
- [API reference](docs/api-reference.md)