Command line

Taqwright ships a single taqwright binary that runs your tests, scaffolds a project, records flows against a device, checks your environment, and serves reports. Invoke any command through your package runner:

npx taqwright <command> [options]

--help and --version are available on every command, so the fastest way to see the live option list for your installed version is:

npx taqwright --help
npx taqwright test --help
npx taqwright --version

A focused surface

The test command exposes the run-time flags below and nothing more. Knobs like trace, video, fullyParallel, and per-project timeouts live in taqwright.config.ts, not on the command line. Playwright-only test flags such as --headed, --debug, --repeat-each, --update-snapshots, and --max-failures are intentionally not surfaced; set the equivalent in config instead.

taqwright test

Run your tests. An optional positional filter narrows which spec files run; it accepts globs (config is auto-discovered as taqwright.config.{ts,mts,js,mjs} in the current directory unless you pass --config).

# Run every test in the configured testDir
npx taqwright test

# Filter test files by glob
npx taqwright test auth/**/*.spec.ts

# Run a single configured project
npx taqwright test --project android

# Run only tests tagged @smoke
npx taqwright test --grep @smoke

# Split the suite into 3 shards and run the first
npx taqwright test --shard 1/3

# List the tests that would run, without running them
npx taqwright test --list

Common options:

Option	Description
--project <name...>	Only run tests from the named project(s). Repeatable.
--grep <regex>	Only run tests matching this regex (matches titles and @tags).
--workers <n>	Number of parallel workers. Defaults to the run's project workers.
--list	List all tests without running them.

All options:

Option	Description
-c, --config <file>	Configuration file. Default: taqwright.config.{ts,mts,js,mjs}.
--reporter <reporter>	Reporter to use (e.g. list, html, json, junit).
--grep <regex>	Only run tests matching this regex.
--grep-invert <regex>	Only run tests NOT matching this regex.
--project <name...>	Only run tests from the specified project(s). Repeatable.
--retries <n>	Maximum retry count for flaky tests.
--timeout <ms>	Test timeout in milliseconds.
--shard <x/n>	Shard to run, e.g. 1/3.
--workers <n>	Number of parallel workers. Default: the run's project workers.
--list	List all tests without running them.
--pass-with-no-tests	Exit with code 0 when no tests are found.

See Running and debugging for reporters and trace output, and Parallelism for --workers / --shard.

taqwright init

Scaffold a new taqwright project in [dir] (the current directory if omitted). Interactive by default; pass the options below to skip prompts.

# Interactive scaffold in a new folder
npx taqwright init my-app

# Non-interactive: Android project, install deps and the demo app
npx taqwright init my-app --platform android --install --demo-app

Option	Description
--test-dir <name>	Test folder name. Default: tests.
--platform <p>	android | ios | both. Default: android.
--install	Run npm install after scaffolding.
--no-install	Skip running npm install after scaffolding.
-y, --yes	Overwrite an existing non-empty directory without prompting.
--install-toolchain	Auto-install the Android toolchain after scaffolding (skips the prompt).
--no-install-toolchain	Skip the Android-toolchain prompt entirely.
--with-avd	Also create an Android emulator (system image + AVD) when installing the toolchain.
--no-with-avd	Skip the emulator prompt.
--demo-app	Download the demo APK so the example test runs out of the box.
--no-demo-app	Skip the demo-app prompt entirely.

taqwright inspect

Open the taqwright inspector, a web UI, against a device. Use it to explore the live UI tree and build locators.

npx taqwright inspect --project android

Option	Description
-c, --config <file>	Configuration file. Default: taqwright.config.{ts,mts,js,mjs}.
--project <name>	Project to inspect. Default: the first project in config.
--port <n>	Preferred local port for the inspector UI. Default: 4280.
--host <host>	Host to bind the inspector UI. Default: localhost.
--no-open	Do not automatically open the browser.
--record	Auto-start recording the moment Connect succeeds.

taqwright codegen

Open the inspector and auto-start recording on Connect (an alias of inspect --record). Each action you perform appends taqwright source to a generated spec. See Generating tests.

npx taqwright codegen --project android

Option	Description
-c, --config <file>	Configuration file. Default: taqwright.config.{ts,mts,js,mjs}.
--project <name>	Project to record against. Default: the first project in config.
--port <n>	Preferred local port for the inspector UI. Default: 4280.
--host <host>	Host to bind the inspector UI. Default: localhost.
--no-open	Do not automatically open the browser.

taqwright devices

List connected devices, simulators, and emulators (Android via adb / emulator, iOS simulators via xcrun simctl on macOS). Takes no options.

npx taqwright devices

taqwright doctor

Check your environment for mobile-development readiness. Exits non-zero if any check fails.

npx taqwright doctor
npx taqwright doctor --json

Option	Description
--json	Output as JSON.

Honours NO_COLOR to suppress ANSI colours in the plain-text output.

taqwright install

Auto-install the Android toolchain (JDK + SDK + Appium) into a managed location, no shell configuration required. Subsequent taqwright commands inherit the managed environment.

npx taqwright install
npx taqwright install --with-avd --print-env

Option	Description
--force	Reinstall even if already provisioned.
--with-avd	Also create a system image + Android emulator (~1 GB).
--print-env	Also print export lines for using the toolchain from your shell.

taqwright merge-reports

Merge blob reports from sharded or parallel runs into a single unified report.

npx taqwright merge-reports ./reports/blob --reporter html

Option	Description
--reporter <reporter>	Reporter to use (e.g. html, list, json, junit).
-c, --config <file>	Configuration file.

taqwright show-report

Serve a previously generated HTML report. The report directory defaults to playwright-report.

npx taqwright show-report
npx taqwright show-report ./reports/html --port 9323

Option	Description
--host <host>	Host to serve the report on. Default: localhost.
--port <port>	Port to serve the report on. Default: 9323.

Environment variables

Variable	Effect
PWDEBUG	Set to 0 to make mobile.pause() a no-op, so a stray pause() cannot hang a CI run.
CI	Conventionally read in your config (e.g. forbidOnly: !!process.env.CI) to tighten behaviour on CI.
NO_COLOR	Disables ANSI colours in taqwright doctor output.
FORCE_COLOR	Forces coloured output; taqwright sets it for a TTY so colours survive the subprocess.
JAVA_HOME	JDK location. Checked by doctor and used by the toolchain.
ANDROID_HOME / ANDROID_SDK_ROOT	Android SDK location. Used by doctor, devices, and Appium.
BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY	Credentials for the BrowserStack provider.
LAMBDATEST_USERNAME / LAMBDATEST_ACCESS_KEY	Credentials for the LambdaTest provider.