npm - @taqwright/taqwright - Versions diffs - 0.0.24 - Mend

@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

package/LICENSE +201 -0
package/README.md +108 -0
package/dist/auto-appium.d.ts +12 -0
package/dist/auto-appium.js +77 -0
package/dist/bin/branding.d.ts +6 -0
package/dist/bin/branding.js +22 -0
package/dist/bin/index.d.ts +2 -0
package/dist/bin/index.js +321 -0
package/dist/bin/init.d.ts +26 -0
package/dist/bin/init.js +902 -0
package/dist/bin/inspect.d.ts +9 -0
package/dist/bin/inspect.js +91 -0
package/dist/bin/report-branding.d.ts +2 -0
package/dist/bin/report-branding.js +42 -0
package/dist/branding-assets.d.ts +1 -0
package/dist/branding-assets.js +1 -0
package/dist/capabilities-helpers.d.ts +7 -0
package/dist/capabilities-helpers.js +14 -0
package/dist/capabilities.d.ts +6 -0
package/dist/capabilities.js +86 -0
package/dist/config.d.ts +17 -0
package/dist/config.js +235 -0
package/dist/discovery-setup.d.ts +1 -0
package/dist/discovery-setup.js +61 -0
package/dist/discovery.d.ts +17 -0
package/dist/discovery.js +55 -0
package/dist/docs/configuration.html +376 -0
package/dist/docs/custom-reporters.html +265 -0
package/dist/docs/docker.html +339 -0
package/dist/docs/docs.js +173 -0
package/dist/docs/generating-tests.html +161 -0
package/dist/docs/images/taqwright-html-report.png +0 -0
package/dist/docs/index.html +13 -0
package/dist/docs/installation.html +686 -0
package/dist/docs/parallel.html +271 -0
package/dist/docs/running-tests.html +385 -0
package/dist/docs/styles.css +460 -0
package/dist/docs/writing-tests.html +565 -0
package/dist/doctor.d.ts +33 -0
package/dist/doctor.js +508 -0
package/dist/expect.d.ts +38 -0
package/dist/expect.js +96 -0
package/dist/fixture/artifact-mode.d.ts +2 -0
package/dist/fixture/artifact-mode.js +7 -0
package/dist/fixture/index.d.ts +15 -0
package/dist/fixture/index.js +324 -0
package/dist/images/taqwright-html-report.png +0 -0
package/dist/images/taqwright_favicon.png +0 -0
package/dist/images/taqwright_logo.png +0 -0
package/dist/index.d.ts +9 -0
package/dist/index.js +7 -0
package/dist/inspector/codegen-appium.d.ts +3 -0
package/dist/inspector/codegen-appium.js +228 -0
package/dist/inspector/devices.d.ts +41 -0
package/dist/inspector/devices.js +422 -0
package/dist/inspector/locator-suggester.d.ts +23 -0
package/dist/inspector/locator-suggester.js +539 -0
package/dist/inspector/recorder.d.ts +128 -0
package/dist/inspector/recorder.js +162 -0
package/dist/inspector/server.d.ts +39 -0
package/dist/inspector/server.js +1210 -0
package/dist/inspector/session.d.ts +84 -0
package/dist/inspector/session.js +262 -0
package/dist/inspector/ui.d.ts +1 -0
package/dist/inspector/ui.js +5508 -0
package/dist/keys.d.ts +3 -0
package/dist/keys.js +28 -0
package/dist/locator/index.d.ts +206 -0
package/dist/locator/index.js +1506 -0
package/dist/logger.d.ts +5 -0
package/dist/logger.js +5 -0
package/dist/mobile/index.d.ts +130 -0
package/dist/mobile/index.js +762 -0
package/dist/network/android.d.ts +5 -0
package/dist/network/android.js +87 -0
package/dist/network/ca.d.ts +10 -0
package/dist/network/ca.js +136 -0
package/dist/network/har.d.ts +90 -0
package/dist/network/har.js +101 -0
package/dist/network/host-proxy.d.ts +16 -0
package/dist/network/host-proxy.js +134 -0
package/dist/network/index.d.ts +26 -0
package/dist/network/index.js +105 -0
package/dist/network/ios-sim.d.ts +3 -0
package/dist/network/ios-sim.js +29 -0
package/dist/network/proxy.d.ts +13 -0
package/dist/network/proxy.js +310 -0
package/dist/providers/appium.d.ts +23 -0
package/dist/providers/appium.js +288 -0
package/dist/providers/browserstack/index.d.ts +5 -0
package/dist/providers/browserstack/index.js +77 -0
package/dist/providers/browserstack/utils.d.ts +1 -0
package/dist/providers/browserstack/utils.js +6 -0
package/dist/providers/cloud.d.ts +53 -0
package/dist/providers/cloud.js +117 -0
package/dist/providers/emulator/index.d.ts +8 -0
package/dist/providers/emulator/index.js +47 -0
package/dist/providers/index.d.ts +10 -0
package/dist/providers/index.js +33 -0
package/dist/providers/lambdatest/index.d.ts +28 -0
package/dist/providers/lambdatest/index.js +99 -0
package/dist/providers/lambdatest/utils.d.ts +1 -0
package/dist/providers/lambdatest/utils.js +6 -0
package/dist/providers/local/index.d.ts +9 -0
package/dist/providers/local/index.js +53 -0
package/dist/providers/local-session.d.ts +16 -0
package/dist/providers/local-session.js +55 -0
package/dist/setup/archive.d.ts +2 -0
package/dist/setup/archive.js +43 -0
package/dist/setup/avd.d.ts +12 -0
package/dist/setup/avd.js +103 -0
package/dist/setup/index.d.ts +6 -0
package/dist/setup/index.js +55 -0
package/dist/setup/install-android.d.ts +2 -0
package/dist/setup/install-android.js +70 -0
package/dist/setup/install-appium.d.ts +1 -0
package/dist/setup/install-appium.js +64 -0
package/dist/setup/install-jdk.d.ts +1 -0
package/dist/setup/install-jdk.js +58 -0
package/dist/setup/paths.d.ts +16 -0
package/dist/setup/paths.js +88 -0
package/dist/setup/spawn-tool.d.ts +3 -0
package/dist/setup/spawn-tool.js +11 -0
package/dist/tracer/index.d.ts +34 -0
package/dist/tracer/index.js +687 -0
package/dist/tracer/proxy.d.ts +3 -0
package/dist/tracer/proxy.js +60 -0
package/dist/types/index.d.ts +189 -0
package/dist/types/index.js +6 -0
package/dist/utils.d.ts +2 -0
package/dist/utils.js +37 -0
package/package.json +79 -0

package/dist/docs/parallel.html ADDED Viewed

@@ -0,0 +1,271 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Parallel runs · taqwright</title>
+<meta name="description" content="Run taqwright tests in parallel — device pools, worker partitioning, the workers × fullyParallel × pool matrix, and BrowserStack / LambdaTest.">
+<link rel="stylesheet" href="styles.css">
+<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>
+</head>
+<body>
+<header class="topbar">
+  <button class="menu-toggle" id="menu-toggle" aria-label="Toggle navigation">☰</button>
+  <a class="brand" href="installation.html"><span class="accent">taq</span>wright</a>
+  <nav class="primary">
+    <a href="installation.html" class="current">Docs</a>
+    <a href="generating-tests.html">Inspector</a>
+    <a href="writing-tests.html#actions">API</a>
+  </nav>
+  <span class="spacer"></span>
+  <div class="search" title="Search (placeholder)">
+    <span>Search docs…</span>
+    <span class="kbd">⌘K</span>
+  </div>
+  <button class="theme-toggle" id="theme-toggle" aria-label="Switch to light theme" title="Switch to light theme"></button>
+  <a class="gh-link" href="https://github.com/taqelah/taqwright" title="GitHub">
+    <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>
+  </a>
+</header>
+<div class="shell">
+<aside class="sidebar" id="sidebar">
+  <h3>Getting started</h3>
+  <ul>
+    <li><a href="installation.html">Installation</a></li>
+    <li><a href="writing-tests.html">Writing tests</a></li>
+    <li><a href="generating-tests.html">Generating tests</a></li>
+    <li><a href="running-tests.html">Running &amp; debugging</a></li>
+    <li><a href="custom-reporters.html">Custom reporters</a></li>
+    <li><a href="parallel.html" class="current">Parallel runs</a></li>
+    <li class="sub"><a href="parallel.html#parallel">Device pools</a></li>
+    <li class="sub"><a href="parallel.html#parallel-combos">The matrix</a></li>
+    <li class="sub"><a href="parallel.html#parallel-cloud">On the cloud</a></li>
+    <li><a href="docker.html">Run in Docker</a></li>
+  </ul>
+  <h3>Taqwright Test</h3>
+  <ul>
+    <li><a href="configuration.html">Configuration</a></li>
+  </ul>
+  <h3>Reference</h3>
+  <ul>
+    <li><a href="https://playwright.dev/docs/intro">Playwright runner ↗</a></li>
+    <li><a href="https://appium.io/docs/en/latest/">Appium 3 ↗</a></li>
+  </ul>
+</aside>
+<main>
+<div class="breadcrumb">
+  <a href="installation.html">Docs</a> / Getting started / Parallel runs
+</div>
+<h1>Parallel runs</h1>
+<p class="lede">
+  Taqwright is <strong>serial by default</strong> — one Appium, one device. To go parallel you either declare a local <strong>device pool</strong> and raise <code>workers</code>, or point at a cloud provider where each worker is its own independent session.
+</p>
+<h2 id="parallel">Device pools</h2>
+<p>
+  Taqwright defaults to <code>workers: 1</code> — one Appium + one device, serial. To run tests truly in parallel against multiple devices, declare a <strong>device pool</strong> and bump <code>workers</code>:
+</p>
+<div class="codeblock">
+  <div class="filename">taqwright.config.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>import { defineConfig, Platform } from 'taqwright';
+export default defineConfig({
+  workers: 3,
+  fullyParallel: true,
+  projects: [{
+    name: 'android-parallel',
+    use: {
+      platform: Platform.ANDROID,
+      device: {
+        provider: 'emulator',
+        pool: [
+          { udid: 'emulator-5554', name: 'Pixel_7_API_34' },
+          { udid: 'emulator-5556', name: 'Pixel_7_API_34_2' },
+          { udid: 'emulator-5558', name: 'Pixel_7_API_34_3' },
+        ],
+      },
+      buildPath: './app.apk',
+      appBundleId: 'com.example.app',
+      appium: { autoStart: true, port: 4723 },
+    },
+  }],
+});</code></pre>
+</div>
+<p>How worker partitioning works:</p>
+<ul>
+  <li>Worker <code>N</code> picks <code>pool[N]</code>. Worker <code>N</code> where <code>N &gt;= pool.length</code> fails fast with a clear error — never silently double-books a device.</li>
+  <li>Each worker spawns its own Appium on <code>basePort + N</code> when <code>appium.autoStart: true</code>, and kills it when the worker tears down.</li>
+  <li>Driver-specific ports (<code>appium:systemPort</code>, <code>appium:wdaLocalPort</code>, <code>appium:chromedriverPort</code>, <code>appium:mjpegServerPort</code>) are auto-staggered per worker so two UiAutomator2 / XCUITest sessions don't fight over the same port.</li>
+</ul>
+<p>For iOS, the WDA / MJPEG port + DerivedData staggering is handled by <a href="configuration.html#ios-parallel-caps"><code>iosParallelCaps()</code></a> — one slot per separate iOS <em>project</em>; pool-driven parallelism within a single iOS project is auto-staggered per worker.</p>
+<h3 id="parallel-combos"><code>workers</code> × <code>fullyParallel</code> × <code>device.pool</code> — what happens</h3>
+<p>
+  <code>fullyParallel</code> only changes Playwright's <em>scheduling granularity</em> (tests-within-a-file vs whole-files per worker) — it never raises the concurrent-device count, which is bounded by <code>workers</code>. So the only thing that risks device contention is <code>workers&nbsp;&gt;&nbsp;1</code>, and that's now caught at <strong>config load</strong>.
+</p>
+<table class="api">
+  <thead><tr><th><code>workers</code></th><th><code>fullyParallel</code></th><th><code>device.pool</code></th><th>Result</th><th>What to do</th></tr></thead>
+  <tbody>
+    <tr>
+      <td><code>1</code> (default)</td><td><code>false</code> (default)</td><td>none</td>
+      <td><strong>Safe.</strong> Serial — one Appium + one device, one test at a time.</td>
+      <td>Nothing — this is the default.</td>
+    </tr>
+    <tr>
+      <td><code>1</code></td><td><code>true</code></td><td>none</td>
+      <td><strong>Safe.</strong> Still serial (one worker). <code>fullyParallel</code> only re-orders the schedule; nothing runs concurrently.</td>
+      <td>Harmless; it has no real effect with one worker. Leave it or drop it.</td>
+    </tr>
+    <tr>
+      <td><code>&gt; 1</code></td><td>any</td><td><strong>none</strong></td>
+      <td><strong>Rejected at config load.</strong> <code>defineConfig</code> throws; <code>taqwright&nbsp;test</code> aborts before any Appium/device work (no silent collision).</td>
+      <td>Add a <code>device.pool</code> with at least <code>workers</code> entries, <em>or</em> set <code>workers:&nbsp;1</code>.</td>
+    </tr>
+    <tr>
+      <td><code>&gt; 1</code></td><td>any</td><td>pool, <code>length &lt; workers</code></td>
+      <td><strong>Rejected at config load.</strong> Under-sized pool — some workers would have no device.</td>
+      <td>Grow the pool to at least <code>workers</code> entries, <em>or</em> lower <code>workers</code>.</td>
+    </tr>
+    <tr>
+      <td><code>&gt; 1</code></td><td><code>true</code></td><td>pool, <code>length &gt;= workers</code></td>
+      <td><strong>Correct parallel.</strong> Each worker gets <code>pool[idx]</code> + its own Appium + staggered driver ports; every test fans out across the pool.</td>
+      <td>This is the intended parallel setup.</td>
+    </tr>
+    <tr>
+      <td><code>&gt; 1</code></td><td><code>false</code></td><td>pool, <code>length &gt;= workers</code></td>
+      <td><strong>Parallel across files only.</strong> Workers run different files concurrently; tests within a file stay sequential.</td>
+      <td>Fine for file-level parallelism. Set <code>fullyParallel:&nbsp;true</code> to also distribute tests <em>within</em> a file.</td>
+    </tr>
+  </tbody>
+</table>
+<p>
+  <strong>Cloud exemption:</strong> <code>browserstack</code> / <code>lambdatest</code> projects have no <code>device.pool</code> (the field doesn't exist on their type) and the provider manages its own device queueing, so the config-load check skips them — <code>workers&nbsp;&gt;&nbsp;1</code> is not rejected for a cloud-only project.
+</p>
+<div class="callout warn">
+  <strong>Don't run multiple workers against one device.</strong>
+  Without an adequately sized pool, <code>workers &gt; 1</code> is rejected with a clear error at config load — <code>taqwright test</code> aborts before any device work, rather than letting multiple workers collide on one Appium session. Either set <code>workers: 1</code>, or declare a <code>device.pool</code> with at least <code>workers</code> entries.
+</div>
+<h3 id="parallel-cloud">Parallel runs on BrowserStack / LambdaTest</h3>
+<p>
+  Cloud providers need <strong>no <code>device.pool</code></strong>. Each Playwright worker is its own OS process and opens its own independent cloud session, so parallelism is plain <code>workers: N</code> + <code>fullyParallel: true</code> — the provider queues device contention on its side. The config-load pool check skips cloud-only projects, so <code>workers&nbsp;&gt;&nbsp;1</code> is never rejected for them.
+</p>
+<div class="codeblock">
+  <div class="filename">taqwright.config.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>import { defineConfig, Platform } from 'taqwright';
+export default defineConfig({
+  workers: 5,            // 5 parallel cloud sessions — no device.pool
+  fullyParallel: true,   // defineConfig defaults to false (serial)
+  projects: [{
+    name: 'browserstack',
+    use: {
+      platform: Platform.ANDROID,
+      device: {
+        provider: 'browserstack',   // or 'lambdatest'
+        name: 'Google Pixel 8',
+        osVersion: '14.0',
+        orientation: 'portrait',    // optional
+      },
+      buildPath: 'bs://&lt;hashed-app-id&gt;',   // pre-uploaded; see note below
+      appBundleId: 'com.example.app',         // required for LambdaTest
+      trace: 'on-failure',
+      video: 'off',                           // cloud records server-side
+    },
+  }],
+});</code></pre>
+</div>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>export BROWSERSTACK_USERNAME=...    # or LAMBDATEST_USERNAME
+export BROWSERSTACK_ACCESS_KEY=...   # or LAMBDATEST_ACCESS_KEY
+npx taqwright test --project browserstack --workers 5</code></pre></div>
+<ul>
+  <li><strong>Parallelism is <code>workers: N</code>, nothing else.</strong> No <code>device.pool</code>, no per-worker Appium, no driver-port staggering — that machinery is local-only. One worker = one cloud session; pass/fail is pushed to the provider dashboard on teardown so sessions don't sit &quot;Running&quot; until idle-timeout.</li>
+  <li><strong>Credentials come from the environment</strong> (<code>BROWSERSTACK_USERNAME</code>/<code>BROWSERSTACK_ACCESS_KEY</code>, or <code>LAMBDATEST_USERNAME</code>/<code>LAMBDATEST_ACCESS_KEY</code>) — never in the config. Missing creds fail the worker fast with the provider's own message, before any session opens.</li>
+  <li><strong><code>--workers N</code> overrides the config value</strong> for that run, so you can dial parallelism per-run without editing the config.</li>
+  <li><strong>Video</strong> is recorded server-side and viewed on the provider dashboard — taqwright attaches no mp4 for cloud runs. <strong>Trace</strong> still works and lands in the HTML report.</li>
+  <li><strong><code>resetBetweenTests</code></strong> still type-requires <code>buildPath</code>&nbsp;+&nbsp;<code>appBundleId</code>, but the on-device terminate/reinstall dance is skipped — the build lives in the cloud. Isolation comes from a fresh session per test plus the provider's own reset.</li>
+</ul>
+<div class="callout">
+  <strong>Two cloud gotchas.</strong>
+  <strong>(1)</strong> Bound <code>workers</code> to your provider plan's parallel-session limit — extra workers just block waiting for a free slot.
+  <strong>(2)</strong> The build upload runs <em>once per worker process</em> and the cached URL doesn't cross worker boundaries, so a local <code>.apk</code>/<code>.ipa</code> in <code>buildPath</code> is uploaded <code>N</code> times for <code>N</code> workers. Pre-upload once and reference the returned <code>bs://</code> / <code>lt://</code> URL (as above) — that path skips the upload entirely.
+</div>
+<div class="pager">
+  <a href="custom-reporters.html">
+    <div class="label">← Previous</div>
+    <div class="title">Custom reporters</div>
+  </a>
+  <a class="next" href="docker.html">
+    <div class="label">Next →</div>
+    <div class="title">Run in Docker</div>
+  </a>
+</div>
+</main>
+<aside class="onthispage">
+  <h4>On this page</h4>
+  <ol>
+    <li><a href="#parallel">Device pools</a></li>
+    <li><a href="#parallel-combos">The matrix</a></li>
+    <li><a href="#parallel-cloud">On the cloud</a></li>
+  </ol>
+</aside>
+</div>
+<footer class="bot">
+  <div class="cols">
+    <div>
+      <h5>Getting started</h5>
+      <ul>
+        <li><a href="installation.html">Installation</a></li>
+        <li><a href="writing-tests.html">Writing tests</a></li>
+        <li><a href="generating-tests.html">Generating tests</a></li>
+        <li><a href="running-tests.html">Running &amp; debugging</a></li>
+      </ul>
+    </div>
+    <div>
+      <h5>Guides</h5>
+      <ul>
+        <li><a href="custom-reporters.html">Custom reporters</a></li>
+        <li><a href="parallel.html">Parallel runs</a></li>
+        <li><a href="docker.html">Run in Docker</a></li>
+        <li><a href="writing-tests.html#actions">API surface</a></li>
+      </ul>
+    </div>
+    <div>
+      <h5>Built on</h5>
+      <ul>
+        <li><a href="https://playwright.dev/">Playwright</a></li>
+        <li><a href="https://appium.io/">Appium 3</a></li>
+      </ul>
+    </div>
+  </div>
+  <div class="copy">
+    Apache-2.0 licensed · Built on Playwright + Appium
+  </div>
+</footer>
+<script src="docs.js"></script>
+</body>
+</html>