Skip to main content
✨ Beta

Welcome to the Taqwright beta

Taqwright is now in public beta. Install it from npm, scaffold a project, try the tools, and run mobile tests on your own machine. Get started by adding it to your project:

npm install --save-dev @taqwright/taqwright@beta

Prerequisites

  • Node.js 24 or newer and npm.
  • A device target: an Android emulator or an iOS simulator. Taqwright can auto-install the Android toolchain for you, but we recommend installing Appium and the Android SDK yourself for a faster, more reliable setup. See Recommended: set up the toolchain below. iOS needs macOS with Xcode.

System requirements

  • Node.js 24 or newer: the only hard requirement. taqwright doctor errors below this; every other check is a soft warning.
  • macOS 14 (Sonoma) or later: required for iOS (Xcode / XCUITest); also works for Android.
  • Linux (Debian 12/13, Ubuntu 22.04/24.04) or Windows 10+/11/WSL: Android only (iOS cannot run off macOS).

taqwright init can vendor a managed Android toolchain for you, which is the quickest way to a first run. For day-to-day testing we recommend installing Appium and the Android SDK system-wide instead: it is faster, easier to debug, and shared across every project. Here is the toolchain Appium needs.

Android (installs Homebrew first if you need it):

# Node 24 (skip if you already have it)
brew install node@24
brew link --overwrite node@24

# JDK 17 (Temurin) + JAVA_HOME
brew install --cask temurin@17
echo 'export JAVA_HOME="$(/usr/libexec/java_home -v 17)"' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc

# Android Studio provides the SDK + emulator.
# Open it once and finish the setup wizard, then:
brew install --cask android-studio
echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
echo 'export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Appium 3 + the Android driver
npm install -g appium@latest
appium driver install uiautomator2
appium driver doctor uiautomator2   # fix anything it flags

# Create an Android emulator (AVD). Apple Silicon: arm64-v8a · Intel Mac: x86_64
sdkmanager --licenses
sdkmanager "platform-tools" "emulator" "platforms;android-34" "system-images;android-34;google_apis;arm64-v8a"
avdmanager create avd -n Pixel_7_API_34 -k "system-images;android-34;google_apis;arm64-v8a" -d pixel_7
emulator -list-avds                 # confirm it was created
# emulator -avd Pixel_7_API_34      # boot it (taqwright can also auto-boot it)

iOS (optional, macOS only):

# Install Xcode from the Mac App Store first, then:
sudo xcodebuild -license accept
xcode-select --install              # if not already installed

# Appium iOS driver
appium driver install xcuitest
appium driver doctor xcuitest       # may ask for: brew install carthage
xcrun simctl list devices           # list available simulators

After changing JAVA_HOME, ANDROID_HOME, or PATH, open a new terminal so the changes apply. Prefer a UI? Android Studio's Device Manager creates emulators too. Once your emulator exists, start it and confirm it is connected with adb devices (it should show device, not offline).

Scaffold a project

Add Taqwright from npm, then scaffold. init creates a project folder (default ./taqwright-tests), writes a taqwright.config.ts, a sample test, wires the demo app, and runs npm install. It can also auto-install the Android toolchain and an emulator for you.

# add Taqwright from npm, then scaffold a project
npm install --save-dev @taqwright/taqwright@beta
npx taqwright init

Already have a project? Run the same two commands inside it. init probes your setup and only adds what is missing.

init walks you through a few prompts, then scaffolds and installs. Here is what to expect. The Toolchain already set up path is what you get after the recommended setup above; Fresh machine is the zero-setup auto-install path.

$ npx taqwright init

taqwright init — scaffold a new project

Press Enter to accept the default shown in (parentheses).

? Project location (./taqwright-tests):
? Test folder name (tests):
? Platform [android/ios/both]: android

Android toolchain:
  ✓ JDK (java v17)
  ✓ Android SDK (adb)
  ✓ Appium 3.x (v3.4.0)
  ✓ uiautomator2 driver
  ✓ Android emulator (AVD): Pixel_7_API_34, Pixel_Tablet_API_35
  → detected a working Android toolchain — skipping install.
  Detected AVDs:
    1) Pixel_7_API_34
    2) Pixel_Tablet_API_35
    3) leave placeholder (edit the config later)
? Which AVD should the config target? (1-3) (1): 1

Downloading the demo app (DemoApp-v1.0.0.apk)… done.

Created:
  taqwright-tests/taqwright.config.ts
  taqwright-tests/package.json
  taqwright-tests/tsconfig.json
  taqwright-tests/.gitignore
  taqwright-tests/tests/example.spec.ts
  taqwright-tests/app/DemoApp-v1.0.0.apk

Running npm install …

Next steps:
  cd taqwright-tests
  npx taqwright test

Commands:
  npx taqwright doctor
  npx taqwright codegen
  npx taqwright test
  npx taqwright show-report

The config targets the "Pixel_7_API_34" AVD — taqwright boots it automatically
when you run the test above (or uses it if already running).

Check your environment

Verify everything is wired up, and see what devices are available:

npx taqwright doctor        # verify your environment
npx taqwright devices       # list emulators / simulators / devices

A healthy setup looks like this. Rows turn [--] (warning) or [!!] (error) when something needs attention:

$ npx taqwright doctor
taqwright doctor (v0.1.0-beta.0)
  [ok] Node.js 24+  — v24.15.0
  [ok] adb (Android SDK)  — on PATH
  [ok] ANDROID_HOME (Appium adb lookup)  — ANDROID_HOME=/Users/you/Library/Android/sdk
  [ok] xcrun (Xcode CLT)  — on PATH
  [ok] Xcode (full, for XCUITest)  — Xcode 26.5 (/Applications/Xcode.app/Contents/Developer)
  [ok] ffmpeg (iOS-sim video)  — on PATH
  [ok] networksetup (iOS-sim network capture)  — on PATH
  [ok] iOS simulator (WDA target)  — 21 available (latest iOS 26.5)
  [ok] node-forge (network capture)  — loaded
  [ok] java (JDK for UiAutomator2)  — on PATH (v25.0.2)
  [ok] JAVA_HOME (UiAutomator2 JDK)  — JAVA_HOME=/opt/homebrew/Cellar/openjdk/25.0.2/libexec/openjdk.jdk/Contents/Home
  [ok] Appium (test server)  — on PATH (v3.3.1)
  [ok] Appium drivers  — uiautomator2, xcuitest

On Android you can provision the full toolchain plus an emulator with npx taqwright install --with-avd.

Explore the tools

  • npx taqwright codegen opens an inspector and records a runnable test as you tap the app. See codegen →
  • npx taqwright doctor and npx taqwright devices keep your setup healthy.

See codegen in action:

Run the tests

Run the sample suite on your device, then open the report:

npx taqwright test          # run the sample tests
npx taqwright show-report   # open the HTML report

Add --project android or --project ios to target one platform. See Running & debugging.

Watch the whole flow, from install to the HTML report:

Learn more

Installation →Writing tests →Codegen →Command line →Configuration →Trace viewer →Sample repo ↗

Start from the sample project

Prefer a ready-made project? Clone the demo, install, and run it to see a passing suite right away.

The sample project (taqwright-demo) is a suite for a Flutter DemoApp. Its tests drive real mobile gestures and assert the UI responds, a quick tour of what taqwright can automate:

  • Swipe: swipes left and right through a card carousel and checks the expected card is shown.
  • Drag and drop: drags an element onto a target and verifies it lands.
  • Pinch to zoom and double tap to zoom: multi-touch and double-tap zoom gestures.
  • Long press: long-presses an element and checks the Copy action appears.

The same suite runs across several configured projects: a single emulator, a 2-emulator pool, auto-detected host AVDs, a local iOS simulator, and real devices on BrowserStack.

git clone https://github.com/Taqwright/taqwright-demo.git
cd taqwright-demo
npm install
npm run test:auto2   # auto-detect emulators, run 2-wide

npm install pulls Taqwright straight from npm, so there is nothing else to set up. test:auto2 runs two workers, so make sure two emulators are available on your machine (check with adb devices). Only have one? Use npm run test:auto1 instead. Browse the repo: https://github.com/Taqwright/taqwright-demo.

Watch the suite run, from clone to the HTML report: