@taqwright/taqwright 0.0.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +108 -0
  3. package/dist/auto-appium.d.ts +12 -0
  4. package/dist/auto-appium.js +77 -0
  5. package/dist/bin/branding.d.ts +6 -0
  6. package/dist/bin/branding.js +22 -0
  7. package/dist/bin/index.d.ts +2 -0
  8. package/dist/bin/index.js +321 -0
  9. package/dist/bin/init.d.ts +26 -0
  10. package/dist/bin/init.js +902 -0
  11. package/dist/bin/inspect.d.ts +9 -0
  12. package/dist/bin/inspect.js +91 -0
  13. package/dist/bin/report-branding.d.ts +2 -0
  14. package/dist/bin/report-branding.js +42 -0
  15. package/dist/branding-assets.d.ts +1 -0
  16. package/dist/branding-assets.js +1 -0
  17. package/dist/capabilities-helpers.d.ts +7 -0
  18. package/dist/capabilities-helpers.js +14 -0
  19. package/dist/capabilities.d.ts +6 -0
  20. package/dist/capabilities.js +86 -0
  21. package/dist/config.d.ts +17 -0
  22. package/dist/config.js +235 -0
  23. package/dist/discovery-setup.d.ts +1 -0
  24. package/dist/discovery-setup.js +61 -0
  25. package/dist/discovery.d.ts +17 -0
  26. package/dist/discovery.js +55 -0
  27. package/dist/docs/configuration.html +376 -0
  28. package/dist/docs/custom-reporters.html +265 -0
  29. package/dist/docs/docker.html +339 -0
  30. package/dist/docs/docs.js +173 -0
  31. package/dist/docs/generating-tests.html +161 -0
  32. package/dist/docs/images/taqwright-html-report.png +0 -0
  33. package/dist/docs/index.html +13 -0
  34. package/dist/docs/installation.html +686 -0
  35. package/dist/docs/parallel.html +271 -0
  36. package/dist/docs/running-tests.html +385 -0
  37. package/dist/docs/styles.css +460 -0
  38. package/dist/docs/writing-tests.html +565 -0
  39. package/dist/doctor.d.ts +33 -0
  40. package/dist/doctor.js +508 -0
  41. package/dist/expect.d.ts +38 -0
  42. package/dist/expect.js +96 -0
  43. package/dist/fixture/artifact-mode.d.ts +2 -0
  44. package/dist/fixture/artifact-mode.js +7 -0
  45. package/dist/fixture/index.d.ts +15 -0
  46. package/dist/fixture/index.js +324 -0
  47. package/dist/images/taqwright-html-report.png +0 -0
  48. package/dist/images/taqwright_favicon.png +0 -0
  49. package/dist/images/taqwright_logo.png +0 -0
  50. package/dist/index.d.ts +9 -0
  51. package/dist/index.js +7 -0
  52. package/dist/inspector/codegen-appium.d.ts +3 -0
  53. package/dist/inspector/codegen-appium.js +228 -0
  54. package/dist/inspector/devices.d.ts +41 -0
  55. package/dist/inspector/devices.js +422 -0
  56. package/dist/inspector/locator-suggester.d.ts +23 -0
  57. package/dist/inspector/locator-suggester.js +539 -0
  58. package/dist/inspector/recorder.d.ts +128 -0
  59. package/dist/inspector/recorder.js +162 -0
  60. package/dist/inspector/server.d.ts +39 -0
  61. package/dist/inspector/server.js +1210 -0
  62. package/dist/inspector/session.d.ts +84 -0
  63. package/dist/inspector/session.js +262 -0
  64. package/dist/inspector/ui.d.ts +1 -0
  65. package/dist/inspector/ui.js +5508 -0
  66. package/dist/keys.d.ts +3 -0
  67. package/dist/keys.js +28 -0
  68. package/dist/locator/index.d.ts +206 -0
  69. package/dist/locator/index.js +1506 -0
  70. package/dist/logger.d.ts +5 -0
  71. package/dist/logger.js +5 -0
  72. package/dist/mobile/index.d.ts +130 -0
  73. package/dist/mobile/index.js +762 -0
  74. package/dist/network/android.d.ts +5 -0
  75. package/dist/network/android.js +87 -0
  76. package/dist/network/ca.d.ts +10 -0
  77. package/dist/network/ca.js +136 -0
  78. package/dist/network/har.d.ts +90 -0
  79. package/dist/network/har.js +101 -0
  80. package/dist/network/host-proxy.d.ts +16 -0
  81. package/dist/network/host-proxy.js +134 -0
  82. package/dist/network/index.d.ts +26 -0
  83. package/dist/network/index.js +105 -0
  84. package/dist/network/ios-sim.d.ts +3 -0
  85. package/dist/network/ios-sim.js +29 -0
  86. package/dist/network/proxy.d.ts +13 -0
  87. package/dist/network/proxy.js +310 -0
  88. package/dist/providers/appium.d.ts +23 -0
  89. package/dist/providers/appium.js +288 -0
  90. package/dist/providers/browserstack/index.d.ts +5 -0
  91. package/dist/providers/browserstack/index.js +77 -0
  92. package/dist/providers/browserstack/utils.d.ts +1 -0
  93. package/dist/providers/browserstack/utils.js +6 -0
  94. package/dist/providers/cloud.d.ts +53 -0
  95. package/dist/providers/cloud.js +117 -0
  96. package/dist/providers/emulator/index.d.ts +8 -0
  97. package/dist/providers/emulator/index.js +47 -0
  98. package/dist/providers/index.d.ts +10 -0
  99. package/dist/providers/index.js +33 -0
  100. package/dist/providers/lambdatest/index.d.ts +28 -0
  101. package/dist/providers/lambdatest/index.js +99 -0
  102. package/dist/providers/lambdatest/utils.d.ts +1 -0
  103. package/dist/providers/lambdatest/utils.js +6 -0
  104. package/dist/providers/local/index.d.ts +9 -0
  105. package/dist/providers/local/index.js +53 -0
  106. package/dist/providers/local-session.d.ts +16 -0
  107. package/dist/providers/local-session.js +55 -0
  108. package/dist/setup/archive.d.ts +2 -0
  109. package/dist/setup/archive.js +43 -0
  110. package/dist/setup/avd.d.ts +12 -0
  111. package/dist/setup/avd.js +103 -0
  112. package/dist/setup/index.d.ts +6 -0
  113. package/dist/setup/index.js +55 -0
  114. package/dist/setup/install-android.d.ts +2 -0
  115. package/dist/setup/install-android.js +70 -0
  116. package/dist/setup/install-appium.d.ts +1 -0
  117. package/dist/setup/install-appium.js +64 -0
  118. package/dist/setup/install-jdk.d.ts +1 -0
  119. package/dist/setup/install-jdk.js +58 -0
  120. package/dist/setup/paths.d.ts +16 -0
  121. package/dist/setup/paths.js +88 -0
  122. package/dist/setup/spawn-tool.d.ts +3 -0
  123. package/dist/setup/spawn-tool.js +11 -0
  124. package/dist/tracer/index.d.ts +34 -0
  125. package/dist/tracer/index.js +687 -0
  126. package/dist/tracer/proxy.d.ts +3 -0
  127. package/dist/tracer/proxy.js +60 -0
  128. package/dist/types/index.d.ts +189 -0
  129. package/dist/types/index.js +6 -0
  130. package/dist/utils.d.ts +2 -0
  131. package/dist/utils.js +37 -0
  132. package/package.json +79 -0
package/dist/docs/installation.html ADDED
@@ -0,0 +1,686 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Installation · taqwright</title>
7
+ <meta name="description" content="Install taqwright — Node 24, Appium 3, drivers, the Android/iOS toolchain, a device, and your taqwright.config.ts. The end-to-end setup guide.">
8
+ <link rel="stylesheet" href="styles.css">
9
+ <script>try{var t=localStorage.getItem('tw-theme');if(t==='light'||(!t&&typeof matchMedia==='function'&&matchMedia('(prefers-color-scheme: light)').matches))document.documentElement.setAttribute('data-theme','light');}catch(e){}</script>
10
+ </head>
11
+ <body>
12
+
13
+ <header class="topbar">
14
+ <button class="menu-toggle" id="menu-toggle" aria-label="Toggle navigation">☰</button>
15
+ <a class="brand" href="installation.html"><span class="accent">taq</span>wright</a>
16
+ <nav class="primary">
17
+ <a href="installation.html" class="current">Docs</a>
18
+ <a href="generating-tests.html">Inspector</a>
19
+ <a href="writing-tests.html#actions">API</a>
20
+ </nav>
21
+ <span class="spacer"></span>
22
+ <div class="search" title="Search (placeholder)">
23
+ <span>Search docs…</span>
24
+ <span class="kbd">⌘K</span>
25
+ </div>
26
+ <button class="theme-toggle" id="theme-toggle" aria-label="Switch to light theme" title="Switch to light theme"></button>
27
+ <a class="gh-link" href="https://github.com/taqelah/taqwright" title="GitHub">
28
+ <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 .5a11.5 11.5 0 0 0-3.64 22.42c.58.1.79-.25.79-.55v-2.02c-3.2.7-3.88-1.36-3.88-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.05-.71.08-.7.08-.7 1.16.08 1.77 1.19 1.77 1.19 1.03 1.77 2.7 1.26 3.36.96.1-.75.4-1.26.73-1.55-2.55-.29-5.24-1.28-5.24-5.7 0-1.26.45-2.29 1.19-3.1-.12-.29-.52-1.47.11-3.06 0 0 .97-.31 3.18 1.18a11 11 0 0 1 5.79 0c2.21-1.49 3.18-1.18 3.18-1.18.63 1.59.23 2.77.11 3.06.74.81 1.18 1.84 1.18 3.1 0 4.43-2.7 5.4-5.27 5.69.41.36.78 1.06.78 2.14v3.17c0 .31.21.66.8.55A11.5 11.5 0 0 0 12 .5Z"/></svg>
29
+ </a>
30
+ </header>
31
+
32
+ <div class="shell">
33
+
34
+ <aside class="sidebar" id="sidebar">
35
+ <h3>Getting started</h3>
36
+ <ul>
37
+ <li><a href="installation.html" class="current">Installation</a></li>
38
+ <li class="sub"><a href="installation.html#introduction">Introduction</a></li>
39
+ <li class="sub"><a href="installation.html#installing">Installing taqwright</a></li>
40
+ <li class="sub"><a href="installation.html#whats-installed">What's installed</a></li>
41
+ <li class="sub"><a href="installation.html#running-example">Running the example test</a></li>
42
+ <li class="sub"><a href="installation.html#html-report">HTML test reports</a></li>
43
+ <li class="sub"><a href="installation.html#updating">Updating taqwright</a></li>
44
+ <li class="sub"><a href="installation.html#system-requirements">System requirements</a></li>
45
+ <li class="sub"><a href="installation.html#quick-start">Quick start</a></li>
46
+ <li class="sub"><a href="installation.html#setup">Fast path (auto-install)</a></li>
47
+ <li class="sub"><a href="installation.html#install">Manual install</a></li>
48
+ <li class="sub"><a href="installation.html#whats-next">What's next</a></li>
49
+ <li><a href="writing-tests.html">Writing tests</a></li>
50
+ <li><a href="generating-tests.html">Generating tests</a></li>
51
+ <li><a href="running-tests.html">Running &amp; debugging</a></li>
52
+ <li><a href="custom-reporters.html">Custom reporters</a></li>
53
+ <li><a href="parallel.html">Parallel runs</a></li>
54
+ <li><a href="docker.html">Run in Docker</a></li>
55
+ </ul>
56
+
57
+ <h3>Taqwright Test</h3>
58
+ <ul>
59
+ <li><a href="configuration.html">Configuration</a></li>
60
+ </ul>
61
+
62
+ <h3>Reference</h3>
63
+ <ul>
64
+ <li><a href="https://playwright.dev/docs/intro">Playwright runner ↗</a></li>
65
+ <li><a href="https://appium.io/docs/en/latest/">Appium 3 ↗</a></li>
66
+ </ul>
67
+ </aside>
68
+
69
+ <main>
70
+
71
+ <div class="breadcrumb">
72
+ <a href="installation.html">Docs</a> / Getting started / Installation
73
+ </div>
74
+
75
+ <h1>Installation</h1>
76
+ <p class="lede">
77
+ Taqwright puts <strong>Playwright's test runner on top of Appium 3</strong> 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.
78
+ </p>
79
+
80
+ <h2 id="introduction">Introduction</h2>
81
+ <p>
82
+ Taqwright sits on top of <a href="https://playwright.dev/">Playwright</a>'s test runner and <a href="https://appium.io/">Appium 3</a>. From Playwright you get parallelism, retries, projects, sharding, fixtures, the HTML reporter, and the <code>test</code> / <code>expect</code> primitives. From Appium you get UiAutomator2 (Android) and XCUITest (iOS) underneath, with a flat <code>mobile</code> API and a chainable <code>Locator</code> on top.
83
+ </p>
84
+ <p>
85
+ 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 below is done, head to <a href="writing-tests.html">Writing tests</a> for your first test.
86
+ </p>
87
+
88
+ <h2 id="installing">Installing taqwright</h2>
89
+ <p>
90
+ Get started by installing taqwright. The command below initializes a new project (or use <code>npm i -D taqwright</code> to add taqwright to an existing one):
91
+ </p>
92
+
93
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npm init taqwright@latest</code></pre></div>
94
+
95
+ <p>When prompted, choose / confirm:</p>
96
+ <ul>
97
+ <li><strong>Project location</strong> — directory to scaffold into (or pass it as an argument: <code>npm init taqwright@latest my-app</code>)</li>
98
+ <li><strong>Test folder name</strong> (default: <code>tests</code>)</li>
99
+ <li><strong>Platform</strong> — <code>android</code>, <code>ios</code>, or <code>both</code> (default: <code>android</code>)</li>
100
+ <li><strong>Run <code>npm install</code> now</strong> (default: yes)</li>
101
+ <li><strong>Auto-install the Android toolchain</strong> — JDK + Android SDK + Appium, ~700&nbsp;MB (default: no — Android projects)</li>
102
+ <li><strong>Download the demo app</strong> so the example test runs out of the box (default: yes — Android projects)</li>
103
+ </ul>
104
+ <p>
105
+ You can re-run the command later — it asks before writing into a non-empty directory, so it won't overwrite existing work. <code>npm init taqwright@latest</code> is equivalent to <code>npm create taqwright@latest</code> (and, once taqwright is installed, <code>npx taqwright init</code>).
106
+ </p>
107
+
108
+ <h2 id="whats-installed">What's installed</h2>
109
+ <p>
110
+ taqwright scaffolds the project below. If you accept the toolchain prompt (or run <a href="#setup"><code>npx taqwright install</code></a>), it also vendors the Android toolchain — a JDK, the Android SDK&nbsp;+&nbsp;<code>adb</code>, Appium&nbsp;3, and the <code>uiautomator2</code> driver — into a taqwright-managed cache dir (the mobile analogue of Playwright's browser binaries), <em>not</em> into <code>node_modules</code>.
111
+ </p>
112
+
113
+ <div class="codeblock"><pre class="code"><code>taqwright.config.ts # test + device/Appium configuration
114
+ package.json
115
+ package-lock.json # after npm install
116
+ tsconfig.json
117
+ .gitignore
118
+ tests/
119
+ example.spec.ts # runnable demo tests (login flows)
120
+ app/
121
+ DemoApp-v1.0.0.apk # bundled demo app (Android, when accepted)</code></pre></div>
122
+
123
+ <p>
124
+ <code>taqwright.config.ts</code> centralizes configuration: platform, device&nbsp;+ Appium, <code>resetBetweenTests</code>, reporters (console <code>list</code> + HTML), timeouts, and projects — see <a href="configuration.html#configure">Configuration</a>. Adding taqwright to an <strong>existing</strong> project instead (<code>npm i -D taqwright</code>) only adds the dependency to your current <code>package.json</code> — no scaffold.
125
+ </p>
126
+ <p>
127
+ <code>tests/</code> contains runnable example tests against the demo app (a minimal no-op stub if you declined the demo app). The managed toolchain lives under <code>~/Library/Caches/taqwright</code> (overridable via <code>TAQWRIGHT_HOME</code>), is shared across projects, and is used automatically by <code>test</code> / <code>devices</code> / <code>doctor</code> — delete that dir to fully revert.
128
+ </p>
129
+
130
+ <h2 id="running-example">Running the example test</h2>
131
+ <p>
132
+ taqwright is <strong>serial by default</strong> (<code>workers: 1</code>) — one Appium session against your configured emulator / simulator / device, not parallel browsers. With the generated config, <code>appium.autoStart</code> spawns Appium and <code>autoStartDevice</code> cold-boots the managed <code>taqwright_api34</code> AVD, so you just run:
133
+ </p>
134
+
135
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright test</code></pre></div>
136
+
137
+ <p>Output and aggregated results stream to the terminal (the <code>list</code> reporter) while the device window shows the run live:</p>
138
+
139
+ <div class="codeblock"><pre class="code"><code>Running 3 tests using 1 worker
140
+
141
+ ✓ tests/example.spec.ts:9:1 › user can log in to the demo app (4.1s)
142
+ ✓ tests/example.spec.ts:16:1 › login fails with invalid username &amp; password (3.4s)
143
+ ✓ tests/example.spec.ts:23:1 › login is blocked without username &amp; password (2.9s)
144
+
145
+ 3 passed (12.3s)
146
+
147
+ To open the HTML report: npx taqwright show-report</code></pre></div>
148
+
149
+ <p>Tips:</p>
150
+ <ul>
151
+ <li><strong>Watch it run</strong> — the emulator / simulator window is visible by default; mobile has no headless/headed toggle (the device UI <em>is</em> the run).</li>
152
+ <li><strong>Run a single project</strong>: <code>npx taqwright test --project=android</code> — needed when the config has multiple projects (e.g. <code>--platform both</code>); Android-only selectors won't run on iOS and vice-versa.</li>
153
+ <li><strong>Run one file</strong>: <code>npx taqwright test tests/example.spec.ts</code>; filter by title with <code>-g "log in"</code>.</li>
154
+ <li><strong>Open the HTML report</strong>: <code>npx taqwright show-report</code> (the generated config writes <code>playwright-report/</code>).</li>
155
+ <li><strong>Debug interactively</strong>: drop <code>await mobile.pause()</code> in a test, or record flows with <code>npx taqwright codegen</code> (the web inspector).</li>
156
+ </ul>
157
+ <p>See <a href="running-tests.html">Running &amp; debugging tests</a> for tracing, screen recording and reports, and <a href="parallel.html">Parallel runs</a> for workers / device pools / sharding.</p>
158
+
159
+ <h2 id="html-report">HTML test reports</h2>
160
+ <p>
161
+ After a run, the HTML report is a dashboard filterable by <strong>project</strong> (android / ios) and status (passed, failed, flaky, skipped). Click a test to inspect its error, steps and attachments — including taqwright's <code>taqwright-trace</code> (a self-contained per-action screenshot + page-source timeline) and <code>taqwright-video</code> (the device screen recording) when <a href="running-tests.html#tracing">trace</a> / <a href="running-tests.html#video">video</a> are enabled.
162
+ </p>
163
+ <p>
164
+ The generated config uses <code>['html', { open: 'never' }]</code>, so it <strong>never auto-opens</strong> — view it manually:
165
+ </p>
166
+
167
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright show-report</code></pre></div>
168
+
169
+ <p>
170
+ This serves <code>playwright-report/</code> at <code>http://localhost:9323</code> (override with <code>--host</code> / <code>--port</code>). Want it to pop open automatically when a test fails instead? Set the reporter to <code>['html', { open: 'on-failure' }]</code> in <a href="configuration.html#configure">taqwright.config.ts</a>.
171
+ </p>
172
+
173
+ <figure class="shot">
174
+ <img src="images/taqwright-html-report.png" alt="taqwright HTML test report — a dashboard listing the demo tests with pass/fail status, durations, and per-test steps and attachments" loading="lazy">
175
+ <figcaption>The taqwright HTML report (<code>npx taqwright show-report</code>).</figcaption>
176
+ </figure>
177
+
178
+ <h2 id="updating">Updating taqwright</h2>
179
+ <p>
180
+ Update the package, then re-provision the managed Android toolchain — a newer taqwright may pin newer JDK / SDK / Appium / driver versions (the analogue of Playwright re-downloading browser binaries):
181
+ </p>
182
+
183
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npm install -D taqwright@latest
184
+ npx taqwright install # idempotent; add --force to fully re-vendor</code></pre></div>
185
+
186
+ <p>
187
+ <code>taqwright install</code> skips anything already present and pulls only what changed; pass <code>--force</code> to rebuild the whole managed toolchain from scratch. Check your installed version:
188
+ </p>
189
+
190
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright --version</code></pre></div>
191
+
192
+ <h2 id="system-requirements">System requirements</h2>
193
+ <ul>
194
+ <li><strong>Node.js 24 or newer</strong> — the only hard requirement (<code>taqwright doctor</code> errors below this; every other check is a soft warn).</li>
195
+ <li><strong>macOS 14 (Sonoma) or later</strong> — required for <strong>iOS</strong> (Xcode / XCUITest); also fine for Android.</li>
196
+ <li><strong>Linux</strong> (Debian 12 / 13, Ubuntu 22.04 / 24.04) or <strong>Windows 10+ / 11 / WSL</strong> — <strong>Android only</strong> (iOS can't run off macOS). x86-64 recommended; Linux-arm64 works but Google's prebuilt <code>adb</code> is x86-64-only — use the system <code>adb</code> or the Docker image.</li>
197
+ <li><strong>Appium 3.x</strong> + the platform toolchain — provisioned automatically by <code>npx taqwright install</code> for Android (JDK + Android SDK + build-tools + Appium + <code>uiautomator2</code>); iOS needs Xcode installed manually.</li>
198
+ <li>An emulator, simulator, or real device — <code>npx taqwright install --with-avd</code> can create an Android emulator for you.</li>
199
+ </ul>
200
+
201
+ <h2 id="quick-start">Quick start</h2>
202
+ <p>A few commands to get oriented:</p>
203
+
204
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npm init taqwright # scaffold a project (interactive)
205
+ npx taqwright install # auto-install the Android toolchain (or say yes during init)
206
+ npx taqwright doctor # verify your env (adb, xcrun, java, appium)
207
+ npx taqwright devices # list local emulators / simulators + state
208
+ npx taqwright codegen # web inspector + record on connect
209
+ npx taqwright test # run your tests</code></pre></div>
210
+
211
+ <h2 id="setup">Fast path — auto-install the Android toolchain</h2>
212
+ <p>
213
+ Don't want to install the Android SDK, a JDK, and Appium by hand? One command vendors the <strong>entire Android stack</strong> — a Temurin JDK, the Android SDK&nbsp;+&nbsp;<code>adb</code>, Appium&nbsp;3, and the <code>uiautomator2</code> driver — into a taqwright-managed directory:
214
+ </p>
215
+
216
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright install</code></pre></div>
217
+
218
+ <p>
219
+ Run it any time, standalone — or let scaffolding do it: <a href="#install-taqwright"><code>npm init taqwright</code></a> (and <code>taqwright init</code>) <strong>offers this exact step</strong> for Android projects right after creating the files (default <em>no</em>; or pass <code>--install-toolchain</code> to skip the prompt). Same command underneath either way.
220
+ </p>
221
+
222
+ <div class="callout">
223
+ <strong>No sudo, no shell edits.</strong>
224
+ Everything downloads under a managed cache dir (override with <code>TAQWRIGHT_HOME</code>) — nothing is installed system-wide and your shell rc is never touched. taqwright automatically uses this toolchain when you run <code>test</code>, <code>devices</code>, <code>codegen</code>, or <code>doctor</code> — no <code>export ANDROID_HOME=…</code> required.
225
+ </div>
226
+
227
+ <p>It runs four idempotent steps (re-running skips anything already present), then self-verifies with <code>doctor</code>:</p>
228
+
229
+ <div class="codeblock"><pre class="code"><code>1/4 JDK (Temurin 21) ✓
230
+ 2/4 Android SDK (cmdline-tools + platform-tools/adb) ✓
231
+ 3/4 Appium 3 + uiautomator2 driver ✓
232
+ 4/4 AVD — skipped (pass --with-avd to also create an emulator)
233
+
234
+ Verifying with doctor:
235
+ [ok] adb (Android SDK) — on PATH
236
+ [ok] ANDROID_HOME (Appium adb lookup) — ANDROID_HOME=~/Library/Caches/taqwright/android-sdk
237
+ [ok] java (JDK for UiAutomator2) — on PATH
238
+ [ok] JAVA_HOME (UiAutomator2 JDK) — JAVA_HOME=~/Library/Caches/taqwright/jdk/…/Contents/Home
239
+ [ok] Appium (test server) — on PATH (v3.x.x)
240
+ [ok] Appium drivers — uiautomator2</code></pre></div>
241
+
242
+ <table class="api">
243
+ <thead><tr><th>Flag</th><th>Effect</th></tr></thead>
244
+ <tbody>
245
+ <tr><td><code>--force</code></td><td>Reinstall even if already provisioned (otherwise every step is skipped when present).</td></tr>
246
+ <tr><td><code>--with-avd</code></td><td>Also download a system image and create an emulator (<code>taqwright_api34</code>, ~1&nbsp;GB).</td></tr>
247
+ <tr><td><code>--print-env</code></td><td>Also print <code>export</code> lines, if you want the managed toolchain on your own shell too.</td></tr>
248
+ </tbody>
249
+ </table>
250
+
251
+ <div class="callout warn">
252
+ <strong>Android only.</strong>
253
+ <code>install</code> can't auto-install two things: <strong>Node.js&nbsp;24+</strong> (it's the runtime taqwright itself runs on — install it first, step&nbsp;1 below) and the <strong>iOS / Xcode</strong> stack (Apple-gated: App Store, license, ~10&nbsp;GB). For iOS — or if you'd rather install the Android pieces by hand — use the step-by-step below.
254
+ </div>
255
+
256
+ <h2 id="install">Installing taqwright (manual)</h2>
257
+ <p>
258
+ Prefer manual control, or testing iOS? Install the stack yourself. The <a href="#setup">fast path</a> above already does steps&nbsp;2–7 automatically for Android, so reach for this when you want manual control, an existing system toolchain, or iOS.
259
+ </p>
260
+ <p>
261
+ The setup is a stack: <strong>Node → Appium → driver → device</strong>. Each step has a verification command — run it and confirm the output before moving on. At the end, <code>npx taqwright doctor</code> runs every check at once.
262
+ </p>
263
+ <p>
264
+ At a minimum you need: <strong>Node.js 24+</strong>, <strong>Appium 3.x</strong>, and the driver + toolchain for the platform you're testing (Android, iOS, or both).
265
+ </p>
266
+
267
+ <h3 id="install-node">1. Node.js 24+</h3>
268
+ <p>
269
+ Taqwright and Appium 3 both require Node.js 24 or newer. Use <a href="https://github.com/nvm-sh/nvm">nvm</a> (macOS / Linux) or <a href="https://github.com/Schniz/fnm">fnm</a> (cross-platform) — they let you switch Node versions per project, and a <code>.nvmrc</code> in the project root picks up automatically.
270
+ </p>
271
+
272
+ <div class="codeblock">
273
+ <div class="filename">macOS / Linux — nvm</div>
274
+ <pre class="code"><button class="copy">Copy</button><code># Install nvm itself (one-time)
275
+ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
276
+ # Re-open your shell, then:
277
+ nvm install 24
278
+ nvm use 24</code></pre>
279
+ </div>
280
+
281
+ <div class="codeblock">
282
+ <div class="filename">macOS — Homebrew</div>
283
+ <pre class="code"><button class="copy">Copy</button><code>brew install node@24
284
+ brew link --overwrite node@24</code></pre>
285
+ </div>
286
+
287
+ <div class="codeblock">
288
+ <div class="filename">Windows / cross-platform — fnm</div>
289
+ <pre class="code"><button class="copy">Copy</button><code>winget install Schniz.fnm # or: choco install fnm
290
+ fnm install 24
291
+ fnm use 24</code></pre>
292
+ </div>
293
+
294
+ <p><strong>Verify:</strong></p>
295
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>node -v
296
+ # v24.x.x ← anything 24.0.0 or newer</code></pre></div>
297
+
298
+ <h3 id="install-appium">2. Appium 3.x (recommended)</h3>
299
+ <p>
300
+ Appium is the WebDriver server that talks to the device. The supported path is Appium 3.x:
301
+ </p>
302
+
303
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npm install -g appium@^3</code></pre></div>
304
+
305
+ <div class="callout">
306
+ <strong>Already on Appium 2.x?</strong>
307
+ Taqwright will run on it — every <code>mobile:</code> command shape is identical between 2.x and 3.x — but <code>taqwright doctor</code> will print a <code>best-effort</code> warning and the 2.x path isn't in CI. Upgrade with <code>npm i -g appium@^3</code> when you're ready for the officially supported path.
308
+ </div>
309
+
310
+ <p><strong>Verify:</strong></p>
311
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>appium --version
312
+ # 3.x.x ← must start with 3</code></pre></div>
313
+
314
+ <p>You can leave Appium not-yet-running. Taqwright will spawn it for you when <code>use.appium.autoStart: true</code> (see <a href="configuration.html#configure">Configuration</a>). Or run it yourself in a separate terminal:</p>
315
+
316
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>appium
317
+ # Welcome to Appium v3.x.x
318
+ # Appium REST http interface listener started on http://0.0.0.0:4723</code></pre></div>
319
+
320
+ <h3 id="install-drivers">3. Appium drivers</h3>
321
+ <p>
322
+ Appium's driver model is one driver per platform. Install the one(s) you need:
323
+ </p>
324
+
325
+ <div class="codeblock">
326
+ <div class="filename">Android — UiAutomator2</div>
327
+ <pre class="code"><button class="copy">Copy</button><code>appium driver install uiautomator2</code></pre>
328
+ </div>
329
+
330
+ <div class="codeblock">
331
+ <div class="filename">iOS — XCUITest</div>
332
+ <pre class="code"><button class="copy">Copy</button><code>appium driver install xcuitest</code></pre>
333
+ </div>
334
+
335
+ <p><strong>Verify:</strong></p>
336
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>appium driver list --installed
337
+ # - uiautomator2@3.x.x [installed (npm)]
338
+ # - xcuitest@8.x.x [installed (npm)]</code></pre></div>
339
+
340
+ <h3 id="install-android-toolchain">4. Android toolchain (Android testing only)</h3>
341
+ <p>
342
+ UiAutomator2 needs the <strong>Android SDK Platform Tools</strong> (for <code>adb</code>) and a <strong>JDK</strong>.
343
+ </p>
344
+
345
+ <h4>Android SDK Platform Tools (<code>adb</code>)</h4>
346
+ <p>
347
+ Easiest: install <a href="https://developer.android.com/studio">Android Studio</a> — its first-run setup installs the SDK + Platform Tools and creates an emulator. If you don't want the full IDE, install just the Command Line Tools and use <code>sdkmanager</code>.
348
+ </p>
349
+
350
+ <div class="codeblock">
351
+ <div class="filename">macOS — Homebrew</div>
352
+ <pre class="code"><button class="copy">Copy</button><code>brew install --cask android-platform-tools # adb + fastboot only
353
+ # or, full SDK with emulator:
354
+ brew install --cask android-commandlinetools</code></pre>
355
+ </div>
356
+
357
+ <p>Set <code>ANDROID_HOME</code> and add tools to <code>PATH</code> in your shell rc (<code>~/.zshrc</code> / <code>~/.bashrc</code>):</p>
358
+
359
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>export ANDROID_HOME="$HOME/Library/Android/sdk" # macOS Android Studio default
360
+ export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"</code></pre></div>
361
+
362
+ <p><strong>Verify:</strong></p>
363
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>adb --version
364
+ # Android Debug Bridge version 1.0.x
365
+
366
+ emulator -list-avds
367
+ # Pixel_7_API_34 ← your created emulators</code></pre></div>
368
+
369
+ <h4>JDK (for UiAutomator2)</h4>
370
+ <p>
371
+ Any LTS Java (11, 17, or 21) works. On macOS:
372
+ </p>
373
+
374
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>brew install --cask temurin@21
375
+ # Tell shells where to find it:
376
+ export JAVA_HOME=$(/usr/libexec/java_home -v 21)
377
+ export PATH="$JAVA_HOME/bin:$PATH"</code></pre></div>
378
+
379
+ <p>On Linux: <code>sudo apt install openjdk-21-jdk</code> (Debian/Ubuntu) or <code>sudo dnf install java-21-openjdk</code> (Fedora).</p>
380
+
381
+ <p><strong>Verify:</strong></p>
382
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>java -version
383
+ # openjdk version "21.x.x"
384
+
385
+ echo $JAVA_HOME
386
+ # /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home</code></pre></div>
387
+
388
+ <h3 id="install-ios-toolchain">5. iOS toolchain (iOS testing only — macOS required)</h3>
389
+ <p>
390
+ XCUITest needs Xcode and its Command Line Tools.
391
+ </p>
392
+
393
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code># 1. Install Xcode from the App Store (~10 GB download).
394
+ # 2. Then accept the license + install CLT:
395
+ sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
396
+ sudo xcodebuild -license accept
397
+ xcode-select --install</code></pre></div>
398
+
399
+ <p>For real-device testing (not just the simulator), also install <a href="https://libimobiledevice.org/">libimobiledevice</a> for some Appium device probes:</p>
400
+
401
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>brew install libimobiledevice ios-deploy</code></pre></div>
402
+
403
+ <p>If you'll use <a href="running-tests.html#video">screen recording</a> (<code>video</code> in a project's <code>use</code> block) on the iOS <strong>simulator</strong>, also install <code>ffmpeg</code> — XCUITest pipes simulator frames through it, and without it every iOS test fails at fixture setup (<code>'ffmpeg' binary is not found in PATH</code>):</p>
404
+
405
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>brew install ffmpeg
406
+ ffmpeg -version # verify it's on PATH</code></pre></div>
407
+
408
+ <p><strong>Verify:</strong></p>
409
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>xcrun --version
410
+ # xcrun version 70.x.x
411
+
412
+ xcodebuild -version
413
+ # Xcode 16.x
414
+
415
+ xcrun simctl list devices available | head -20
416
+ # == Devices ==
417
+ # -- iOS 18.0 --
418
+ # iPhone 16 (xxxx) (Shutdown)
419
+ # iPhone 16 Pro (xxxx) (Shutdown)
420
+ # ...</code></pre></div>
421
+
422
+ <h3 id="install-device">6. A device</h3>
423
+ <p>You need at least one of: an emulator (Android), a simulator (iOS), or a real device on USB.</p>
424
+
425
+ <h4>Android emulator</h4>
426
+ <p>Easiest path: create one in Android Studio's <strong>Device Manager → Create device</strong>. Or via CLI:</p>
427
+
428
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>sdkmanager "system-images;android-34;google_apis;arm64-v8a"
429
+ avdmanager create avd -n Pixel_7_API_34 -k "system-images;android-34;google_apis;arm64-v8a" -d pixel_7
430
+ emulator -avd Pixel_7_API_34 -no-snapshot &</code></pre></div>
431
+
432
+ <p><strong>Verify:</strong></p>
433
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>adb devices
434
+ # List of devices attached
435
+ # emulator-5554 device ← booted and ready</code></pre></div>
436
+
437
+ <h4>iOS simulator</h4>
438
+ <p>List, then boot:</p>
439
+
440
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>xcrun simctl list devices available
441
+ xcrun simctl boot "iPhone 16" # or whatever name appears in the list above
442
+ open -a Simulator</code></pre></div>
443
+
444
+ <p><strong>Verify:</strong></p>
445
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>xcrun simctl list devices booted
446
+ # iPhone 16 (xxxx) (Booted)</code></pre></div>
447
+
448
+ <div class="callout warn">
449
+ <strong>WebDriverAgent won't start — <code>connect ECONNREFUSED 127.0.0.1:8100</code>?</strong>
450
+ iOS sessions go through WebDriverAgent (WDA), which Appium builds with
451
+ <code>xcodebuild</code> and reaches on port <code>8100</code>. If it can't, you'll see
452
+ <code>Unable to start WebDriverAgent session … connect ECONNREFUSED 127.0.0.1:8100</code>.
453
+ Two causes, in order of likelihood:
454
+ <ul>
455
+ <li><strong>The iOS simulator platform for your Xcode isn't installed.</strong> e.g. Xcode 26.5 but only an iOS 26.4 runtime present — <code>xcodebuild</code> then can't resolve a build destination (<em>"iOS 26.5 is not installed. … Xcode &gt; Settings &gt; Components"</em>), so WDA never builds and nothing listens on <code>:8100</code>. This is an Xcode environment gap, not a taqwright/config issue. Install the matching platform, then make a sim on it:
456
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>xcodebuild -downloadPlatform iOS # or: Xcode → Settings → Components
457
+ xcrun simctl create 'iPhone 17 Pro' 'iPhone 17 Pro' \
458
+ com.apple.CoreSimulator.SimRuntime.iOS-26-5
459
+ xcrun simctl list devices available # copy the new UDID into device.udid / pool</code></pre></div>
460
+ </li>
461
+ <li><strong>The first WDA build is just slow and times out</strong> (Appium's default is ~60&nbsp;s; a cold WDA build is longer). Set <a href="configuration.html#ios-parallel-caps"><code>iosParallelCaps()</code></a> on the project (it bumps WDA launch/connection timeouts, enables <code>useNewWDA</code>, and retries), <em>or</em> pre-build WDA once so it's cached:
462
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>WDA=~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
463
+ xcodebuild build-for-testing -project "$WDA/WebDriverAgent.xcodeproj" \
464
+ -scheme WebDriverAgentRunner -destination 'id=&lt;sim-udid&gt;'</code></pre></div>
465
+ </li>
466
+ </ul>
467
+ Note: <code>iosParallelCaps()</code>'s WDA tuning applies to <code>taqwright test</code> (the runner). The <code>taqwright codegen</code> connect builds capabilities from its own form, so it uses Appium's default WDA timeout — once the platform is installed and WDA is prebuilt/cached, the inspector connects fine. Add <code>appium:showXcodeLog: true</code> to surface the real <code>xcodebuild</code> error if it still fails.
468
+ </div>
469
+
470
+ <h4>Real device (Android)</h4>
471
+ <ol>
472
+ <li>On the phone: <strong>Settings → About phone</strong>, tap "Build number" seven times to unlock Developer Options.</li>
473
+ <li><strong>Settings → Developer options → USB debugging</strong> → On.</li>
474
+ <li>Plug into USB. On first connect, accept the "Allow USB debugging" prompt.</li>
475
+ <li>Run <code>adb devices</code> — your device shows with state <code>device</code> (not <code>unauthorized</code>).</li>
476
+ </ol>
477
+
478
+ <h4>Real device (iOS)</h4>
479
+ <ol>
480
+ <li>Plug into the Mac. Xcode shows the device in <strong>Window → Devices and Simulators</strong>.</li>
481
+ <li>On the phone: trust the computer when prompted.</li>
482
+ <li>Provisioning: you'll need an Apple Developer account + a signed build of your app on the device.</li>
483
+ <li>Verify: <code>xcrun xctrace list devices</code> shows the device by name + UDID.</li>
484
+ </ol>
485
+
486
+ <h3 id="install-taqwright">7. Install taqwright</h3>
487
+ <p>Two options:</p>
488
+
489
+ <div class="codeblock">
490
+ <div class="filename">Scaffold a new project (recommended)</div>
491
+ <pre class="code"><button class="copy">Copy</button><code>npm init taqwright my-mobile-tests
492
+ cd my-mobile-tests
493
+ npm install</code></pre>
494
+ </div>
495
+
496
+ <p>
497
+ <code>npm init taqwright</code> (equivalently <code>npm create taqwright@latest</code>) is the standard bootstrap — it runs the <code>create-taqwright</code> initializer, which delegates to <code>taqwright init</code>. If <code>taqwright</code> is already installed/linked, the equivalent is <code>npx taqwright init my-mobile-tests</code>. Either way it walks you through picking a platform, points at your APK / IPA, and writes a ready-to-run <code>package.json</code>, <code>tsconfig.json</code>, <code>taqwright.config.ts</code>, and a sample spec. For an Android project it then <strong>offers to download the demo app</strong> (a small reference APK, default <em>yes</em>) — wiring <code>buildPath</code>/<code>appBundleId</code> + a real login spec so <code>npx taqwright test</code> works out of the box — and to <strong>auto-install the toolchain</strong> (the <a href="#setup">fast path</a> above, default <em>no</em>). Both are skippable via <code>--demo-app</code>/<code>--no-demo-app</code> and <code>--install-toolchain</code>/<code>--no-install-toolchain</code>. All flags forward, e.g. <code>npm init taqwright my-app -- --platform ios -y</code>.
498
+ </p>
499
+
500
+ <p>Example run — <code>npm init taqwright taq-demo</code>, choosing <code>android</code> and accepting the prompts:</p>
501
+
502
+ <div class="codeblock"><pre class="code"><code>taqwright init — scaffold a new project
503
+
504
+ ? Test folder name (tests):
505
+ ? Platform [android/ios/both]: android
506
+ ? Run npm install now? (Y/n): Y
507
+ ? Auto-install the Android toolchain now? (~700 MB: JDK + Android SDK + Appium) (y/N): y
508
+ ? Download the demo app so the example test runs out of the box? (~few MB) (Y/n): Y
509
+
510
+ Downloading the demo app (DemoApp-v1.0.0.apk)… done.
511
+
512
+ Created:
513
+ taq-demo/package.json
514
+ taq-demo/tsconfig.json
515
+ taq-demo/taqwright.config.ts
516
+ taq-demo/tests/example.spec.ts
517
+ taq-demo/.gitignore
518
+ taq-demo/app/DemoApp-v1.0.0.apk
519
+
520
+ Running npm install …
521
+ added 179 packages, audited 179 packages — found 0 vulnerabilities
522
+
523
+ Installing the Android toolchain — this can take a few minutes…
524
+
525
+ taqwright install — vendoring the Android toolchain into:
526
+ ~/Library/Caches/taqwright
527
+ … (the 4 install steps + doctor verification — identical to the Fast path output above) …
528
+
529
+ Next steps:
530
+ cd taq-demo
531
+ npx taqwright doctor # check your environment
532
+ npx taqwright devices # list connected devices
533
+ npx taqwright test # runs the demo login test (Appium auto-starts)</code></pre></div>
534
+
535
+ <p>
536
+ With the demo app accepted, the generated <code>taqwright.config.ts</code> has <code>resetBetweenTests: true</code> + <code>buildPath: './app/DemoApp-v1.0.0.apk'</code> + <code>appBundleId: 'com.taqelah.demo_app'</code> active, and <code>tests/example.spec.ts</code> is a real login test — so <code>npx taqwright test</code> passes once an emulator is up. Decline it and those config lines stay commented and the example is a no-op stub instead.
537
+ </p>
538
+
539
+ <div class="callout">
540
+ <strong>That toolchain block is the prompt in action.</strong> This Android-capable project answered <em>yes</em> to "Auto-install the Android toolchain", so <code>init</code> chained <a href="#setup"><code>taqwright install</code></a> automatically — the project is runnable immediately, no separate step. Answer <em>no</em> (the default) and that same command instead appears under <strong>Next steps</strong> as <code>npx taqwright install</code>.
541
+ </div>
542
+
543
+ <div class="codeblock">
544
+ <div class="filename">Add to an existing project</div>
545
+ <pre class="code"><button class="copy">Copy</button><code>npm install --save-dev taqwright</code></pre>
546
+ </div>
547
+
548
+ <h3 id="install-verify">8. Final verification</h3>
549
+ <p>Run the built-in doctor — it re-checks everything above in one go:</p>
550
+
551
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright doctor</code></pre></div>
552
+
553
+ <p>Expected output:</p>
554
+
555
+ <div class="codeblock"><pre class="code"><code>taqwright doctor (v0.0.1)
556
+ [ok] Node.js >= 24 — v24.15.0
557
+ [ok] adb (Android SDK) — on PATH
558
+ [ok] ANDROID_HOME (Appium adb lookup) — ANDROID_HOME=~/Library/Android/sdk
559
+ [ok] xcrun (Xcode CLT) — on PATH
560
+ [ok] Xcode (full, for XCUITest) — Xcode 16.2 (/Applications/Xcode.app/Contents/Developer)
561
+ [ok] ffmpeg (iOS-sim video) — on PATH
562
+ [ok] iOS simulator (WDA target) — 8 available (latest iOS 18.2)
563
+ [ok] java (JDK for UiAutomator2) — on PATH
564
+ [ok] JAVA_HOME (UiAutomator2 JDK) — JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
565
+ [ok] Appium (test server) — on PATH (v3.x.x)
566
+ [ok] Appium drivers — uiautomator2, xcuitest</code></pre></div>
567
+
568
+ <div class="callout">
569
+ <strong>What you'll actually see varies by platform — that's expected.</strong>
570
+ The <code>xcrun</code> / <code>Xcode</code> / <code>ffmpeg</code> / <code>iOS simulator</code> lines are <strong>macOS-only</strong> (skipped entirely on Linux/Windows). A <code>[warn]</code> is a <em>soft</em> heads-up, never a hard failure — e.g. <code>ffmpeg</code> and <code>iOS simulator</code> only matter if you record iOS-simulator video, and a single missing Appium driver is fine if you don't test that platform. Only <code>[error]</code> (e.g. Node &lt; 24) blocks you.
571
+ </div>
572
+
573
+ <p>List what taqwright can see:</p>
574
+
575
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright devices</code></pre></div>
576
+
577
+ <p>Example output:</p>
578
+
579
+ <div class="codeblock"><pre class="code"><code>Android (adb + emulator):
580
+ Pixel 7 API 34 emulator-5554 (booted, Android 14)
581
+ Pixel 6 API 33 avd:Pixel_6_API_33 (shutdown)
582
+
583
+ iOS Simulators (xcrun simctl):
584
+ iPhone 16 1A2B3C4D-5E6F-7A8B-9C0D-1E2F3A4B5C6D (booted, iOS 18.2)
585
+ iPhone 16 Pro 9F8E7D6C-5B4A-3210-FEDC-BA9876543210 (shutdown, iOS 18.2)</code></pre></div>
586
+
587
+ <p>
588
+ Every created emulator / simulator is listed with its <strong>state</strong> — <code>(booted, …)</code> if it's running, <code>(shutdown)</code> if it exists but isn't started. A shutdown Android AVD shows an <code>avd:&lt;name&gt;</code> id (use it to boot the emulator); a running one shows its live <code>emulator-5554</code> serial. Connected physical devices appear here too. If <code>doctor</code> all passes and <code>devices</code> lists something, you're ready to <a href="writing-tests.html#first-test">write your first test</a> — boot a shutdown device first (e.g. <code>emulator -avd Pixel_7_API_34</code> or <code>xcrun simctl boot "iPhone 16"</code>).
589
+ </p>
590
+
591
+ <div class="callout">
592
+ <strong>Stuck?</strong>
593
+ Most setup failures fall into three buckets:
594
+ <ol>
595
+ <li><strong><code>ANDROID_HOME</code> not set</strong> — the shell can find <code>adb</code> but <code>appium</code> can't find the rest of the SDK. Add the <code>export</code>s from step 4 to your shell rc.</li>
596
+ <li><strong>Wrong Node version</strong> — <code>node -v</code> shows v22 or older. Re-run <code>nvm use 24</code> (or check your <code>fnm</code> setup) — restart the shell if needed.</li>
597
+ <li><strong>Appium 2 leftover</strong> — <code>appium --version</code> prints <code>2.x</code>. Uninstall the old one (<code>npm uninstall -g appium</code>) then re-run step 2.</li>
598
+ </ol>
599
+ </div>
600
+
601
+ <h2 id="whats-next">What's next</h2>
602
+ <ul>
603
+ <li><a href="writing-tests.html">Writing tests</a> — your first test, actions, locators, assertions, isolation, hooks.</li>
604
+ <li><a href="generating-tests.html">Generating tests</a> — record a spec with the browser inspector + codegen.</li>
605
+ <li><a href="running-tests.html">Running &amp; debugging tests</a> — tracing, screen recording, artifacts, reports.</li>
606
+ <li><a href="parallel.html">Parallel runs</a> — device pools, workers, BrowserStack / LambdaTest.</li>
607
+ <li><a href="docker.html">Run in Docker</a> — skip the local toolchain with the bundled image.</li>
608
+ </ul>
609
+
610
+ <div class="pager">
611
+ <span></span>
612
+ <a class="next" href="writing-tests.html">
613
+ <div class="label">Next →</div>
614
+ <div class="title">Writing tests</div>
615
+ </a>
616
+ </div>
617
+
618
+ </main>
619
+
620
+ <aside class="onthispage">
621
+ <h4>On this page</h4>
622
+ <ol>
623
+ <li><a href="#introduction">Introduction</a></li>
624
+ <li><a href="#installing">Installing taqwright</a></li>
625
+ <li><a href="#whats-installed">What's installed</a></li>
626
+ <li><a href="#running-example">Running the example test</a></li>
627
+ <li><a href="#html-report">HTML test reports</a></li>
628
+ <li><a href="#updating">Updating taqwright</a></li>
629
+ <li><a href="#system-requirements">System requirements</a></li>
630
+ <li><a href="#quick-start">Quick start</a></li>
631
+ <li><a href="#setup">Fast path (auto-install)</a></li>
632
+ <li><a href="#install">Manual install</a>
633
+ <ol class="sub">
634
+ <li><a href="#install-node">Node.js 24+</a></li>
635
+ <li><a href="#install-appium">Appium 3.x</a></li>
636
+ <li><a href="#install-drivers">Appium drivers</a></li>
637
+ <li><a href="#install-android-toolchain">Android toolchain</a></li>
638
+ <li><a href="#install-ios-toolchain">iOS toolchain</a></li>
639
+ <li><a href="#install-device">A device</a></li>
640
+ <li><a href="#install-taqwright">Install taqwright</a></li>
641
+ <li><a href="#install-verify">Final verification</a></li>
642
+ </ol>
643
+ </li>
644
+ <li><a href="#whats-next">What's next</a></li>
645
+ </ol>
646
+ </aside>
647
+
648
+ </div>
649
+
650
+ <footer class="bot">
651
+ <div class="cols">
652
+ <div>
653
+ <h5>Getting started</h5>
654
+ <ul>
655
+ <li><a href="installation.html">Installation</a></li>
656
+ <li><a href="writing-tests.html">Writing tests</a></li>
657
+ <li><a href="generating-tests.html">Generating tests</a></li>
658
+ <li><a href="running-tests.html">Running &amp; debugging</a></li>
659
+ </ul>
660
+ </div>
661
+ <div>
662
+ <h5>Guides</h5>
663
+ <ul>
664
+ <li><a href="custom-reporters.html">Custom reporters</a></li>
665
+ <li><a href="parallel.html">Parallel runs</a></li>
666
+ <li><a href="docker.html">Run in Docker</a></li>
667
+ <li><a href="writing-tests.html#actions">API surface</a></li>
668
+ </ul>
669
+ </div>
670
+ <div>
671
+ <h5>Built on</h5>
672
+ <ul>
673
+ <li><a href="https://playwright.dev/">Playwright</a></li>
674
+ <li><a href="https://appium.io/">Appium 3</a></li>
675
+ </ul>
676
+ </div>
677
+ </div>
678
+ <div class="copy">
679
+ Apache-2.0 licensed · Built on Playwright + Appium
680
+ </div>
681
+ </footer>
682
+
683
+ <script src="docs.js"></script>
684
+
685
+ </body>
686
+ </html>