@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/discovery.js ADDED
@@ -0,0 +1,55 @@
1
+ import { Platform } from './types/index.js';
2
+ import { listDevices } from './inspector/devices.js';
3
+ export function toAssignableSlots(listing, opts) {
4
+ const { platform, provider } = opts;
5
+ if (provider === 'local-device' && platform === Platform.IOS) {
6
+ throw new Error('taqwright: device.autoDiscover is not supported for local-device + iOS — ' +
7
+ 'no multi-device enumerator exists for physical iPhones. Set device.udid or device.pool.');
8
+ }
9
+ let slots;
10
+ if (platform === Platform.ANDROID && provider === 'emulator') {
11
+ slots = listing.android
12
+ .filter((d) => !!d.avdName)
13
+ .map((d) => ({ udid: d.udid, name: d.avdName, osVersion: d.osVersion || undefined }));
14
+ slots.sort((a, b) => (a.name ?? '').localeCompare(b.name ?? ''));
15
+ }
16
+ else if (platform === Platform.ANDROID && provider === 'local-device') {
17
+ slots = listing.android
18
+ .filter((d) => !d.avdName && !d.udid.startsWith('emulator-'))
19
+ .map((d) => ({ udid: d.udid, name: d.name, osVersion: d.osVersion }));
20
+ slots.sort((a, b) => a.udid.localeCompare(b.udid));
21
+ }
22
+ else {
23
+ slots = listing.ios.map((d) => ({ udid: d.udid, name: d.name, osVersion: d.osVersion }));
24
+ slots.sort((a, b) => a.udid.localeCompare(b.udid));
25
+ }
26
+ const seen = new Set();
27
+ slots = slots.filter((s) => (seen.has(s.udid) ? false : (seen.add(s.udid), true)));
28
+ if (opts.name !== undefined) {
29
+ const want = opts.name;
30
+ slots = slots.filter((s) => {
31
+ if (s.name === undefined)
32
+ return false;
33
+ return want instanceof RegExp ? want.test(s.name) : s.name === want;
34
+ });
35
+ }
36
+ if (opts.osVersion !== undefined) {
37
+ slots = slots.filter((s) => s.osVersion === undefined || s.osVersion === opts.osVersion);
38
+ }
39
+ return slots;
40
+ }
41
+ export function selectDevicePool(slots, workers) {
42
+ if (slots.length < workers) {
43
+ throw new Error(`taqwright: device.autoDiscover found ${slots.length} ` +
44
+ `device${slots.length === 1 ? '' : 's'} but \`workers\` is ${workers}. ` +
45
+ `Start/connect more devices (or AVDs/simulators), or lower \`workers\`.`);
46
+ }
47
+ return slots.slice(0, workers);
48
+ }
49
+ export async function discoverAssignableDevices(opts) {
50
+ return toAssignableSlots(await listDevices(), opts);
51
+ }
52
+ export function resolvedPoolEnvKey(projectName) {
53
+ const safe = (projectName ?? '').replace(/[^A-Za-z0-9_]/g, '_');
54
+ return `TAQWRIGHT_RESOLVED_POOL__${safe}`;
55
+ }
package/dist/docs/configuration.html ADDED
@@ -0,0 +1,376 @@
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>Configuration · taqwright</title>
7
+ <meta name="description" content="The taqwright.config.ts that taqwright init generates — projects, device + Appium, resetBetweenTests, reporters, iosParallelCaps, and the full use-options reference.">
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">Installation</a></li>
38
+ <li><a href="writing-tests.html">Writing tests</a></li>
39
+ <li><a href="generating-tests.html">Generating tests</a></li>
40
+ <li><a href="running-tests.html">Running &amp; debugging</a></li>
41
+ <li><a href="custom-reporters.html">Custom reporters</a></li>
42
+ <li><a href="parallel.html">Parallel runs</a></li>
43
+ <li><a href="docker.html">Run in Docker</a></li>
44
+ </ul>
45
+
46
+ <h3>Taqwright Test</h3>
47
+ <ul>
48
+ <li><a href="configuration.html" class="current">Configuration</a></li>
49
+ <li class="sub"><a href="configuration.html#configure">taqwright.config.ts</a></li>
50
+ <li class="sub"><a href="configuration.html#ios-parallel-caps">iosParallelCaps()</a></li>
51
+ <li class="sub"><a href="configuration.html#use-options">Common use options</a></li>
52
+ </ul>
53
+
54
+ <h3>Reference</h3>
55
+ <ul>
56
+ <li><a href="https://playwright.dev/docs/intro">Playwright runner ↗</a></li>
57
+ <li><a href="https://appium.io/docs/en/latest/">Appium 3 ↗</a></li>
58
+ </ul>
59
+ </aside>
60
+
61
+ <main>
62
+
63
+ <div class="breadcrumb">
64
+ <a href="installation.html">Docs</a> / Taqwright Test / Configuration
65
+ </div>
66
+
67
+ <h1>Configuration</h1>
68
+ <p class="lede">
69
+ Project config lives in <code>taqwright.config.ts</code>. This is <strong>exactly what <code>taqwright init</code> generates</strong> for an Android project with the demo app (the default <code>npm init taqwright</code> path) — every knob is listed, essentials uncommented, the rest commented placeholders you enable by deleting the leading <code>// </code>. The bundled demo app and its managed <code>taqwright_api34</code> AVD are already wired, so <code>npx taqwright test</code> works out of the box. Choosing <code>--platform both</code> adds an <code>ios</code> project; declining the demo prompt leaves <code>buildPath</code> / <code>appBundleId</code> as commented placeholders instead.
70
+ </p>
71
+
72
+ <h2 id="configure">taqwright.config.ts</h2>
73
+
74
+ <div class="codeblock">
75
+ <div class="filename">taqwright.config.ts</div>
76
+ <pre class="code"><button class="copy">Copy</button><code>import { defineConfig, Platform } from 'taqwright';
77
+
78
+ // Every config knob is listed here. Essentials are uncommented; everything
79
+ // else is a commented placeholder you can enable by removing the leading
80
+ // "// ". Hover any field in your editor for the full type docs.
81
+ export default defineConfig({
82
+ testDir: './tests',
83
+ timeout: 60_000,
84
+ expectTimeout: 30_000,
85
+ // 'html' writes playwright-report/ — view it with: npx taqwright show-report
86
+ reporter: [['list'], ['html', { open: 'never' }]],
87
+
88
+ // ─── Optional top-level overrides ─────────────────────────────────
89
+ // retries: 1,
90
+ // outputDir: './test-results',
91
+ // fullyParallel: false,
92
+ // forbidOnly: !!process.env.CI,
93
+ // testMatch: ['**/*.spec.ts'],
94
+ // testIgnore: ['**/wip/**'],
95
+ // globalSetup: './setup.ts',
96
+ // globalTeardown: './teardown.ts',
97
+
98
+ projects: [
99
+ {
100
+ name: 'android',
101
+ use: {
102
+ platform: Platform.ANDROID,
103
+ device: {
104
+ provider: 'emulator',
105
+ name: 'taqwright_api34', // AVD from `taqwright install --with-avd`
106
+ // osVersion: '14',
107
+ // udid: 'emulator-5554',
108
+ // orientation: 'portrait',
109
+ //
110
+ // ─── Parallel runs (optional) ────────────────────────────
111
+ // Declare a pool of devices to fan tests out across, then
112
+ // bump `workers` at the top of this config to match. Worker
113
+ // N picks pool[N]; `workers > pool.length` fails fast. Each
114
+ // worker gets its own Appium + driver ports auto-staggered.
115
+ // pool: [
116
+ // { udid: 'emulator-5554', name: 'Pixel_7_API_34' },
117
+ // { udid: 'emulator-5556', name: 'Pixel_7_API_34_2' },
118
+ // { udid: 'emulator-5558', name: 'Pixel_7_API_34_3' },
119
+ // ],
120
+ },
121
+ // Spawn `npx appium` automatically when nothing is listening on
122
+ // the configured host:port. Set `autoStart: false` to manage
123
+ // Appium yourself (e.g. when Appium runs in Docker — see the
124
+ // `Run in Docker` guide).
125
+ appium: {
126
+ autoStart: true,
127
+ // Boot an offline Android emulator automatically. Needs a
128
+ // string device.name equal to the AVD id (e.g. 'Pixel_7_API_34',
129
+ // see 'emulator -list-avds'); a RegExp name is rejected at
130
+ // config load. iOS simulators boot via XCUITest regardless.
131
+ autoStartDevice: true, // cold-boots the taqwright_api34 AVD
132
+ host: 'localhost',
133
+ port: 4723, // Appium 3 default
134
+ path: '/', // Appium 3 default (Appium 1.x used '/wd/hub')
135
+ // newCommandTimeout: 240,
136
+ // logLevel: 'warn',
137
+ },
138
+
139
+ // ─── Reset between tests ────────────────────────────────────
140
+ // Bound to the bundled demo app (app/DemoApp-v1.0.0.apk).
141
+ // resetBetweenTests reinstalls + relaunches it fresh before every
142
+ // test, so each starts from a known state. All three are
143
+ // type-required together.
144
+ resetBetweenTests: true,
145
+ buildPath: './app/DemoApp-v1.0.0.apk',
146
+ appBundleId: 'com.taqelah.demo_app',
147
+
148
+ // ─── Extra capabilities (escape hatch) ──────────────────────
149
+ // Anything Appium accepts; merged on top of the auto-built caps.
150
+ // capabilities: {
151
+ // 'appium:autoGrantPermissions': true,
152
+ // 'appium:autoAcceptAlerts': true,
153
+ // },
154
+
155
+ // ─── Per-project locator-action timeout (ms) ────────────────
156
+ // Overrides the top-level `expectTimeout` for this project only.
157
+ // expectTimeout: 30_000,
158
+
159
+ // ─── Trace artifact ─────────────────────────────────────────
160
+ // Captures a per-action screenshot + page-source timeline as a
161
+ // self-contained `trace.html` under the test's output dir, also
162
+ // attached to the Playwright HTML report. Adds one screenshot +
163
+ // page-source round-trip per action (~100–300ms local, more
164
+ // over USB) — recommended for CI: 'on-failure'.
165
+ // 'off' — no overhead (default)
166
+ // 'on' — every test
167
+ // 'on-failure' — only failed tests
168
+ // 'retain-on-failure' — alias of 'on-failure' on mobile
169
+ // trace: 'on-failure',
170
+
171
+ // ─── Screen recording (video) ───────────────────────────────
172
+ // Records the device screen via Appium for the whole run and
173
+ // attaches a screen.mp4 to the Playwright HTML report (as
174
+ // 'taqwright-video'). No per-action cost like trace, but every
175
+ // run pays the device recorder + an mp4 transfer at teardown —
176
+ // recommended for CI: 'on-failure'. iOS-simulator support varies.
177
+ // 'off' — no recording (default)
178
+ // 'on' — every test
179
+ // 'on-failure' — only failed tests
180
+ // 'retain-on-failure' — alias of 'on-failure' on mobile
181
+ // video: 'on-failure',
182
+ },
183
+
184
+ // ─── Per-project test-runner overrides ────────────────────────
185
+ // timeout: 90_000,
186
+ // retries: 2,
187
+ // grep: /smoke/,
188
+ // grepInvert: /flaky/,
189
+ // dependencies: ['setup'],
190
+ // testMatch: ['**/android/*.spec.ts'],
191
+ },
192
+
193
+ // ─── Cloud examples (BrowserStack / LambdaTest) ─────────────────
194
+ // Uncomment a block below to add a cloud project. Set the matching
195
+ // env vars before launching:
196
+ // BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY
197
+ // LAMBDATEST_USERNAME / LAMBDATEST_ACCESS_KEY
198
+ // For now, cloud devices are wired through the inspector
199
+ // ('taqwright inspect'); cloud test-runner support lands separately.
200
+ //
201
+ // {
202
+ // name: 'browserstack',
203
+ // use: {
204
+ // platform: Platform.ANDROID,
205
+ // device: {
206
+ // provider: 'browserstack',
207
+ // name: 'Google Pixel 8',
208
+ // osVersion: '14.0',
209
+ // orientation: 'portrait',
210
+ // },
211
+ // resetBetweenTests: true,
212
+ // buildPath: 'bs://&lt;app-id-from-app-upload&gt;',
213
+ // appBundleId: 'com.example.app',
214
+ // },
215
+ // },
216
+ // {
217
+ // name: 'lambdatest',
218
+ // use: {
219
+ // platform: Platform.IOS,
220
+ // device: {
221
+ // provider: 'lambdatest',
222
+ // name: 'iPhone 15',
223
+ // osVersion: '17',
224
+ // },
225
+ // resetBetweenTests: true,
226
+ // buildPath: 'lt://&lt;app-id-from-app-upload&gt;',
227
+ // appBundleId: 'com.example.MyApp',
228
+ // },
229
+ // },
230
+ ],
231
+ });</code></pre>
232
+ </div>
233
+
234
+ <div class="callout">
235
+ <strong>What this config does:</strong>
236
+ <ul>
237
+ <li><strong><code>reporter</code></strong> — console <code>list</code> plus an HTML report under <code>playwright-report/</code>; open it with <code>npx taqwright show-report</code>.</li>
238
+ <li><strong><code>android</code> project</strong> — <code>appium.autoStart</code> spawns Appium and <code>autoStartDevice</code> cold-boots the managed <code>taqwright_api34</code> AVD (from <code>npx taqwright install --with-avd</code>) — no manual emulator launch.</li>
239
+ <li><strong><code>resetBetweenTests</code> + <code>buildPath</code> + <code>appBundleId</code></strong> — bound to the bundled demo app (<code>app/DemoApp-v1.0.0.apk</code>); reinstalled + relaunched fresh before every test.</li>
240
+ <li>Everything else — parallel <code>pool</code>, <code>trace</code>, <code>video</code>, extra capabilities, and the BrowserStack / LambdaTest cloud projects — is a commented placeholder you enable as needed.</li>
241
+ </ul>
242
+ </div>
243
+
244
+ <p>To run your own app instead of the demo, swap <code>buildPath</code> and <code>appBundleId</code> (the Android package id from your <code>AndroidManifest.xml</code>), and point <code>device.name</code> at one of your own AVDs (<code>emulator -list-avds</code>) — or drop <code>autoStartDevice</code> and boot an emulator yourself. The <code>iosParallelCaps()</code> helper below is for iOS projects you add.</p>
245
+
246
+ <h2 id="ios-parallel-caps"><code>iosParallelCaps(slot, opts?)</code></h2>
247
+ <p>
248
+ iOS-specific helper that returns a capabilities block tuned for parallel runs. Two parallel iOS simulators would otherwise collide on the default WDA port (<code>8100</code>), the MJPEG screenshot port (<code>9100</code>), and the Xcode DerivedData directory. <code>iosParallelCaps(N)</code> generates per-slot offsets so each session is isolated:
249
+ </p>
250
+
251
+ <table class="api">
252
+ <thead><tr><th>Slot</th><th>wdaLocalPort</th><th>mjpegServerPort</th><th>derivedDataPath</th></tr></thead>
253
+ <tbody>
254
+ <tr><td>0</td><td>8100</td><td>9100</td><td>/tmp/wda-0</td></tr>
255
+ <tr><td>1</td><td>8101</td><td>9101</td><td>/tmp/wda-1</td></tr>
256
+ <tr><td>N</td><td>8100 + N</td><td>9100 + N</td><td>/tmp/wda-N</td></tr>
257
+ </tbody>
258
+ </table>
259
+
260
+ <p>
261
+ <strong>One slot per separate iOS <em>project</em>, not per device.</strong> The
262
+ <code>slot</code> argument exists so two iOS <em>projects</em> in the same config don't
263
+ fight (project A → <code>iosParallelCaps(0)</code>, project B →
264
+ <code>iosParallelCaps(1)</code>). Parallelism <em>within</em> one iOS project comes from
265
+ <a href="parallel.html#parallel"><code>device.pool</code></a> + <code>workers</code>, and the worker
266
+ fixture auto-staggers these same ports per worker — so a single iOS project (even with a
267
+ 3-simulator pool) just uses <code>iosParallelCaps(0)</code>. Only
268
+ <code>wdaLocalPort</code> / <code>mjpegServerPort</code> / <code>derivedDataPath</code>
269
+ change with the slot; the WDA tunings below are identical for every slot.
270
+ </p>
271
+
272
+ <p>
273
+ It returns a plain object (<code>Record&lt;string, unknown&gt;</code>), so use the
274
+ <code>...</code> spread to merge it with your own extra capabilities — later keys win:
275
+ </p>
276
+
277
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>capabilities: {
278
+ ...iosParallelCaps(0), // WDA ports + tunings (slot 0)
279
+ 'appium:forceSimulatorSoftwareKeyboardPresence': true, // your extra cap, merged on top
280
+ },</code></pre></div>
281
+
282
+ <p>Plus baked-in WDA tunings that work for most setups: <code>useNewWDA: true</code> (fresh build each session, prevents stale-WDA failures), <code>wdaStartupRetries: 4</code>, and generous launch/connection timeouts (120s / 360s) that cover Xcode's slow first-build phase. Override any of these <em>tuning</em> fields via the second argument (the spread above is for adding <em>arbitrary</em> caps; the second arg only accepts the WDA knobs):</p>
283
+
284
+ <div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>capabilities: iosParallelCaps(0, {
285
+ useNewWDA: false, // reuse WDA across sessions
286
+ wdaLaunchTimeout: 180_000, // 3 min for slower CI machines
287
+ }),</code></pre></div>
288
+
289
+ <div class="callout">
290
+ <strong>When you don't need this helper:</strong>
291
+ <ul>
292
+ <li>You're using <code>device.pool</code> within a single iOS project — the worker fixture already auto-staggers these per-worker (since v0.x).</li>
293
+ <li>You're running iOS through a cloud provider (BrowserStack / LambdaTest) — the cloud manages WDA itself; don't set these caps.</li>
294
+ <li>You only ever run one iOS simulator at a time — Appium's defaults work fine without staggering.</li>
295
+ </ul>
296
+ </div>
297
+
298
+ <h2 id="use-options">Common <code>use</code> options</h2>
299
+
300
+ <table class="api">
301
+ <thead><tr><th>Option</th><th>Description</th></tr></thead>
302
+ <tbody>
303
+ <tr><td><code>platform</code></td><td><code>Platform.ANDROID</code> or <code>Platform.IOS</code>.</td></tr>
304
+ <tr><td><code>device</code></td><td>Where the test runs. <code>{ provider: 'emulator' | 'local-device' | 'browserstack' | 'lambdatest', name, udid?, osVersion? }</code>. See <a href="parallel.html#parallel">Parallel runs</a> for <code>device.pool</code>.</td></tr>
305
+ <tr><td><code>buildPath</code></td><td>Path to the APK / IPA / <code>.app</code> to install.</td></tr>
306
+ <tr><td><code>appBundleId</code></td><td>App bundle id (Android package name / iOS bundle id).</td></tr>
307
+ <tr><td><code>resetBetweenTests</code></td><td>If <code>true</code>, terminate → uninstall → install → activate the app between every test. Requires <code>buildPath</code> and <code>appBundleId</code>.</td></tr>
308
+ <tr><td><code>expectTimeout</code></td><td>Default timeout for locator actions, in ms. Default <code>30000</code>.</td></tr>
309
+ <tr><td><code>appium</code></td><td>Appium server connection: <code>{ host, port, path, autoStart?, autoStartDevice? }</code>. <code>autoStart: true</code> spawns <code>npx appium</code> if nothing is listening on the port. <code>autoStartDevice: true</code> cold-boots an offline <strong>Android emulator</strong> via <code>appium:avd</code> (requires a <em>string</em> <code>device.name</code> = the AVD id; a RegExp is rejected at config load); iOS simulators are auto-booted by XCUITest regardless; real devices / cloud: no-op.</td></tr>
310
+ <tr><td><code>capabilities</code></td><td>Escape hatch for extra Appium capabilities, merged on top of the defaults — e.g. <code>appium:autoGrantPermissions</code>, <code>appium:wdaLocalPort</code>. For iOS, taqwright sets <code>appium:forceSimulatorSoftwareKeyboardPresence: true</code> by default (the simulator hides the software keyboard otherwise); pass it here as <code>false</code> to opt out.</td></tr>
311
+ <tr><td><code>trace</code></td><td><code>'off' | 'on' | 'on-failure' | 'retain-on-failure'</code>. Captures per-action screenshots + page-source as a self-contained <code>trace.html</code> under the test's output dir. Details in <a href="running-tests.html#tracing">Tracing</a>.</td></tr>
312
+ <tr><td><code>video</code></td><td><code>'off' | 'on' | 'on-failure' | 'retain-on-failure'</code>. Records the device screen via Appium for the whole run and attaches a <code>screen.mp4</code>. Details in <a href="running-tests.html#video">Screen recording</a>.</td></tr>
313
+ </tbody>
314
+ </table>
315
+
316
+ <div class="pager">
317
+ <a href="installation.html">
318
+ <div class="label">← Previous</div>
319
+ <div class="title">Installation</div>
320
+ </a>
321
+ <a class="next" href="custom-reporters.html">
322
+ <div class="label">Next →</div>
323
+ <div class="title">Custom reporters</div>
324
+ </a>
325
+ </div>
326
+
327
+ </main>
328
+
329
+ <aside class="onthispage">
330
+ <h4>On this page</h4>
331
+ <ol>
332
+ <li><a href="#configure">taqwright.config.ts</a></li>
333
+ <li><a href="#ios-parallel-caps">iosParallelCaps()</a></li>
334
+ <li><a href="#use-options">Common <code>use</code> options</a></li>
335
+ </ol>
336
+ </aside>
337
+
338
+ </div>
339
+
340
+ <footer class="bot">
341
+ <div class="cols">
342
+ <div>
343
+ <h5>Getting started</h5>
344
+ <ul>
345
+ <li><a href="installation.html">Installation</a></li>
346
+ <li><a href="writing-tests.html">Writing tests</a></li>
347
+ <li><a href="generating-tests.html">Generating tests</a></li>
348
+ <li><a href="running-tests.html">Running &amp; debugging</a></li>
349
+ </ul>
350
+ </div>
351
+ <div>
352
+ <h5>Guides</h5>
353
+ <ul>
354
+ <li><a href="configuration.html">Configuration</a></li>
355
+ <li><a href="custom-reporters.html">Custom reporters</a></li>
356
+ <li><a href="parallel.html">Parallel runs</a></li>
357
+ <li><a href="docker.html">Run in Docker</a></li>
358
+ </ul>
359
+ </div>
360
+ <div>
361
+ <h5>Built on</h5>
362
+ <ul>
363
+ <li><a href="https://playwright.dev/">Playwright</a></li>
364
+ <li><a href="https://appium.io/">Appium 3</a></li>
365
+ </ul>
366
+ </div>
367
+ </div>
368
+ <div class="copy">
369
+ Apache-2.0 licensed · Built on Playwright + Appium
370
+ </div>
371
+ </footer>
372
+
373
+ <script src="docs.js"></script>
374
+
375
+ </body>
376
+ </html>