Skip to main content

Installation

Taqwright puts Playwright's test runner on top of Appium 3, so you write mobile E2E tests the same way you'd write a Playwright web test, but you drive a real phone instead of a browser. This page takes you from nothing installed to a configured project ready to run its first test.

Introduction​

Taqwright sits on top of Playwright's test runner and Appium 3. From Playwright you get parallelism, retries, projects, sharding, fixtures, the HTML reporter, and the test / expect primitives. From Appium you get UiAutomator2 (Android) and XCUITest (iOS) underneath, with a flat mobile API and a chainable Locator on top.

You write tests the same way you'd write a Playwright web test, same file shape, same hooks, same runner flags, but you drive a phone instead of a browser. Once setup is done, head to Writing tests for your first test.

Installing taqwright​

Get started by installing taqwright. The command below initializes a new project (or use npm i -D taqwright to add taqwright to an existing one):

npm init taqwright@latest

When prompted, choose / confirm:

  • Project location: directory to scaffold into (or pass it as an argument: npm init taqwright@latest my-app)
  • Test folder name (default: tests)
  • Platform: android, ios, or both (default: android)
  • Run npm install now (default: yes)
  • Auto-install the Android toolchain: JDK + Android SDK + Appium, ~700 MB (default: no, Android projects)
  • Download the demo app so the example test runs out of the box (default: yes, Android projects)

You can re-run the command later, it asks before writing into a non-empty directory, so it won't overwrite existing work. npm init taqwright@latest is equivalent to npm create taqwright@latest (and, once taqwright is installed, npx taqwright init).

What's installed​

Taqwright scaffolds the project below. If you accept the toolchain prompt (or run npx taqwright install), it also vendors the Android toolchain, a JDK, the Android SDK + adb, Appium 3, and the uiautomator2 driver, into a taqwright-managed cache dir (the mobile analogue of Playwright's browser binaries), not into node_modules.

taqwright.config.ts          # test + device/Appium configuration
package.json
package-lock.json            # after npm install
tsconfig.json
.gitignore
tests/
  example.spec.ts            # runnable demo tests (login flows)
app/
  DemoApp-v1.0.0.apk         # bundled demo app (Android, when accepted)

taqwright.config.ts centralizes configuration: platform, device + Appium, resetBetweenTests, reporters (console list + HTML), timeouts, and projects, see Configuration. The managed toolchain lives under ~/Library/Caches/taqwright (overridable via TAQWRIGHT_HOME), is shared across projects, and is used automatically by test / devices / doctor, delete that dir to fully revert.

Running the example test​

Taqwright is serial by default (workers: 1), one Appium session against your configured emulator / simulator / device, not parallel browsers. With the generated config, appium.autoStart spawns Appium and autoStartDevice cold-boots the managed taqwright_api34 AVD, so you just run:

npx taqwright test

Output and aggregated results stream to the terminal (the list reporter) while the device window shows the run live:

Running 3 tests using 1 worker

  ✓  tests/example.spec.ts:9:1 › user can log in to the demo app (4.1s)
  ✓  tests/example.spec.ts:16:1 › login fails with invalid username & password (3.4s)
  ✓  tests/example.spec.ts:23:1 › login is blocked without username & password (2.9s)

  3 passed (12.3s)

To open the HTML report: npx taqwright show-report

Tips:

  • Watch it run: the emulator / simulator window is visible by default; mobile has no headless/headed toggle (the device UI is the run).
  • Run a single project: npx taqwright test --project=android, needed when the config has multiple projects (e.g. --platform both).
  • Run one file: npx taqwright test tests/example.spec.ts; filter by title with -g "log in".
  • Open the HTML report: npx taqwright show-report (the generated config writes playwright-report/).
  • Debug interactively: drop await mobile.pause() in a test, or record flows with npx taqwright codegen.

See Running & debugging tests for tracing, screen recording and reports, and Parallel runs for workers / device pools / sharding.

Updating taqwright​

Update the package, then re-provision the managed Android toolchain, a newer taqwright may pin newer JDK / SDK / Appium / driver versions:

npm install -D taqwright@latest
npx taqwright install            # idempotent; add --force to fully re-vendor

taqwright install skips anything already present and pulls only what changed; pass --force to rebuild the whole managed toolchain. Check your installed version with npx taqwright --version.

System requirements​

  • Node.js 24 or newer: the only hard requirement (taqwright doctor errors below this; every other check is a soft warn).
  • macOS 14 (Sonoma) or later: required for iOS (Xcode / XCUITest); also fine for Android.
  • Linux (Debian 12/13, Ubuntu 22.04/24.04) or Windows 10+/11/WSL: Android only (iOS can't run off macOS).
  • Appium 3.x + the platform toolchain: provisioned automatically by npx taqwright install for Android; iOS needs Xcode installed manually.
  • An emulator, simulator, or real device: npx taqwright install --with-avd can create an Android emulator for you.

Fast path: auto-install the Android toolchain​

Don't want to install the Android SDK, a JDK, and Appium by hand? One command vendors the entire Android stack, a Temurin JDK, the Android SDK + adb, Appium 3, and the uiautomator2 driver, into a taqwright-managed directory:

npx taqwright install

:::tip No sudo, no shell edits Everything downloads under a managed cache dir (override with TAQWRIGHT_HOME), nothing is installed system-wide and your shell rc is never touched. Taqwright automatically uses this toolchain when you run test, devices, codegen, or doctor, no export ANDROID_HOME=… required. :::

It runs four idempotent steps, then self-verifies with doctor:

1/4  JDK (Temurin 21)                                  ✓
2/4  Android SDK (cmdline-tools + platform-tools/adb)  ✓
3/4  Appium 3 + uiautomator2 driver                    ✓
4/4  AVD, skipped (pass --with-avd to also create an emulator)
FlagEffect
--forceReinstall even if already provisioned.
--with-avdAlso download a system image and create an emulator (taqwright_api34, ~1 GB).
--print-envAlso print export lines, if you want the managed toolchain on your own shell too.

:::note Android only install can't auto-install two things: Node.js 24+ (it's the runtime taqwright itself runs on) and the iOS / Xcode stack (Apple-gated). For iOS, or to install the Android pieces by hand, use the manual steps below. :::

Manual install​

Prefer manual control, or testing iOS? The setup is a stack: Node → Appium → driver → device. Each step has a verification command.

1. Node.js 24+​

Taqwright and Appium 3 both require Node.js 24 or newer. Use nvm (macOS / Linux) or fnm (cross-platform):

# macOS / Linux: nvm
nvm install 24
nvm use 24

# Windows / cross-platform: fnm
fnm install 24
fnm use 24

Verify with node -v (anything v24.0.0 or newer).

npm install -g appium@^3

Verify with appium --version (must start with 3). You can leave Appium not-yet-running, taqwright spawns it for you when use.appium.autoStart: true.

:::note Already on Appium 2.x? Taqwright will run on it, every mobile: command shape is identical between 2.x and 3.x, but taqwright doctor prints a best-effort warning and the 2.x path isn't in CI. Upgrade with npm i -g appium@^3 when ready. :::

3. Appium drivers​

appium driver install uiautomator2   # Android
appium driver install xcuitest       # iOS

Verify with appium driver list --installed.

4. Android toolchain (Android only)​

UiAutomator2 needs the Android SDK Platform Tools (for adb) and a JDK. Install Android Studio (its first-run setup installs the SDK + Platform Tools and creates an emulator), or just the command-line tools. Set ANDROID_HOME and add tools to PATH in your shell rc:

export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"

Any LTS Java (11, 17, or 21) works for UiAutomator2:

brew install --cask temurin@21
export JAVA_HOME=$(/usr/libexec/java_home -v 21)

Verify with adb --version and java -version.

5. iOS toolchain (iOS only: macOS required)​

XCUITest needs Xcode and its Command Line Tools:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
xcode-select --install

For iOS-simulator screen recording (video in a project's use), also install ffmpeg (brew install ffmpeg), XCUITest pipes simulator frames through it.

6. A device​

You need at least one of an Android emulator, an iOS simulator, or a real device on USB.

# Android emulator
emulator -avd Pixel_7_API_34 -no-snapshot &
adb devices          # emulator-5554   device

# iOS simulator
xcrun simctl boot "iPhone 16"
open -a Simulator

:::warning WDA won't start, connect ECONNREFUSED 127.0.0.1:8100? iOS sessions go through WebDriverAgent (WDA) on port 8100. The two common causes: (1) the iOS simulator platform for your Xcode isn't installed, run xcodebuild -downloadPlatform iOS, then make a sim on it; (2) the first WDA build is slow and times out, use iosParallelCaps() on the project or pre-build WDA once so it's cached. Add appium:showXcodeLog: true to surface the real xcodebuild error. :::

7. Install taqwright​

npm init taqwright my-mobile-tests   # scaffold a new project (recommended)
cd my-mobile-tests
npm install
#, or add to an existing project: npm install --save-dev taqwright

8. Final verification​

npx taqwright doctor
taqwright doctor (v0.0.1)
  [ok] Node.js >= 24 , v24.15.0
  [ok] adb (Android SDK) , on PATH
  [ok] ANDROID_HOME (Appium adb lookup) , ANDROID_HOME=~/Library/Android/sdk
  [ok] java (JDK for UiAutomator2) , on PATH
  [ok] Appium (test server) , on PATH (v3.x.x)
  [ok] Appium drivers , uiautomator2, xcuitest

:::tip A [warn] is a soft heads-up, never a hard failure The xcrun / Xcode / ffmpeg / iOS simulator lines are macOS-only. Only [error] (e.g. Node < 24) blocks you. :::

List what taqwright can see with npx taqwright devices. If doctor passes and devices lists something, you're ready to write your first test.

What's next​