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/taqwright@beta to add taqwright to an existing one):

npm init taqwright

Two ways to set up

The same npm init taqwright command works whether or not you already have mobile tooling, init probes your machine and adapts. Pick the path that matches you:

	Path A, you already have the tooling	Path B, fresh install
You have	Appium 3, a JDK, and an Android emulator (AVD) already installed	A clean machine, no Android SDK / JDK / Appium
What init does	Detects them, prints ✓ rows, and skips the ~700 MB download. Wires your existing AVD into the config.	Offers to vendor a self-contained managed toolchain (JDK + SDK + Appium + driver), and optionally an emulator.
What you do	Accept the defaults, then npx taqwright test. Nothing to install.	Say yes to "Auto-install the Android toolchain", or run npx taqwright install --with-avd.
Download	~0 (reuses your tools)	~700 MB toolchain (+ ~1 GB emulator with --with-avd)
Details	Path A below	Path B below

Both paths land in the same place, a scaffolded project you run with npx taqwright test. The sections further down (Checking what you already have, Fast path, Manual install) expand on each.

Path A, you already have the tooling

If Appium 3, a JDK (17+), the uiautomator2 driver, and an AVD are already on your machine (system-wide, or from a previous taqwright install):

1. Run npm init taqwright and answer the project prompts (location, platform, etc.).

2. init probes your environment, prints the status table with ✓ rows, and shows → detected a working Android toolchain — skipping install., no toolchain prompt, no download.

3. It wires your existing AVD into taqwright.config.ts (auto for one AVD, pick for several).

4. Run it:

   npx taqwright test

Path B, fresh install

If you're starting clean and want taqwright to provide everything:

1. Run npm init taqwright and answer the project prompts.

2. When asked "Auto-install the Android toolchain now? (~700 MB)", say yes (or pass --install-toolchain). taqwright vendors a self-contained JDK + Android SDK + Appium 3 + uiautomator2 driver into a managed cache, your system tools are untouched.

3. Accept the emulator prompt (or pass --with-avd) to also create the managed taqwright_api34 AVD (~1 GB), or skip it and use a physical device.

4. Run it:

   npx taqwright test

   Already scaffolded and want to add the toolchain afterwards? Run npx taqwright install --with-avd (see Fast path).

Testing iOS?

iOS isn't auto-installable (Xcode is Apple-gated). On macOS, follow the Manual install steps for the Xcode / XCUITest stack regardless of which path above you take for Android.

Prompts and flags

When prompted, choose / confirm:

• Project location: directory to scaffold into (or pass it as an argument: npm init taqwright 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. This prompt only appears when init doesn't already detect a working Android toolchain, see Checking what you already have below.

The demo app (so the example test runs out of the box) is downloaded automatically for interactive Android runs, no prompt. Opt out with --no-demo-app; CI / scripted runs (no TTY, or all flags supplied) default to off, opt in with --demo-app.

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 is equivalent to npm create taqwright (and, once taqwright is installed, npx taqwright init).

Input validations

A few names and platforms are rejected up front so the scaffold can't produce a broken project:

• iOS needs macOS. --platform ios / both off macOS fails with: iOS testing requires macOS (Xcode + simulators). On Windows/Linux, use --platform android.
• Reserved folder names. The project folder and test folder can't be app, node_modules, playwright-report, dist, or a Windows device name (con, nul, com1…).
• Test-folder name. Letters, digits, dot, dash or underscore only, no spaces/special chars and no leading dot or dash.
• npm install failure. @taqwright/taqwright is published publicly on npm. If install fails, check your network/registry access and that you're on Node 24 or newer, then re-run with npm install --verbose for details.

Checking what you already have

On an interactive run that includes Android, init probes your environment before prompting and prints a compact status of the Android toolchain, so you see exactly what you already have and aren't asked to re-download tools you've got:

Android toolchain:
  ✓ JDK (java v21)
  ✓ Android SDK (adb)
  ✓ Appium 3.x (v3.4.0)
  ✓ uiautomator2 driver
  ✓ Android emulator (AVD): Pixel_7_API_34

Each row is one probe:

Marker	Meaning
✓	ready
⚠	present but not ideal, e.g. ⚠ Appium 2.x … — best-effort, not the supported version, or a JDK older than 17
✗	missing, e.g. ✗ Android SDK (adb) or ✗ Android emulator (AVD) — none

What each check looks at: JDK via java -version (needs 17+), Android SDK via adb on PATH, Appium via appium --version (3.x is the supported version) plus appium driver list --installed for uiautomator2, and AVDs scanned from ~/.android/avd.

When all four core pieces are present (JDK ok and adb and Appium 3.x and the uiautomator2 driver), init treats the toolchain as ready, prints → detected a working Android toolchain — skipping install., and skips the install prompt entirely. The closing Next steps also adapt to what was found, e.g. it won't suggest --with-avd if you already have an emulator, and won't tell you to set device.name when your AVD was wired in for you.

No re-download when you're already set up

A detected working toolchain means init won't fetch the ~700 MB managed bundle. If any row shows ✗, the fix is either npx taqwright install (auto, Android, see Fast path) or the Manual install steps (iOS / by hand).

Reusing your existing emulator

If the probe finds AVDs and you're not creating the managed taqwright_api34 emulator, init points the generated taqwright.config.ts at one of yours instead of leaving a placeholder:

• One AVD detected → it's wired in as device.name, with autoStartDevice: true uncommented, so npx taqwright test cold-boots it for you.
• Several AVDs → init lists them numbered and asks which the config should target (with a "leave placeholder" option to edit later).
• You already have an AVD → instead of assuming, init asks whether to also create the managed taqwright_api34 (default no), so it never pushes a redundant ~1 GB image on you.

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 Parallelism 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/taqwright@beta
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

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)

Flag	Effect
--force	Reinstall even if already provisioned.
--with-avd	Also download a system image and create an emulator (taqwright_api34, ~1 GB).
--print-env	Also print export lines, if you want the managed toolchain on your own shell too.

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

2. Appium 3.x (recommended)

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.

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

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/taqwright@beta

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

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

• Writing tests, your first test, actions, locators, assertions, isolation, hooks.
• Generating tests, record a spec with the browser inspector + codegen.
• Running & debugging tests, tracing, screen recording, artifacts, reports.
• Parallelism, device pools, workers, BrowserStack / LambdaTest.