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/custom-reporters.html ADDED Viewed

@@ -0,0 +1,265 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Custom reporters · taqwright</title>
+<meta name="description" content="Build a custom report for taqwright runs. taqwright forwards the reporter option to Playwright, so any Playwright Reporter works — including ones that consume the taqwright-trace and taqwright-video attachments.">
+<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" class="current">Custom reporters</a></li>
+    <li class="sub"><a href="custom-reporters.html#overview">Overview</a></li>
+    <li class="sub"><a href="custom-reporters.html#writing">Writing a reporter</a></li>
+    <li class="sub"><a href="custom-reporters.html#wiring">Wiring it in</a></li>
+    <li class="sub"><a href="custom-reporters.html#artifacts">Consuming artifacts</a></li>
+    <li class="sub"><a href="custom-reporters.html#typescript">TypeScript &amp; deps</a></li>
+    <li><a href="parallel.html">Parallel runs</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/test-reporters">Playwright reporters ↗</a></li>
+    <li><a href="https://playwright.dev/docs/api/class-reporter">Reporter API ↗</a></li>
+  </ul>
+</aside>
+<main>
+<div class="breadcrumb">
+  <a href="installation.html">Docs</a> / Getting started / Custom reporters
+</div>
+<h1>Custom reporters</h1>
+<p class="lede">
+  Taqwright has <strong>no reporting layer of its own</strong> — it forwards the <code>reporter</code> option straight to Playwright's runner. So <strong>any Playwright reporter works unchanged</strong>, including a fully custom one you write. And because taqwright's device trace and screen recording are attached as standard Playwright attachments, your custom reporter can pull them into whatever report format you want.
+</p>
+<h2 id="overview">Overview</h2>
+<p>
+  When you run <code>npx taqwright test</code>, taqwright locates your <code>taqwright.config.ts</code> and spawns Playwright's own runner against it. <code>defineConfig()</code> returns a real Playwright <code>TestConfig</code> and passes <code>reporter</code> through verbatim — there is no whitelist, no wrapper, and no forced reporter. The built-in presets (<code>list</code>, <code>html</code>, <code>json</code>, <code>junit</code>, <code>blob</code>, <code>github</code>, …) are covered in <a href="running-tests.html#reports">Running &amp; debugging → Reports</a>. This page is about writing your <em>own</em>.
+</p>
+<div class="callout">
+  <strong>What "custom report" means here.</strong> A custom reporter is a small module that implements Playwright's <code>Reporter</code> interface. Playwright calls your hooks as tests run; you decide what to emit — a bespoke HTML dashboard, a Slack message, a CSV, a row in your own DB. It's the same mechanism Playwright's own <code>html</code> / <code>json</code> reporters use.
+</div>
+<h2 id="writing">Writing a custom reporter</h2>
+<p>
+  Implement the <code>Reporter</code> interface from <code>@playwright/test/reporter</code>. The three hooks you'll almost always want are <code>onBegin</code>, <code>onTestEnd</code>, and <code>onEnd</code>:
+</p>
+<div class="codeblock">
+  <div class="filename">reporters/my-reporter.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>import type {
+  Reporter, FullConfig, Suite, TestCase, TestResult, FullResult,
+} from '@playwright/test/reporter';
+export default class MyReporter implements Reporter {
+  private rows: Array&lt;Record&lt;string, unknown&gt;&gt; = [];
+  onBegin(config: FullConfig, suite: Suite) {
+    console.log(`Starting ${suite.allTests().length} tests`);
+  }
+  onTestEnd(test: TestCase, result: TestResult) {
+    this.rows.push({
+      title: test.titlePath().join(' › '),
+      project: test.parent.project()?.name,
+      status: result.status,                 // 'passed' | 'failed' | 'timedOut' | 'skipped'
+      durationMs: result.duration,
+      retry: result.retry,
+      error: result.error?.message,
+      attachments: result.attachments.map((a) =&gt; a.name),
+    });
+  }
+  async onEnd(result: FullResult) {
+    const fs = await import('node:fs/promises');
+    await fs.writeFile(
+      'reports/custom.json',
+      JSON.stringify({ status: result.status, tests: this.rows }, null, 2),
+    );
+    console.log(`Custom report written — overall: ${result.status}`);
+  }
+}</code></pre>
+</div>
+<p>
+  Every Playwright reporter hook is available (<code>onStdOut</code>, <code>onStdErr</code>, <code>onStepBegin</code>/<code>onStepEnd</code>, <code>onError</code>, <code>printsToStdio</code>, …). taqwright doesn't intercept any of them — your reporter sees exactly what a Playwright web reporter would: standard <code>TestCase</code> / <code>TestResult</code> objects, the Playwright-managed <code>result.status</code>, and the full attachment list.
+</p>
+<h2 id="wiring">Wiring it in</h2>
+<p>
+  Reference the reporter module from <code>taqwright.config.ts</code>. Use the <strong>array tuple form</strong> — <code>[modulePath]</code> or <code>[modulePath, options]</code> — and stack it alongside any built-ins:
+</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({
+  reporter: [
+    ['list'],                                  // keep a console reporter
+    ['./reporters/my-reporter.ts'],            // your custom reporter
+    ['./reporters/my-reporter.ts', { slackWebhook: process.env.SLACK_URL }],
+  ],
+  projects: [ /* ... */ ],
+});</code></pre>
+</div>
+<div class="callout warn">
+  <strong>Use the array form, not a bare string.</strong>
+  taqwright's <code>reporter</code> type is <code>presets | Array&lt;[string] | [string, unknown]&gt;</code>. The bare-string custom-module form (<code>reporter: './reporters/my-reporter.ts'</code>) is <em>not</em> in the type union, so TypeScript will flag it even though Playwright would accept it at runtime. Always wrap a custom reporter in the tuple form: <code>reporter: [['./reporters/my-reporter.ts']]</code>.
+</div>
+<p>
+  You can also pass it per-run on the CLI — <code>taqwright test</code> forwards <code>--reporter</code> to Playwright:
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright test --reporter=./reporters/my-reporter.ts
+# or stack with a preset:
+npx taqwright test --reporter=list,./reporters/my-reporter.ts</code></pre></div>
+<h2 id="artifacts">Consuming taqwright's trace &amp; video</h2>
+<p>
+  This is the part unique to taqwright. When <a href="running-tests.html#tracing"><code>trace</code></a> or <a href="running-tests.html#video"><code>video</code></a> is enabled, taqwright writes its artifacts as <strong>standard Playwright attachments</strong> on the test result — so a custom reporter reads them straight off <code>result.attachments</code>, no taqwright import required:
+</p>
+<table class="api">
+  <thead><tr><th>Attachment name</th><th><code>contentType</code></th><th>What it is</th></tr></thead>
+  <tbody>
+    <tr><td><code>taqwright-trace</code></td><td><code>text/html</code></td><td>Self-contained per-action timeline (screenshots + page-source) as one <code>trace.html</code>.</td></tr>
+    <tr><td><code>taqwright-video</code></td><td><code>video/mp4</code></td><td>Full-run on-device screen recording, <code>screen.mp4</code>.</td></tr>
+  </tbody>
+</table>
+<p>
+  They are deliberately <em>not</em> named <code>trace</code> / <code>video</code> — Playwright's own HTML report reserves those names for its browser <code>.zip</code> traces and recordings. Each attachment is the normal Playwright shape (<code>{ name, contentType, path }</code>, occasionally <code>body</code>), so you can copy, embed, or link them however your report needs:
+</p>
+<div class="codeblock">
+  <div class="filename">reporters/my-reporter.ts (excerpt)</div>
+  <pre class="code"><button class="copy">Copy</button><code>onTestEnd(test: TestCase, result: TestResult) {
+  for (const att of result.attachments) {
+    if (att.name === 'taqwright-trace' &amp;&amp; att.path) {
+      // e.g. copy next to your report and link it
+      this.traceFor[test.id] = att.path;            // .../trace.html (text/html)
+    }
+    if (att.name === 'taqwright-video' &amp;&amp; att.path) {
+      this.videoFor[test.id] = att.path;            // .../screen.mp4 (video/mp4)
+    }
+  }
+}</code></pre>
+</div>
+<div class="callout">
+  <strong>Retention follows the artifact mode.</strong> An attachment only exists when the run's outcome matches the configured mode (<code>'on'</code> always; <code>'on-failure'</code> / <code>'retain-on-failure'</code> only for failed tests). Always guard on <code>att.path</code> being present — don't assume every test result carries the trace/video.
+</div>
+<h2 id="typescript">TypeScript &amp; dependencies</h2>
+<ul>
+  <li><strong>A <code>.ts</code> reporter is fine.</strong> Playwright transpiles the reporter module the same way it transpiles your <code>taqwright.config.ts</code> — no separate build step needed.</li>
+  <li><strong>Type imports come from <code>@playwright/test/reporter</code>.</strong> taqwright doesn't re-export the reporter types. <code>@playwright/test</code> is a direct dependency of taqwright, so it already resolves in your project's <code>node_modules</code>; for clean, version-pinned editor types add it explicitly: <code>npm i -D @playwright/test</code>.</li>
+  <li><strong>Nothing taqwright-specific is required</strong> to write the reporter — it's a pure Playwright reporter. taqwright only affects <em>what</em> is in the attachments, not the reporter contract.</li>
+</ul>
+<div class="pager">
+  <a href="running-tests.html">
+    <div class="label">← Previous</div>
+    <div class="title">Running &amp; debugging tests</div>
+  </a>
+  <a class="next" href="parallel.html">
+    <div class="label">Next →</div>
+    <div class="title">Parallel runs</div>
+  </a>
+</div>
+</main>
+<aside class="onthispage">
+  <h4>On this page</h4>
+  <ol>
+    <li><a href="#overview">Overview</a></li>
+    <li><a href="#writing">Writing a custom reporter</a></li>
+    <li><a href="#wiring">Wiring it in</a></li>
+    <li><a href="#artifacts">Consuming trace &amp; video</a></li>
+    <li><a href="#typescript">TypeScript &amp; deps</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>

package/dist/docs/docker.html ADDED Viewed

@@ -0,0 +1,339 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Run in Docker · taqwright</title>
+<meta name="description" content="Skip the local toolchain — run taqwright in the bundled Docker image. Local Android over ADB-TCP, and cloud Android / iOS in CI.">
+<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">Parallel runs</a></li>
+    <li><a href="docker.html" class="current">Run in Docker</a></li>
+    <li class="sub"><a href="docker.html#docker-build">Build the image</a></li>
+    <li class="sub"><a href="docker.html#docker-local-android">Local Android</a></li>
+    <li class="sub"><a href="docker.html#docker-ci-android">CI: cloud Android</a></li>
+    <li class="sub"><a href="docker.html#docker-ci-ios">CI: cloud iOS</a></li>
+    <li class="sub"><a href="docker.html#docker-verify">Verify</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 / Run in Docker
+</div>
+<h1>Run in Docker</h1>
+<p class="lede">
+  Skip the local toolchain install — the repo's Docker setup bundles Node 24, Appium 3, JDK, the Android SDK command-line tools, and the UiAutomator2 driver into one image. Useful for reproducible CI and zero-setup onboarding.
+</p>
+<h2 id="docker">Run in Docker (optional)</h2>
+<p>
+  Skip the local toolchain install — the repo's <a href="https://docs.docker.com/get-docker/">Docker</a> setup bundles Node 24, Appium 3, JDK 21, the Android SDK command-line tools, and the UiAutomator2 driver into one image. Useful for CI (reproducible runs against a cloud device) and onboarding (contributors who don't want to install Appium / Android Studio locally).
+</p>
+<div class="callout">
+  <strong>Coverage:</strong> Android works fully inside Docker. iOS goes through a cloud provider (BrowserStack / LambdaTest) — XCUITest needs Xcode, which only runs on macOS, so it can't go in a container. Real-device USB passthrough is Linux-only; Mac users connect to emulators via ADB-over-TCP.
+</div>
+<p>The repo ships a <code>Dockerfile</code> and a <code>docker-compose.yml</code> with three profiles. Pick the one that matches what you're doing.</p>
+<h3 id="docker-build">Build the image (one-time)</h3>
+<p>
+  All three profile services share one image (<code>taqwright:local</code>). Build it once — subsequent <code>up</code> / <code>run</code> commands reuse the cache.
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>docker compose build appium</code></pre></div>
+<div class="callout">
+  <strong>Why <code>appium</code>?</strong>
+  All three services in <code>docker-compose.yml</code> are profile-gated, so a bare <code>docker compose build</code> sees no services and prints <code>No services to build</code>. Naming any service builds the shared image. Equivalent:
+  <code>docker compose --profile local-android build</code>.
+</div>
+<p>First-time build: 3–6 minutes on Apple Silicon (Rosetta-emulating the amd64 SDK), 2–4 minutes on Linux/Intel. Final image: ~1.3 GB.</p>
+<h4 id="docker-contents">What's in the image</h4>
+<p>Source of truth is the <a href="https://github.com/taqelah/taqwright/blob/main/Dockerfile"><code>Dockerfile</code></a> at the repo root. At a glance, the build layers are:</p>
+<table class="api">
+  <thead><tr><th>Layer</th><th>What &amp; why</th><th>~Size</th></tr></thead>
+  <tbody>
+    <tr>
+      <td><code>node:24-bookworm</code></td>
+      <td>Debian-based Node 24 LTS — matches <code>engines.node</code> in <code>package.json</code>.</td>
+      <td>~250 MB</td>
+    </tr>
+    <tr>
+      <td>System tools</td>
+      <td><code>openjdk-17-jre-headless</code> (Appium's UiAutomator2 driver needs 11+; 17 is what Debian bookworm ships by default) plus Debian's <code>adb</code> package (built for both amd64 and arm64 — Google's own platform-tools is x86_64-only on Linux, so we use Debian's so the image runs natively on Apple Silicon). Plus <code>curl</code> + <code>unzip</code> + <code>ca-certificates</code> for the SDK download.</td>
+      <td>~210 MB</td>
+    </tr>
+    <tr>
+      <td>Android cmdline-tools</td>
+      <td>Downloaded from Google's CDN at build time. Gives you <code>sdkmanager</code> (used at build time to accept SDK licenses). Java-based, so arch-neutral. We skip installing the platform-tools / system-images / emulator via sdkmanager — Debian's <code>adb</code> covers our adb need, and emulators don't work in Docker Desktop anyway.</td>
+      <td>~150 MB</td>
+    </tr>
+    <tr>
+      <td>Appium 3 + UiAutomator2 driver</td>
+      <td><code>npm install -g appium@^3</code> then <code>appium driver install uiautomator2</code>. No XCUITest — iOS goes through cloud providers.</td>
+      <td>~200 MB</td>
+    </tr>
+  </tbody>
+</table>
+<p>Env baked in (no shell setup needed inside the container):</p>
+<div class="codeblock"><pre class="code"><code>JAVA_HOME=/usr/lib/jvm/java-17-openjdk-{amd64,arm64}   # arch-suffix set by buildx
+ANDROID_HOME=/opt/android-sdk
+ANDROID_SDK_ROOT=/opt/android-sdk
+PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH</code></pre></div>
+<p>Default command: <code>appium --address 0.0.0.0 --port 4723 --base-path /</code>. The cloud-profile services override this with <code>npx taqwright test --project=…</code>.</p>
+<div class="callout">
+  <strong>When to rebuild</strong>: the <code>Dockerfile</code> itself changes, <code>engines.node</code> moves in <code>package.json</code>, or the pinned Appium / UiAutomator2 versions change. Other code changes don't require a rebuild — the test sources mount in via <code>volumes: - .:/work</code>.
+</div>
+<h3 id="docker-local-android">Local dev — Android emulator on the host</h3>
+<p>
+  Appium runs in the container; the emulator runs on your <strong>host</strong>. The container's <code>adb</code> connects to the emulator over TCP (port 5555). Works on macOS, Windows, and Linux Docker Desktop. Setup is five steps — three on the host, two inside the container.
+</p>
+<div class="callout">
+  <strong>Why the emulator stays on the host:</strong>
+  Android emulators need hardware virtualization (Apple's Hypervisor.framework on Mac, <code>/dev/kvm</code> on Linux). Docker Desktop on Mac / Windows runs Docker itself inside a VM — nested virtualization isn't passed through, so an emulator in the container would either refuse to boot or crawl. The container is the Appium runtime; the device is always external.
+</div>
+<p><strong>Prerequisite:</strong> at least one AVD created in Android Studio (or via <code>avdmanager</code>). Check what you have:</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>emulator -list-avds
+# Pixel_7_API_34         ← if you see names, you're set
+#                        # if empty: open Android Studio → Device Manager → Create Device</code></pre></div>
+<h4 id="docker-local-host-side">Host-side setup (per emulator session)</h4>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code># 1. Boot the emulator in the background:
+emulator -avd Pixel_7_API_34 &amp;
+# 2. Wait for Android to finish booting (~30s typically):
+adb wait-for-device
+adb shell getprop sys.boot_completed     # prints "1" when ready
+# 3. Confirm host sees it:
+adb devices
+# List of devices attached
+# emulator-5554    device
+# 4. Put it into TCP-listen mode so the container can reach it on :5555.
+# NOTE: this gets reset every emulator reboot — re-run after each boot.
+adb tcpip 5555
+# restarting in TCP mode port: 5555</code></pre></div>
+<h4 id="docker-local-container-side">Container-side setup</h4>
+<p>What the compose file wires up for you (no manual config needed):</p>
+<ul>
+  <li><strong>Port 4723</strong> mapped to your host — so <code>localhost:4723</code> reaches Appium inside the container.</li>
+  <li><strong><code>~/.android</code> (read-only volume)</strong> — shares your host's adb keypair (<code>adbkey</code> / <code>adbkey.pub</code>) with the container. Emulators you've already authorized on the host accept the container's adb without prompting again. Without this, <code>adb connect</code> would fail with <code>failed to authenticate</code>.</li>
+  <li><strong><code>host.docker.internal:host-gateway</code></strong> — makes the hostname resolve to your host's IP from inside the container (built-in on Docker Desktop, explicit on Linux).</li>
+</ul>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code># 5. Start the Appium container (detached so you can exec into it):
+docker compose --profile local-android up -d appium
+# 6. From inside the container, connect adb to the host emulator:
+docker compose exec appium adb connect host.docker.internal:5555
+# connected to host.docker.internal:5555
+# 7. Verify the container now sees the emulator:
+docker compose exec appium adb devices
+# List of devices attached
+# host.docker.internal:5555    device       ← anything other than "device"
+#                                              means try again from step 4</code></pre></div>
+<p>The chain is live: <strong>host emulator ← TCP :5555 ← container's adb ← Appium → port :4723 → your host</strong>. Verify Appium is reachable:</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>curl -s http://localhost:4723/status
+# {"value":{"ready":true,"message":"The server is ready...","build":{"version":"3.x.x"}}}</code></pre></div>
+<p>From here, you can:</p>
+<ul>
+  <li><strong>Run codegen</strong> against the containerized Appium: <code>cd</code> into your taqwright project, run <code>npx taqwright codegen</code>. The inspector opens in your browser, defaults to <code>localhost:4723</code> — just enter your app's <code>appium:appPackage</code> + <code>appium:appActivity</code> (pre-install the APK via <code>adb install</code> on the host first).</li>
+  <li><strong>Run tests</strong> from your host shell: <code>npx taqwright test</code> against a project whose <code>use.appium</code> points at <code>localhost:4723</code>.</li>
+</ul>
+<div class="callout warn">
+  <strong>If step 7 prints <code>offline</code>, empty, or step 6 says <code>failed to authenticate</code>:</strong>
+  <ul>
+    <li><strong><code>failed to authenticate</code></strong> → the container's adb has a different keypair than your host. The compose file mounts <code>~/.android</code> from your host into the container (read-only) so the keys match — make sure that volume is present. If you're running an older compose that doesn't have it, copy the keys manually:
+      <code>docker compose cp ~/.android/adbkey appium:/root/.android/adbkey &amp;&amp; docker compose cp ~/.android/adbkey.pub appium:/root/.android/adbkey.pub &amp;&amp; docker compose exec appium adb kill-server</code>, then retry step 6.</li>
+    <li>Emulator went to sleep → <code>adb disconnect host.docker.internal:5555</code> in the container, then re-run step 6.</li>
+    <li>Emulator was rebooted → re-run step 4 (<code>adb tcpip 5555</code>) on the host, then step 6.</li>
+    <li>Host shows no device in step 3 → no emulator running. Boot one via step 1.</li>
+    <li>The emulator may show <strong>"Allow USB debugging from this computer?"</strong> — click <strong>Always allow</strong>.</li>
+  </ul>
+</div>
+<p>When you're done, kill the emulator: <code>adb emu kill</code> (or close its window). And tear down the container: <code>docker compose --profile local-android down</code>.</p>
+<h3 id="docker-ci-android">CI — cloud Android (BrowserStack / LambdaTest)</h3>
+<p>
+  No local Appium and no local emulator. The test runner container talks directly to the cloud provider. Define an <code>android-cloud</code> project in your <code>taqwright.config.ts</code> with <code>device.provider: 'browserstack'</code> (or <code>'lambdatest'</code>) and your credentials in env.
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>export BROWSERSTACK_USERNAME=...
+export BROWSERSTACK_ACCESS_KEY=...
+docker compose --profile ci-cloud-android run --rm tests-cloud-android</code></pre></div>
+<p>The container mounts your repo at <code>/work</code>, forwards your credentials, and runs <code>npx taqwright test --project=android-cloud</code>. Results land in <code>./playwright-report/</code> on the host.</p>
+<h3 id="docker-ci-ios">CI — cloud iOS</h3>
+<p>
+  Same image, same env vars; just a different project name. Your <code>ios-cloud</code> project in <code>taqwright.config.ts</code> needs <code>platform: Platform.IOS</code> and <code>device.provider: 'browserstack'</code> (or <code>'lambdatest'</code>) — the cloud handles all the iOS-specific machinery.
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>export BROWSERSTACK_USERNAME=...
+export BROWSERSTACK_ACCESS_KEY=...
+docker compose --profile ci-cloud-ios run --rm tests-cloud-ios</code></pre></div>
+<h3 id="docker-verify">Verify the image</h3>
+<p>Run the doctor inside the container — it'll confirm Node / Appium / adb / java are all present:</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>docker compose run --rm tests-cloud-android npx taqwright doctor</code></pre></div>
+<p>Expected output — the macOS-only lines (<code>xcrun</code>, <code>Xcode</code>, <code>ffmpeg</code>, <code>iOS simulator</code>) are absent because the container is Linux, and only the <code>uiautomator2</code> Appium driver is in the image (iOS goes through the cloud):</p>
+<div class="codeblock"><pre class="code"><code>taqwright doctor (v0.0.1)
+  [ok] Node.js >= 24  — v24.x.x
+  [ok] adb (Android SDK)  — on PATH
+  [ok] ANDROID_HOME (Appium adb lookup)  — ANDROID_HOME=/opt/android-sdk
+  [ok] java (JDK for UiAutomator2)  — on PATH
+  [ok] JAVA_HOME (UiAutomator2 JDK)  — JAVA_HOME=/usr/lib/jvm/java-17-openjdk-arm64
+  [ok] Appium (test server)  — on PATH (v3.x.x)
+  [ok] Appium drivers  — uiautomator2; not installed: xcuitest (iOS)</code></pre></div>
+<div class="callout">
+  <strong>Apple Silicon Macs:</strong>
+  the image is amd64; Docker Desktop runs it under Rosetta. Initial build is slower (SDK download under emulation) but test runs are fine. A native arm64 variant is on the roadmap.
+</div>
+<div class="pager">
+  <a href="parallel.html">
+    <div class="label">← Previous</div>
+    <div class="title">Parallel runs</div>
+  </a>
+  <a class="next" href="installation.html">
+    <div class="label">Next →</div>
+    <div class="title">Back to Installation</div>
+  </a>
+</div>
+</main>
+<aside class="onthispage">
+  <h4>On this page</h4>
+  <ol>
+    <li><a href="#docker">Overview</a></li>
+    <li><a href="#docker-build">Build the image</a>
+      <ol class="sub">
+        <li><a href="#docker-contents">What's in the image</a></li>
+      </ol>
+    </li>
+    <li><a href="#docker-local-android">Local Android</a>
+      <ol class="sub">
+        <li><a href="#docker-local-host-side">Host setup</a></li>
+        <li><a href="#docker-local-container-side">Container setup</a></li>
+      </ol>
+    </li>
+    <li><a href="#docker-ci-android">CI: cloud Android</a></li>
+    <li><a href="#docker-ci-ios">CI: cloud iOS</a></li>
+    <li><a href="#docker-verify">Verify</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>