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

@@ -0,0 +1,565 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Writing tests · taqwright</title>
+<meta name="description" content="Write your first taqwright test. Actions, locators, assertions, isolation, hooks.">
+<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" class="current">Writing tests</a></li>
+    <li class="sub"><a href="writing-tests.html#introduction">Introduction</a></li>
+    <li class="sub"><a href="writing-tests.html#first-test">First test</a></li>
+    <li class="sub"><a href="writing-tests.html#actions">Actions</a></li>
+    <li class="sub"><a href="writing-tests.html#assertions">Assertions</a></li>
+    <li class="sub"><a href="writing-tests.html#isolation">Test isolation</a></li>
+    <li class="sub"><a href="writing-tests.html#hooks">Hooks</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">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 / Writing tests
+</div>
+<h1>Writing tests</h1>
+<p class="lede">
+  Taqwright tests <strong>perform actions</strong> on a live mobile device and <strong>assert the resulting UI state</strong>. Each test gets a fresh WebDriver session against your configured emulator, simulator, or physical device. Locators auto-wait for elements to be visible and actionable before driving them, so tests stay reliable even when the app animates.
+</p>
+<h2 id="introduction">Introduction</h2>
+<p>
+  Taqwright sits on top of <a href="https://playwright.dev/">Playwright</a>'s test runner and <a href="https://appium.io/">Appium 3</a>. From Playwright you get parallelism, retries, projects, sharding, fixtures, the HTML reporter, and the <code>test</code> / <code>expect</code> primitives. From Appium you get UiAutomator2 (Android) and XCUITest (iOS) underneath, with a flat <code>mobile</code> API and a chainable <code>Locator</code> on top.
+</p>
+<p>
+  You write tests the same way you'd write a Playwright web test — same file shape, same hooks, same runner flags — but you drive a phone instead of a browser. New here? Do the <a href="installation.html">Installation</a> first.
+</p>
+<p>You will learn</p>
+<ul>
+  <li><a href="#first-test">How to write your first test</a></li>
+  <li><a href="#actions">How to perform actions</a> — app lifecycle, locators, per-element</li>
+  <li><a href="#assertions">How to use auto-retrying assertions</a></li>
+  <li><a href="#isolation">How tests run in isolation</a></li>
+  <li><a href="#hooks">How to use test hooks</a></li>
+</ul>
+<h2 id="first-test">First test</h2>
+<p>
+  <code>taqwright init</code> already wrote one for you at <code>tests/example.spec.ts</code> (against the bundled demo app):
+</p>
+<div class="codeblock">
+  <div class="filename">tests/example.spec.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>import { test, expect } from 'taqwright';
+test('user can log in to the demo app', async ({ mobile }) =&gt; {
+  await mobile.getByXpath("//*[@hint='Username']").fill('emma@demoapp.com');
+  await mobile.getByXpath("//*[@hint='Password']").fill('10203040');
+  await mobile.getByUiSelector('new UiSelector().description("Login")').click();
+  await expect(mobile.getByUiSelector('new UiSelector().description("View All")')).toBeVisible();
+});</code></pre>
+</div>
+<p>Then run it (Android — see <a href="installation.html#running-example">Running the example test</a>):</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>npx taqwright test --project=android</code></pre></div>
+<p>Line-by-line:</p>
+<ul>
+  <li><code>import { test, expect } from 'taqwright'</code> — Playwright's <code>test</code> + <code>expect</code>, extended with a <code>mobile</code> fixture. Use them exactly like the Playwright ones you know.</li>
+  <li><code>async ({ mobile }) =&gt;</code> — destructure the fixture. It opens a fresh WebDriver/Appium session when the test starts and tears it down when it ends.</li>
+  <li><code>mobile.getByXpath(…)</code> / <code>getByUiSelector(…)</code> — return a lazy <code>Locator</code>; nothing touches the device until an action or assertion runs. (<code>getByUiSelector</code> is Android-only; <code>getById</code> and the rest are in <a href="#locating">Locating elements</a>.)</li>
+  <li><code>.fill('emma@demoapp.com')</code> — the action drives the device: taps the field, clears it, sends the text as real key events (so React Native / Flutter <code>onChangeText</code> handlers fire).</li>
+  <li><code>.click()</code> — auto-waits for the element to be visible <strong>and</strong> enabled before tapping. No explicit <code>waitFor</code> needed in the common case.</li>
+  <li><code>await expect(locator).toBeVisible()</code> — auto-retrying assertion: polls every 200ms until the element is visible or the timeout (default 30s) elapses.</li>
+</ul>
+<div class="callout">
+  <strong>Two assertion styles, same engine.</strong>
+  taqwright ships a Playwright-style <code>expect(locator)</code> wrapper — <code>expect(loc).toBeVisible()</code> / <code>.toHaveText()</code> / <code>.toBeChecked()</code> / … — that delegates to the auto-retrying assertion methods on the <code>Locator</code> itself (<code>loc.assertVisible()</code>, <code>loc.assertText()</code>, …). Both forms behave identically; use whichever reads better. See <a href="#assertions">Assertions</a>.
+</div>
+<h2 id="actions">Actions</h2>
+<p>
+  Actions fall into three buckets: <strong>app lifecycle</strong> (install / launch / background / deep-link), <strong>locating</strong> (the <code>getBy*</code> family), and <strong>per-element actions</strong> on the returned <code>Locator</code>.
+</p>
+<h3 id="app-lifecycle">App lifecycle</h3>
+<p>
+  Most tests don't need to call these directly — the fixture handles install + launch via <code>resetBetweenTests</code> (see <a href="#isolation">Test isolation</a>). But they're there when you need them:
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>// Install and launch
+await mobile.installApp('/path/to/app.apk');
+await mobile.launchApp('com.example.app');
+// Send to background for 5 seconds, then come back
+await mobile.backgroundApp(5);
+await mobile.activateApp('com.example.app');
+// Deep link
+await mobile.openDeepLink('myapp://product/123');
+// Android-only system back
+await mobile.goBack();
+// Tear down
+await mobile.terminateApp('com.example.app');</code></pre></div>
+<h3 id="locating">Locating elements</h3>
+<p>
+  Pick the locator strategy that matches what your app exposes. Most stable to least:
+</p>
+<table class="api">
+  <thead><tr><th>Method</th><th>What it matches</th></tr></thead>
+  <tbody>
+    <tr><td><code>getById('login_btn')</code></td><td>Accessibility id (iOS <code>name</code>) / Android <code>resource-id</code>. Same as <code>getByTestId</code>.</td></tr>
+    <tr><td><code>getByLabel('Submit')</code></td><td>Accessibility label.</td></tr>
+    <tr><td><code>getByText('Submit')</code></td><td>Visible text. Pass <code>{ exact: false }</code> for substring, or a <code>RegExp</code> for regex.</td></tr>
+    <tr><td><code>getByPlaceholder('Email')</code></td><td>Input placeholder / hint text.</td></tr>
+    <tr><td><code>getByRole('button', { name })</code></td><td>Best-effort role → widget-type mapping.</td></tr>
+    <tr><td><code>getByType('android.widget.Button')</code></td><td>Class name / XCUI element type. Use for grouping (e.g. <code>.all()</code>).</td></tr>
+    <tr><td><code>getByXpath('//*[@hint="..."]')</code></td><td>Raw XPath. Slowest; reach for last.</td></tr>
+    <tr><td><code>getByUiSelector('new UiSelector()...')</code></td><td>Android UiAutomator2 selector. Fast, expressive.</td></tr>
+    <tr><td><code>getByPredicate("type == '...'")</code></td><td>iOS NSPredicate. Fastest iOS strategy.</td></tr>
+    <tr><td><code>getByClassChain('**/X[`label == "OK"`]')</code></td><td>iOS class-chain. Hierarchical, much faster than XPath.</td></tr>
+  </tbody>
+</table>
+<p>
+  When several elements match the same locator, <strong>chain</strong> to disambiguate:
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>// Pick by position
+await mobile.getByText('Item').nth(2).click();
+await mobile.getByText('Item').first().click();
+await mobile.getByText('Item').last().click();
+// Filter
+await mobile.getByType('android.widget.LinearLayout')
+  .filter({ hasText: 'Wi-Fi' })
+  .click();
+// Scope a child find under a parent
+await mobile.getById('login_form')
+  .locator(mobile.getById('submit'))
+  .click();
+// Iterate
+for (const row of await mobile.getByType('XCUIElementTypeCell').all()) {
+  console.log(await row.getText());
+}</code></pre></div>
+<h3 id="common-actions">Common actions</h3>
+<p>
+  Here are the most popular per-element actions, called on the <code>Locator</code> a <code>getBy*</code> returns. Each auto-waits for actionability — visible, enabled, stable — so you never write a manual wait:
+</p>
+<table class="api">
+  <thead><tr><th>Action</th><th>Description</th></tr></thead>
+  <tbody>
+    <tr><td><code>click()</code> / <code>tap()</code></td><td>Tap the element. Auto-waits for visible + enabled.</td></tr>
+    <tr><td><code>fill(text)</code></td><td>Focus, clear, send the text as real key events.</td></tr>
+    <tr><td><code>clear()</code></td><td>Empty the field.</td></tr>
+    <tr><td><code>check()</code> / <code>uncheck()</code></td><td>Idempotent toggle for switches and checkboxes.</td></tr>
+    <tr><td><code>focus()</code> / <code>blur()</code></td><td>Bring focus (taps the field) / dismiss the keyboard.</td></tr>
+    <tr><td><code>press('Enter')</code></td><td>Single key. Supports <code>Enter</code> / <code>Tab</code> / <code>Backspace</code> / <code>Space</code> / arrows / nav keys.</td></tr>
+    <tr><td><code>pressSequentially(text, { delay })</code></td><td>One char at a time. Use when autocomplete needs to react.</td></tr>
+    <tr><td><code>selectOption(value)</code></td><td>Drive a native picker / spinner / date / time picker.</td></tr>
+    <tr><td><code>scrollIntoView()</code></td><td>Native scroll-to-visible if available, gesture-swipe fallback.</td></tr>
+    <tr><td><code>swipeLeft()</code> / <code>Right</code> / <code>Up</code> / <code>Down</code></td><td>Swipe inside the element's bounding box.</td></tr>
+    <tr><td><code>longPress({ duration })</code></td><td>Press-and-hold. Default 1000ms.</td></tr>
+    <tr><td><code>dragTo(target)</code></td><td>Drag onto another locator.</td></tr>
+    <tr><td><code>pinchIn()</code> / <code>pinchOut()</code></td><td>Two-finger zoom.</td></tr>
+    <tr><td><code>screenshot()</code></td><td>Element screenshot as a <code>Buffer</code>.</td></tr>
+  </tbody>
+</table>
+<h3 id="mobile-specific">Mobile-specific actions</h3>
+<p>
+  These have no direct web Playwright analogue:
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>// Hardware buttons — HOME | BACK | POWER | VOLUME_UP | VOLUME_DOWN | ENTER
+await mobile.pressButton('BACK');
+await mobile.pressButton('HOME');
+await mobile.pressButton('VOLUME_UP');
+await mobile.press('Enter');                        // a single named key, device-level
+await mobile.goBack();                              // Android back / iOS nav-bar back
+// Screen-level gestures (vs the locator-scoped ones in Common actions)
+await mobile.swipe('left');
+await mobile.scroll('down');                        // content-reveal direction
+await mobile.scroll('down', { from: { y: 0.7 }, to: { y: 0.3 } });
+await mobile.scrollIntoView(mobile.getByText('Submit'));
+await mobile.dragAndDrop({ x: 100, y: 400 }, { x: 100, y: 120 });
+await mobile.clickByPercent({ x: 0, y: 0, width: 1080, height: 2400 }, 0.5, 0.9);
+await mobile.gesture({ pointers: [/* multi-finger W3C pointer path */] });
+// Pickers — auto-detects element type
+await mobile.getByType('XCUIElementTypePickerWheel').selectOption('March');
+await mobile.getByType('XCUIElementTypeDatePicker').selectOption({ date: '2026-05-14' });
+await mobile.getByType('android.widget.Spinner').selectOption('Large');
+// Deep links / orientation / keyboard
+await mobile.openDeepLink('myapp://settings');
+await mobile.setOrientation('landscape');
+const o = await mobile.getOrientation();            // 'portrait' | 'landscape'
+await mobile.hideKeyboard();
+const up = await mobile.isKeyboardShown();
+// OS dialogs
+await mobile.acceptAlert();
+await mobile.dismissAlert();
+const msg = await mobile.getAlertText();
+// App state & lifecycle queries
+await mobile.isAppInstalled();                      // defaults to the configured bundle id
+await mobile.queryAppState();                       // not_installed | not_running | background | foreground
+const { bundleId } = await mobile.getCurrentApp();
+await mobile.backgroundApp(3);                       // send to background for 3s (-1 = indefinitely)
+// Clipboard / geolocation
+await mobile.setClipboard('hello');
+const clip = await mobile.getClipboard();
+await mobile.setLocation({ latitude: 37.422, longitude: -122.084 });
+const loc = await mobile.getLocation();
+// Permissions / network (Android-only — throw a clear error on iOS)
+await mobile.setPermission('android.permission.CAMERA', 'grant');
+await mobile.setNetworkConnection({ wifi: false, data: true, airplane: false });
+const net = await mobile.getNetworkConnection();
+// Files / logs / locale / time
+await mobile.pushFile('/sdcard/Download/in.txt', 'payload');
+const buf = await mobile.pullFile('/sdcard/Download/out.txt');
+const logs = await mobile.getDeviceLogs();          // 'logcat' | 'syslog' | 'crashlog'
+const types = await mobile.getLogTypes();
+await mobile.setLocale('en-US');                     // Android-only at runtime
+const time = await mobile.getDeviceTime();
+// Screen recording (separate from the auto-captured trace video)
+await mobile.startScreenRecording();
+const mp4 = await mobile.stopScreenRecording();
+// Device info / misc
+const size = await mobile.getScreenSize();           // { width, height }
+const png = await mobile.screenshot();               // full-screen Buffer
+const xml = await mobile.viewTree();                 // current page source
+await mobile.waitForTimeout(500);
+await mobile.pause();                                // attach the inspector mid-test (no-op if PWDEBUG=0)</code></pre></div>
+<p>
+  <code>mobile.raw</code> is the escape hatch back to the underlying WebDriver
+  <code>Client</code> if you need a command not surfaced here.
+</p>
+<h2 id="assertions">Assertions</h2>
+<h3 id="locator-assertions">Locator assertions (auto-retrying)</h3>
+<p>
+  Every assertion that operates on a <code>Locator</code> is a method on the locator itself, not a <code>expect</code> matcher. They auto-retry — polling every 200ms until the condition holds or the timeout elapses.
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>const submit = mobile.getById('Submit');
+await submit.assertVisible();
+await submit.assertEnabled();
+await submit.assertText('Submit order');
+await submit.assertContainsText('Submit');
+// State for toggles
+await mobile.getById('darkMode').assertChecked();
+// Counts (pairs with .all() / chain)
+await mobile.getByType('CartItem').assertCount(3);
+// Arbitrary attribute
+await mobile.getById('promo').assertAttribute('content-desc', /Save \d+%/);
+// Position / structure
+await mobile.getByText('Footer').assertInViewport();
+await mobile.getById('cart_count').assertEmpty();
+await mobile.getById('username').assertFocused();</code></pre></div>
+<table class="api">
+  <thead><tr><th>Method</th><th>Asserts</th></tr></thead>
+  <tbody>
+    <tr><td><code>assertVisible()</code> / <code>assertHidden()</code></td><td>Element is (or isn't) displayed.</td></tr>
+    <tr><td><code>assertEnabled()</code> / <code>assertDisabled()</code></td><td>Element is interactive.</td></tr>
+    <tr><td><code>assertChecked()</code> / <code>assertUnchecked()</code></td><td>Toggle / switch state.</td></tr>
+    <tr><td><code>assertText(s | RegExp)</code></td><td>Exact text or regex match.</td></tr>
+    <tr><td><code>assertContainsText(s)</code></td><td>Substring match.</td></tr>
+    <tr><td><code>assertValue(s | RegExp)</code></td><td>Input value match.</td></tr>
+    <tr><td><code>assertCount(n)</code></td><td>The chain currently matches exactly <code>n</code> elements.</td></tr>
+    <tr><td><code>assertAttribute(name, s | RegExp)</code></td><td>Arbitrary attribute matches.</td></tr>
+    <tr><td><code>assertEditable()</code> / <code>assertReadonly()</code></td><td>Input is (or isn't) editable.</td></tr>
+    <tr><td><code>assertFocused()</code></td><td>Element has keyboard focus.</td></tr>
+    <tr><td><code>assertAttached()</code></td><td>Element exists in the UI tree (whether or not visible).</td></tr>
+    <tr><td><code>assertEmpty()</code></td><td>No children and no text.</td></tr>
+    <tr><td><code>assertInViewport()</code></td><td>Bounding box intersects the device viewport.</td></tr>
+  </tbody>
+</table>
+<h3 id="generic-matchers">Generic matchers (<code>expect</code>)</h3>
+<p>
+  Playwright's <code>expect</code> is re-exported from <code>taqwright</code>. For <strong>plain values</strong> — strings, numbers, arrays, objects — it's Playwright's <code>expect</code> unchanged. For a <code>Locator</code> it returns taqwright's auto-retrying mobile matchers (next section).
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>import { test, expect } from 'taqwright';
+test('totals match', async ({ mobile }) =&gt; {
+  const total = await mobile.getById('total').getText();
+  expect(total).toBe('$69.99');
+  const items = await mobile.getByType('CartItem').all();
+  expect(items).toHaveLength(3);
+  const isPromoApplied = await mobile.getById('promo_active').isVisible();
+  expect(isPromoApplied).toBeTruthy();
+});</code></pre></div>
+<h3 id="expect-extend">Using <code>expect(locator)</code></h3>
+<p>
+  No setup, no <code>expect.extend</code>. <code>expect</code> imported from <code>taqwright</code> returns taqwright's mobile matchers when you pass a <code>Locator</code>, and falls through to Playwright's real <code>expect</code> for plain values. Each locator matcher just delegates to the matching auto-retrying <a href="#locator-assertions"><code>assert*</code></a> method:
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>import { test, expect } from 'taqwright';
+test('cart', async ({ mobile }) =&gt; {
+  await expect(mobile.getById('VIEW CART')).toBeVisible();
+  await expect(mobile.getByText('Total')).toContainText('$69.99');
+  await expect(mobile.getByType('CartItem')).toHaveCount(3);
+  await expect(mobile.getById('darkMode')).toBeChecked();
+  // plain values still use Playwright's expect, unchanged
+  const total = await mobile.getById('total').getText();
+  expect(total).toBe('$69.99');
+});</code></pre></div>
+<p>
+  Here are the most popular locator matchers. Each maps 1:1 to the auto-retrying <a href="#locator-assertions"><code>assert*</code></a> method of the same meaning:
+</p>
+<table class="api">
+  <thead><tr><th>Assertion</th><th>Description</th></tr></thead>
+  <tbody>
+    <tr><td><code>expect(locator).toBeVisible()</code></td><td>Element is visible</td></tr>
+    <tr><td><code>expect(locator).toBeHidden()</code></td><td>Element is hidden / not displayed</td></tr>
+    <tr><td><code>expect(locator).toBeEnabled()</code></td><td>Control is enabled</td></tr>
+    <tr><td><code>expect(locator).toBeDisabled()</code></td><td>Control is disabled</td></tr>
+    <tr><td><code>expect(locator).toBeChecked()</code></td><td>Checkbox / switch is checked</td></tr>
+    <tr><td><code>expect(locator).toBeEditable()</code></td><td>Input is editable</td></tr>
+    <tr><td><code>expect(locator).toBeFocused()</code></td><td>Element has keyboard focus</td></tr>
+    <tr><td><code>expect(locator).toBeAttached()</code></td><td>Element exists in the UI tree</td></tr>
+    <tr><td><code>expect(locator).toBeInViewport()</code></td><td>Element intersects the device viewport</td></tr>
+    <tr><td><code>expect(locator).toBeEmpty()</code></td><td>Element has no children and no text</td></tr>
+    <tr><td><code>expect(locator).toHaveText(s | RegExp)</code></td><td>Element matches text</td></tr>
+    <tr><td><code>expect(locator).toContainText(s)</code></td><td>Element contains text</td></tr>
+    <tr><td><code>expect(locator).toHaveValue(s | RegExp)</code></td><td>Input element has value</td></tr>
+    <tr><td><code>expect(locator).toHaveCount(n)</code></td><td>The chain matches exactly <code>n</code> elements</td></tr>
+    <tr><td><code>expect(locator).toHaveAttribute(name, s | RegExp)</code></td><td>Element has attribute</td></tr>
+  </tbody>
+</table>
+<p>
+  The paired matchers also take a <code>.not</code> form — <code>.not.toBeVisible()</code>, <code>.not.toBeEnabled()</code>, <code>.not.toBeChecked()</code>, <code>.not.toBeEditable()</code>. Web-only Playwright matchers (<code>toHaveScreenshot</code>, <code>toHaveCSS</code>, <code>toHaveTitle</code>, …) throw a clear error rather than misfire. It's a thin standalone wrapper (<em>not</em> <code>expect.extend</code>), so Playwright's value matchers, <code>expect.soft</code>, <code>expect.poll</code> and <code>expect.configure</code> are all unchanged.
+</p>
+<p>
+  To poll an arbitrary predicate (not a <code>Locator</code>), <code>expect.poll</code> works exactly as in Playwright:
+</p>
+<div class="codeblock"><pre class="code"><button class="copy">Copy</button><code>await expect
+  .poll(() =&gt; mobile.getById('VIEW CART').isVisible(), { timeout: 10_000 })
+  .toBe(true);</code></pre></div>
+<h2 id="isolation">Test isolation</h2>
+<p>
+  Each worker holds one WebDriver / Appium session. By default that session stays open across tests in the same worker — fast, but tests can leak state.
+</p>
+<p>
+  Set <code>resetBetweenTests: true</code> in your config to get a clean app between tests:
+</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({
+  projects: [{
+    name: 'android-emulator',
+    use: {
+      platform: Platform.ANDROID,
+      device: { provider: 'emulator', name: 'Pixel_7_API_34' },
+      buildPath: './app/build/outputs/apk/debug/app-debug.apk',
+      appBundleId: 'com.example.app',
+      resetBetweenTests: true,
+    },
+  }],
+});</code></pre>
+</div>
+<p>
+  When <code>resetBetweenTests</code> is <code>true</code>, the <code>mobile</code> fixture <strong>terminates → uninstalls → re-installs → activates</strong> the app between every test. Both <code>buildPath</code> and <code>appBundleId</code> are required — TypeScript will enforce that.
+</p>
+<h2 id="hooks">Hooks</h2>
+<p>
+  Inherited from Playwright unchanged: <code>test.describe</code>, <code>test.beforeEach</code>, <code>test.afterEach</code>, <code>test.beforeAll</code>, <code>test.afterAll</code>.
+</p>
+<div class="codeblock">
+  <div class="filename">tests/cart.spec.ts</div>
+  <pre class="code"><button class="copy">Copy</button><code>import { test } from 'taqwright';
+test.describe('Cart', () =&gt; {
+  test.beforeEach(async ({ mobile }) =&gt; {
+    await mobile.getById('Username').fill('emma@demoapp.com');
+    await mobile.getById('Password').fill('10203040');
+    await mobile.getById('Login').click();
+  });
+  test('add to cart', async ({ mobile }) =&gt; {
+    await mobile.getById('View All').click();
+    await mobile.getById('Search dresses...').fill('boho');
+    await mobile.getById('Boho Wrap Dress\n$69.99').click();
+    await mobile.getById('Add to Cart').click();
+    await mobile.getById('VIEW CART').assertVisible();
+  });
+  test('remove from cart', async ({ mobile }) =&gt; {
+    /* ... */
+  });
+});</code></pre>
+</div>
+<div class="callout">
+  <strong>Tip — keep <code>beforeEach</code> light.</strong>
+  Every action there runs before every test. If your login flow takes 8s, three tests cost 24s of repeated work. Combine with <code>resetBetweenTests: false</code> (default) and a single <code>test.beforeAll</code> if the tests don't need fresh app state.
+</div>
+<div class="pager">
+  <a href="installation.html">
+    <div class="label">← Previous</div>
+    <div class="title">Installation</div>
+  </a>
+  <a class="next" href="generating-tests.html">
+    <div class="label">Next →</div>
+    <div class="title">Generating tests</div>
+  </a>
+</div>
+</main>
+<aside class="onthispage">
+  <h4>On this page</h4>
+  <ol>
+    <li><a href="#introduction">Introduction</a></li>
+    <li><a href="#first-test">First test</a></li>
+    <li><a href="#actions">Actions</a>
+      <ol class="sub">
+        <li><a href="#app-lifecycle">App lifecycle</a></li>
+        <li><a href="#locating">Locating elements</a></li>
+        <li><a href="#common-actions">Common actions</a></li>
+        <li><a href="#mobile-specific">Mobile-specific</a></li>
+      </ol>
+    </li>
+    <li><a href="#assertions">Assertions</a>
+      <ol class="sub">
+        <li><a href="#locator-assertions">Locator assertions</a></li>
+        <li><a href="#generic-matchers">Generic matchers</a></li>
+        <li><a href="#expect-extend">Using <code>expect</code></a></li>
+      </ol>
+    </li>
+    <li><a href="#isolation">Test isolation</a></li>
+    <li><a href="#hooks">Hooks</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/doctor.d.ts ADDED Viewed

@@ -0,0 +1,33 @@
+export { normalizeSysImagePath } from './setup/avd.js';
+export type DoctorStatus = 'ok' | 'warn' | 'error';
+export interface DoctorCheck {
+    name: string;
+    status: DoctorStatus;
+    detail?: string;
+}
+export declare function runDoctorChecks(): Promise<DoctorCheck[]>;
+export type AppiumSupportLevel = 'recommended' | 'best-effort' | 'unsupported';
+export declare function classifyAppiumVersion(version: string): AppiumSupportLevel;
+export type JdkLevel = 'ok' | 'too-old' | 'unknown';
+export declare function classifyJdkVersion(version: string): JdkLevel;
+export interface AndroidToolchainStatus {
+    jdk: JdkLevel | 'missing';
+    jdkVersion?: string;
+    sdk: boolean;
+    appium: AppiumSupportLevel | 'missing';
+    appiumVersion?: string;
+    uiautomator2: boolean;
+    avd: boolean;
+    avdNames: string[];
+    ready: boolean;
+}
+export declare function androidToolchainReady(s: {
+    jdk: JdkLevel | 'missing';
+    sdk: boolean;
+    appium: AppiumSupportLevel | 'missing';
+    uiautomator2: boolean;
+}): boolean;
+export declare function listAvds(): Promise<string[]>;
+export declare function detectAndroidToolchain(): Promise<AndroidToolchainStatus>;
+export declare function isAppiumVersionSupported(version: string): boolean;
+export declare function isNodeVersionSupported(version: string): boolean;