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/running-tests.html ADDED Viewed

@@ -0,0 +1,385 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Running &amp; debugging tests · taqwright</title>
+<meta name="description" content="Tracing, screen recording, the output directory, and reporters — debug taqwright runs after the fact and ship results to 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" class="current">Running &amp; debugging</a></li>
+    <li class="sub"><a href="running-tests.html#tracing">Tracing</a></li>
+    <li class="sub"><a href="running-tests.html#video">Screen recording</a></li>
+    <li class="sub"><a href="running-tests.html#output-dir">Output &amp; artifacts</a></li>
+    <li class="sub"><a href="running-tests.html#reports">Reports</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">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 / Running &amp; debugging tests
+</div>
+<h1>Running &amp; debugging tests</h1>
+<p class="lede">
+  When a test fails on a device you can't see, you need a record of what happened. Taqwright captures two kinds — a per-action <strong>trace</strong> and a full-run <strong>video</strong> — writes them under the <strong>output directory</strong>, and hands everything to Playwright's <strong>reporters</strong>.
+</p>
+<h2 id="tracing">Tracing — post-mortem debugging</h2>
+<p>
+  Set <code>trace</code> in a project's <code>use</code> block to capture a per-action screenshot + page-source timeline of every test run. The result is a self-contained <code>trace.html</code> file under the test's output directory, attached to the Playwright HTML report as <code>taqwright-trace</code>.
+</p>
+<div class="callout">
+  <strong>Open it directly.</strong> It's a standalone HTML page — in the Playwright report, click the <code>taqwright-trace</code> attachment to open it in a new tab. It is <em>not</em> a Playwright <code>.zip</code> trace, so don't load it in the Playwright Trace Viewer (that viewer reports <em>"Could not load trace"</em> for it).
+</div>
+<table class="api">
+  <thead><tr><th>Value</th><th>Behaviour</th></tr></thead>
+  <tbody>
+    <tr><td><code>'off'</code> (default)</td><td>No overhead — Tracer never instantiated.</td></tr>
+    <tr><td><code>'on'</code></td><td>Trace every test; HTML always written.</td></tr>
+    <tr><td><code>'on-failure'</code></td><td>Trace every test; HTML written only when the test fails. <strong>Recommended for CI.</strong></td></tr>
+    <tr><td><code>'retain-on-failure'</code></td><td>Alias of <code>'on-failure'</code> on mobile.</td></tr>
+  </tbody>
+</table>
+<div class="codeblock">
+  <div class="filename">taqwright.config.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>{
+  name: 'android',
+  use: {
+    // ... rest of your use options
+    trace: 'on-failure',
+  },
+}</code></pre>
+</div>
+<p>What ends up in <code>trace.html</code>:</p>
+<ul>
+  <li><strong>Per-action timeline</strong> — each <code>click</code> / <code>fill</code> / <code>assertVisible</code> / etc. gets a row, in execution order.</li>
+  <li><strong>Post-state screenshot</strong> for every step (click thumbnail to zoom).</li>
+  <li><strong>Page-source XML</strong> snapshot at that moment.</li>
+  <li><strong>Per-step timing</strong> + error message highlighted on the failing step.</li>
+</ul>
+<div class="callout">
+  <strong>Cost:</strong>
+  each traced action adds one <code>takeScreenshot</code> + one <code>getPageSource</code> round-trip (~100–300 ms on a local emulator, more over USB / cloud). A 30-action test on <code>trace: 'on'</code> typically goes from ~5 s to ~15 s. That's why <code>'on-failure'</code> is the sweet spot for CI.
+</div>
+<p><strong>How it works under the hood:</strong> the <code>mobile</code> fixture wraps the Mobile + Locator instances in a Proxy when <code>trace !== 'off'</code>. Chain methods (<code>filter</code> / <code>first</code> / <code>nth</code> / <code>locator</code> / <code>and</code> / <code>or</code>) pass through untraced — only the terminal action (<code>click</code>, <code>fill</code>, etc.) records an entry. So <code>mobile.getByType('Cell').nth(2).click()</code> produces one row in the trace, not three.</p>
+<p>For <strong>interactive</strong> debugging during development (instead of post-mortem), drop <code>await mobile.pause()</code> in a test — it hands the in-flight WebDriver session off to the inspector in your browser. See <a href="generating-tests.html#pause">Generating tests → Debug a live test</a>.</p>
+<h2 id="video">Screen recording — full-run video</h2>
+<p>
+  Set <code>video</code> in a project's <code>use</code> block to capture an Appium on-device screen recording of every test run. The result is a <code>screen.mp4</code> under the test's output directory, attached to the Playwright HTML report as <code>taqwright-video</code>.
+</p>
+<div class="callout">
+  <strong>It's a plain video.</strong> In the Playwright report, click the <code>taqwright-video</code> attachment to play the <code>.mp4</code>. It is <em>not</em> a Playwright Trace Viewer trace, and it's deliberately named <code>taqwright-video</code> (not <code>video</code>) so the report doesn't confuse it with its own browser recordings.
+</div>
+<div class="callout">
+  <strong>iOS simulators require <code>ffmpeg</code> on <code>PATH</code>.</strong>
+  XCUITest records the iOS <em>simulator</em> by piping frames through host
+  <code>ffmpeg</code>. If it isn't installed, Appium's
+  <code>startRecordingScreen</code> throws at session start and
+  <strong>every iOS test in that project fails in fixture setup</strong> with
+  <code>WebDriverError: 'ffmpeg' binary is not found in PATH</code> — this is
+  by design (the fixture surfaces the error loudly rather than producing an
+  empty <code>.mp4</code>). Install it once:
+  <code>brew install ffmpeg</code> (macOS) /
+  <code>sudo apt-get install ffmpeg</code> (Linux), then verify with
+  <code>ffmpeg -version</code>. Android emulators/devices and <em>real</em>
+  iOS devices record on-device and need <strong>no</strong> host
+  <code>ffmpeg</code>. Note this affects every non-<code>'off'</code> mode:
+  <code>'on-failure'</code> still starts the recorder at session start, so it
+  fails the same way without <code>ffmpeg</code> — set
+  <code>video: 'off'</code> for the iOS project if you can't install it.
+</div>
+<table class="api">
+  <thead><tr><th>Value</th><th>Behaviour</th></tr></thead>
+  <tbody>
+    <tr><td><code>'off'</code> (default)</td><td>No recording — recorder never started.</td></tr>
+    <tr><td><code>'on'</code></td><td>Record every test; <code>.mp4</code> always kept.</td></tr>
+    <tr><td><code>'on-failure'</code></td><td>Record every test; <code>.mp4</code> kept only when the test fails. <strong>Recommended for CI.</strong></td></tr>
+    <tr><td><code>'retain-on-failure'</code></td><td>Alias of <code>'on-failure'</code> on mobile.</td></tr>
+  </tbody>
+</table>
+<div class="codeblock">
+  <div class="filename">taqwright.config.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>{
+  name: 'android',
+  use: {
+    // ... rest of your use options
+    video: 'on-failure',
+  },
+}</code></pre>
+</div>
+<h3 id="video-view">Run &amp; verify</h3>
+<p>
+  With <code>video</code> set, just run the project — recording is automatic. The <code>.mp4</code> is written when the test finishes (teardown), so let the run complete.
+</p>
+<div class="codeblock">
+  <pre class="code"><button class="copy">Copy</button><code># run the project (emulator/simulator up; Appium auto-starts if configured)
+npx taqwright test --project=android
+# open the HTML report, then: pick the test → Attachments → taqwright-video
+npx taqwright show-report</code></pre>
+</div>
+<p>
+  In the report, open the test and expand <strong>Attachments</strong> — click <code>taqwright-video</code> to play the recording inline (alongside <code>taqwright-trace</code> if <a href="#tracing">tracing</a> is also on). To skip the report and grab the file directly, it's <code>screen.mp4</code> in the test's output folder:
+</p>
+<div class="codeblock">
+  <pre class="code"><button class="copy">Copy</button><code>find test-results -name screen.mp4 -exec open {} \;</code></pre>
+</div>
+<p>
+  Expectations: with <code>'on'</code> you get an <code>.mp4</code> every run (pass or fail); with <code>'on-failure'</code> only failing tests keep one. The file lives under <a href="#output-dir"><code>outputDir</code></a> (gitignored by the <code>taqwright init</code> scaffold), so it isn't committed. If you don't see the attachment, confirm the run actually reached teardown and that the project's <code>use.video</code> isn't <code>'off'</code>.
+</p>
+<div class="callout">
+  <strong>Cost &amp; caveats:</strong> recording happens on the device for the whole run, so unlike <a href="#tracing">tracing</a> there is <em>no</em> per-action penalty — but every run pays the device recorder plus a base64 transfer of the <code>.mp4</code> at teardown, even when the buffer is discarded on a pass (<code>'on-failure'</code>/<code>'retain-on-failure'</code>). Expect a few MB per minute. Long tests are capped at 30&nbsp;min (the Appium maximum) so recordings aren't silently truncated. On-device recording support varies by driver — real devices and Android emulators record on-device and work out of the box; the iOS <em>simulator</em> needs host <code>ffmpeg</code> on <code>PATH</code> (see the callout above) and the fixture surfaces a clear error at session start rather than producing an empty file.
+</div>
+<p><strong>How it works under the hood:</strong> the <code>mobile</code> fixture calls Appium's <code>startRecordingScreen</code> before the test body and always <code>stopRecordingScreen</code> at teardown (so the device recorder can't leak between tests). The base64 payload is written to <code>screen.mp4</code> and attached only when the run's outcome matches the selected mode. <code>video</code> and <code>trace</code> are independent — enable both and you get a <code>taqwright-video</code> MP4 plus a <code>taqwright-trace</code> HTML timeline for the same run.</p>
+<h2 id="output-dir">Output directory &amp; artifacts</h2>
+<p>
+  <code>outputDir</code> is the root directory for everything a test run produces on disk — the <code>trace.html</code> from <a href="#tracing">tracing</a>, any <code>testInfo.attach(...)</code> files, and anything a test writes via <code>testInfo.outputPath(...)</code>. It's a top-level <code>defineConfig</code> option, overridable per project.
+</p>
+<div class="codeblock">
+  <div class="filename">taqwright.config.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>export default defineConfig({
+  testDir: './tests',
+  outputDir: './test-results',     // top-level default for every project
+  projects: [
+    {
+      name: 'android',
+      outputDir: './test-results/android',   // optional per-project override
+      use: { /* ... */ },
+    },
+  ],
+});</code></pre>
+</div>
+<ul>
+  <li><strong>Per-test subfolder</strong> — each test gets its own directory under <code>outputDir</code>, named <code>&lt;file&gt;-&lt;title&gt;-&lt;project&gt;/</code>. Two tests never clobber each other's artifacts.</li>
+  <li><strong>Path resolution</strong> — relative paths are resolved against the <code>taqwright.config.ts</code> location, not the shell's cwd, so the runner works the same whether launched from the project root or a subfolder.</li>
+  <li><strong>Default</strong> — if you omit <code>outputDir</code>, it falls back to Playwright's default <code>test-results/</code> in the config directory.</li>
+  <li><strong>Reading it from a test</strong> — <code>testInfo</code> is the second argument to the test function: <code>test('name', async ({ mobile }, testInfo) =&gt; { ... })</code>. Use <code>testInfo.outputDir</code> or <code>testInfo.outputPath('file.png')</code> to write your own artifacts into the per-test folder.</li>
+</ul>
+<div class="callout">
+  <strong>Git:</strong> add <code>outputDir</code> (e.g. <code>test-results</code>) to <code>.gitignore</code> — it's regenerated every run, not source. The <code>taqwright init</code> scaffold already ignores <code>test-results/</code> for you.
+</div>
+<h2 id="reports">Reports</h2>
+<p>
+  taqwright forwards the <code>reporter</code> option straight to Playwright. Reporters are <strong>run-level</strong> (there is no per-project reporter), and you stack several at once with the array form. Need a bespoke format? See <a href="custom-reporters.html">Custom reporters</a>.
+</p>
+<table class="api">
+  <thead><tr><th>Reporter</th><th>Writes to</th><th>Use for</th></tr></thead>
+  <tbody>
+    <tr><td><code>'list'</code> (default)</td><td>console — one line per test</td><td>local / interactive</td></tr>
+    <tr><td><code>'line'</code></td><td>console — compact, updating line</td><td>larger suites</td></tr>
+    <tr><td><code>'dot'</code></td><td>console — one char per test</td><td>huge suites / CI logs</td></tr>
+    <tr><td><code>'html'</code></td><td><code>outputFolder/</code> — browsable site</td><td>debugging, sharing</td></tr>
+    <tr><td><code>'json'</code></td><td><code>outputFile</code></td><td>custom tooling</td></tr>
+    <tr><td><code>'junit'</code></td><td><code>outputFile</code></td><td>CI (Jenkins/GitLab/Azure)</td></tr>
+    <tr><td><code>'blob'</code></td><td><code>outputDir/</code> — shardable</td><td><code>merge-reports</code> across shards</td></tr>
+    <tr><td><code>'github'</code></td><td>GitHub Actions annotations</td><td>CI only</td></tr>
+  </tbody>
+</table>
+<div class="codeblock">
+  <div class="filename">taqwright.config.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>export default defineConfig({
+  reporter: [
+    ['list'],                                            // ONE console reporter only
+    ['html',  { open: 'never', outputFolder: 'reports/html' }],
+    ['json',  { outputFile:  'reports/results.json' }],
+    ['junit', { outputFile:  'reports/results.xml' }],
+    ...(process.env.CI ? [['github'] as [string]] : []), // CI-only annotations
+    ['blob',  { outputDir:   'reports/blob' }],
+  ],
+});</code></pre>
+</div>
+<ul>
+  <li><strong>One console reporter.</strong> <code>list</code> / <code>line</code> / <code>dot</code> all write to stdout — stacking two interleaves the output into noise. Pick one; the file reporters coexist cleanly.</li>
+  <li><strong>Give <code>json</code> / <code>junit</code> an <code>outputFile</code></strong> — without it they print to stdout and collide with the console reporter.</li>
+  <li><strong><code>github</code> is CI-only.</strong> It emits GitHub Actions <code>::notice::</code> / <code>::error::</code> annotations; locally it just prints a hardcoded Playwright summary line. Gate it on <code>process.env.CI</code> as shown.</li>
+</ul>
+<div class="callout danger">
+  <strong>Don't nest the HTML report inside <code>outputDir</code>.</strong> The <code>html</code> reporter <em>wipes</em> its <code>outputFolder</code> before regenerating. If that folder sits inside the test <a href="#output-dir"><code>outputDir</code></a> (e.g. <code>outputFolder: 'test-results/html'</code> with <code>outputDir: 'test-results'</code>), Playwright errors — <em>"HTML reporter output folder clashes with the tests output folder"</em> — and per-test artifacts are destroyed. Keep reports a <strong>sibling</strong> of <code>outputDir</code> (e.g. <code>reports/</code> next to <code>test-results/</code>).
+</div>
+<h3 id="reports-view">Viewing the HTML report</h3>
+<p>After a run, serve it with:</p>
+<div class="codeblock">
+  <pre class="code"><button class="copy">Copy</button><code>npx taqwright show-report reports/html
+# --host &lt;host&gt; (default localhost) · --port &lt;port&gt; (default 9323)</code></pre>
+</div>
+<p>
+  taqwright prints this exact (taqwright-branded) command at the end of an interactive run. <code>show-report</code> also serves a blob <code>.zip</code> directly.
+</p>
+<h3 id="reports-per-project">Per-project report directories</h3>
+<p>
+  Because reporters are run-level, one run merges every project into a single report. For an isolated report <em>per</em> project, run once per project and let the config derive reporter paths from an env var — <code>taqwright.config.ts</code> is just TypeScript, so it can read <code>process.env</code>:
+</p>
+<div class="codeblock">
+  <div class="filename">taqwright.config.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>const proj = process.env.TW_REPORT_PROJECT;
+const base = proj ? `reports/${proj}` : 'reports/_all';
+export default defineConfig({
+  outputDir: './test-results',                  // sibling of reports/ — no clash
+  reporter: [
+    ['list'],
+    ['html',  { open: 'never', outputFolder: `${base}/html-report` }],
+    ['json',  { outputFile:  `${base}/results.json` }],
+    ['junit', { outputFile:  `${base}/results.xml` }],
+    ['blob',  { outputDir:   `${base}/blob-report` }],
+  ],
+  // ...
+});</code></pre>
+</div>
+<div class="codeblock">
+  <div class="filename">package.json</div>
+  <pre class="code"><button class="copy">Copy</button><code>{
+  "scripts": {
+    "test:android": "TW_REPORT_PROJECT=android taqwright test --project=android",
+    "test:ios":     "TW_REPORT_PROJECT=ios taqwright test --project=ios",
+    "report:android": "taqwright show-report reports/android/html-report",
+    "report:ios":     "taqwright show-report reports/ios/html-report"
+  }
+}</code></pre>
+</div>
+<p>
+  Each invocation writes only under its own <code>reports/&lt;project&gt;/</code> — runs never clobber each other. A plain <code>taqwright test</code> (all projects, one run, env unset) falls back to <code>reports/_all/</code>.
+</p>
+<div class="pager">
+  <a href="generating-tests.html">
+    <div class="label">← Previous</div>
+    <div class="title">Generating tests</div>
+  </a>
+  <a class="next" href="custom-reporters.html">
+    <div class="label">Next →</div>
+    <div class="title">Custom reporters</div>
+  </a>
+</div>
+</main>
+<aside class="onthispage">
+  <h4>On this page</h4>
+  <ol>
+    <li><a href="#tracing">Tracing</a></li>
+    <li><a href="#video">Screen recording</a>
+      <ol class="sub">
+        <li><a href="#video-view">Run &amp; verify</a></li>
+      </ol>
+    </li>
+    <li><a href="#output-dir">Output &amp; artifacts</a></li>
+    <li><a href="#reports">Reports</a>
+      <ol class="sub">
+        <li><a href="#reports-view">Viewing the report</a></li>
+        <li><a href="#reports-per-project">Per-project dirs</a></li>
+      </ol>
+    </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>