@irsprs/mobwright 0.1.0

package/README.md

@@ -0,0 +1,776 @@
+<div align="center">
+  <img src="img/mobwright-logo.png" alt="Mobwright" width="280" />
+  <br />
+  <br />
+
+  <p>
+    <strong>Playwright-style mobile E2E testing — powered by AI</strong>
+  </p>
+
+  <p>
+    Write mobile tests that feel like Playwright.<br />
+    Run them on Android emulators & iOS simulators through Appium.<br />
+    Let AI resolve locators when you don't want to dig through XML.
+  </p>
+
+  <br />
+
+  <p>
+    <a href="#-quick-start"><img src="https://img.shields.io/badge/-Quick%20Start-6C63FF?style=for-the-badge&logoColor=white" alt="Quick Start" /></a>
+    <a href="#-api-reference"><img src="https://img.shields.io/badge/-API%20Docs-00D4AA?style=for-the-badge&logoColor=white" alt="API Docs" /></a>
+    <a href="#-ai-providers"><img src="https://img.shields.io/badge/-AI%20Providers-FF6B6B?style=for-the-badge&logoColor=white" alt="AI Providers" /></a>
+    <a href="#-examples"><img src="https://img.shields.io/badge/-Examples-FFA94D?style=for-the-badge&logoColor=white" alt="Examples" /></a>
+  </p>
+
+  <br />
+
+  <p>
+    <img src="https://img.shields.io/badge/status-pre--0.1-orange?style=flat-square" alt="Status" />
+    <img src="https://img.shields.io/badge/node-%3E%3D18.18-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node" />
+    <img src="https://img.shields.io/badge/typescript-5.4+-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
+    <img src="https://img.shields.io/badge/playwright-%3E%3D1.40-2EAD33?style=flat-square&logo=playwright&logoColor=white" alt="Playwright" />
+    <img src="https://img.shields.io/badge/appium-powered-662D91?style=flat-square&logo=appium&logoColor=white" alt="Appium" />
+    <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License" />
+  </p>
+</div>
+
+---
+
+> ⚠️ **Pre-1.0 — here be dragons.** The Locator API and AI provider abstraction are stable. `device.ai()`, CLI commands, and custom matchers are shipped and validated end-to-end. Some sharp edges remain. Pin your version until 1.0.
+
+<br />
+
+## ✨ Why Mobwright?
+
+| Pain Point | Mobwright Solution |
+|---|---|
+| 🤯 Appium's verbose API | Playwright-style `.locator()`, `.tap()`, `.fill()` |
+| 😵 Flaky element lookups | Built-in **auto-wait** — polls until visible + enabled |
+| 🔎 Hunting through XML trees | **`device.ai('description')`** — describe elements in plain English |
+| 🧩 Separate Android/iOS test files | Unified selector syntax, write once for both platforms |
+| ⚙️ Complex session management | One session per test, automatic setup & teardown |
+| 🥱 Setting up a new project | `npx mobwright init` scaffolds everything in seconds |
+
+
+<br />
+
+## 📋 Prerequisites
+
+Before using Mobwright, ensure you have the following installed:
+
+| Requirement | Version | Purpose |
+|---|---|---|
+| **Node.js** | ≥ 18.18 | Runtime |
+| **pnpm** | ≥ 8.x | Package manager (recommended) |
+| **Appium** | ≥ 2.x | Mobile automation server |
+| **Android SDK** | Latest | Android emulator & ADB |
+| **Xcode** | ≥ 15 | iOS simulator (macOS only) |
+
+### Appium Drivers
+
+```bash
+# Install Appium globally
+npm install -g appium
+
+# Install platform drivers
+appium driver install uiautomator2   # Android
+appium driver install xcuitest       # iOS
+```
+
+> 💡 **Tip:** After install, run `npx mobwright doctor` to verify everything's wired up correctly.
+
+<br />
+
+## 🚀 Quick Start
+
+### 1. Scaffold a new project
+
+```bash
+npx mobwright init my-mobile-tests
+cd my-mobile-tests
+```
+
+The init wizard asks which platforms (Android, iOS, both), whether to enable AI, and whether to install dependencies. Non-interactive mode is supported too:
+
+```bash
+npx mobwright init my-tests --platforms=android,ios --ai=deepseek --yes
+```
+
+### 2. Configure environment
+
+`mobwright init` generates a `.env.example` for you. Copy and fill in:
+
+```bash
+cp .env.example .env
+```
+
+```ini
+# ── Android ──────────────────────────────────────────
+MOBWRIGHT_APP_PATH=/absolute/path/to/your/app.apk
+MOBWRIGHT_ANDROID_AVD=Pixel_6_API_34
+# MOBWRIGHT_ANDROID_APP_PACKAGE=com.example
+# MOBWRIGHT_ANDROID_APP_ACTIVITY=com.example.MainActivity
+
+# ── iOS ──────────────────────────────────────────────
+MOBWRIGHT_IOS_DEVICE=iPhone 15
+MOBWRIGHT_IOS_BUNDLE_ID=com.example.app
+# MOBWRIGHT_IOS_APP_PATH=/absolute/path/to/My.app
+# MOBWRIGHT_IOS_UDID=...
+# MOBWRIGHT_IOS_PLATFORM_VERSION=17.5
+
+# ── AI (optional) ───────────────────────────────────
+# MOBWRIGHT_AI_PROVIDER=deepseek
+# MOBWRIGHT_AI_API_KEY=sk-...
+# MOBWRIGHT_AI_MODEL=deepseek-chat
+# MOBWRIGHT_AI_BASE_URL=https://api.deepseek.com
+```
+
+### 3. Verify your environment
+
+```bash
+npx mobwright doctor
+```
+
+You'll get a colorized summary of what's working and what's missing. Fix anything red before continuing.
+
+### 4. Write your first test
+
+```typescript
+import { test, expect } from 'mobwright';
+
+test('app launches and shows welcome screen', async ({ device }) => {
+  const welcomeText = device.locator('~welcomeMessage');
+
+  // toBeVisible auto-retries up to 5s
+  await expect(welcomeText).toBeVisible();
+  await expect(welcomeText).toHaveText(/welcome/i);
+
+  // Tap a button
+  await device.locator('~getStartedButton').tap();
+
+  // Fill an input
+  await device.locator('#emailInput').fill('user@example.com');
+
+  // Or describe elements in English — AI finds the selector for you
+  await device.ai('the blue Continue button at the bottom').tap();
+});
+```
+
+### 5. Start Appium & run
+
+```bash
+# Terminal 1: Start Appium server
+appium
+
+# Terminal 2: Run tests via mobwright (recommended)
+npx mobwright test --project android
+npx mobwright test --project ios
+
+# Or use playwright directly — both work
+npx playwright test --project android
+```
+
+`mobwright test` is a thin wrapper that pre-flights the Appium connection and forwards everything else to `playwright test`. Every Playwright flag (`--grep`, `--ui`, `--workers`, etc.) works.
+
+<br />
+
+## 🛠️ CLI
+
+Mobwright ships three commands:
+
+| Command | What it does |
+|---|---|
+| `mobwright init [dir]` | Scaffold a new project with config, env example, and sample tests |
+| `mobwright test` | Run your test suite (pre-flight Appium check + forwards to `playwright test`) |
+| `mobwright doctor` | Check your environment for required tools, drivers, and env vars |
+
+Run `mobwright help` for full flag reference.
+
+<br />
+
+## 🎯 Selector Syntax
+
+Mobwright provides a concise selector syntax that works across both platforms:
+
+| Prefix | Strategy | Example | Android Maps To | iOS Maps To |
+|---|---|---|---|---|
+| `~` | Accessibility ID | `~loginButton` | `content-desc` | `name` |
+| `#` | Resource ID | `#emailInput` | `resource-id` (ends-with) | `name` |
+| `//` | XPath | `//android.widget.Button` | Raw XPath | Raw XPath |
+| *(none)* | Accessibility ID | `loginButton` | `content-desc` | `name` |
+
+> **💡 Tip:** Prefer `~accessibilityId` selectors — they're the most reliable across platforms and are the recommended approach for cross-platform tests.
+
+<br />
+
+## 📖 API Reference
+
+### `device` — The Test Fixture
+
+Every test receives a `device` object that represents the connected mobile device.
+
+```typescript
+import { test, expect } from 'mobwright';
+
+test('example', async ({ device }) => {
+  // device is ready — Appium session is active
+});
+```
+
+| Property | Type | Description |
+|---|---|---|
+| `device.platform` | `Platform` | Current platform (`'android'` or `'ios'`) |
+| `device.project` | `string` | Project name from Playwright config |
+| `device.aiProvider` | `AIProvider \| undefined` | Attached AI provider (if configured) |
+
+### `device.locator(selector, options?)`
+
+Create a lazy reference to a UI element. **Does not query the device** until an action is called.
+
+```typescript
+const button = device.locator('~submitButton');
+const input = device.locator('#emailField');
+const element = device.locator('//android.widget.TextView[@text="Hello"]');
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `number` | `5000` | Max wait time in ms for actions |
+
+### `device.getByText(text, options?)`
+
+Locate an element by its visible text or label.
+
+```typescript
+const heading = device.getByText('Welcome to the App');
+await heading.waitFor();
+```
+
+### `device.ai(description, options?)`
+
+Natural-language locator. AI resolves the description to a concrete selector on first action, then caches the result for the rest of the test.
+
+```typescript
+// Same surface as Locator — tap, fill, getText, isVisible, waitFor
+await device.ai('the blue Continue button').tap();
+await device.ai('the email input field').fill('me@example.com');
+await device.ai('the welcome banner').waitFor();
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `number` | `5000` | Max wait time in ms for actions |
+| `minConfidence` | `number` | `0.5` | Minimum confidence; throws below this |
+| `treeCharBudget` | `number` | `12000` | Max chars of accessibility tree sent to AI |
+
+Requires `MOBWRIGHT_AI_PROVIDER` and `MOBWRIGHT_AI_API_KEY` set. Throws `AIError` if not configured.
+
+### `device.screenshot()`
+
+Take a screenshot. Returns raw PNG bytes as a `Buffer`.
+
+```typescript
+const png = await device.screenshot();
+```
+
+### `device.getPageSource()`
+
+Get the current accessibility tree as an XML string. Useful for debugging and AI features.
+
+```typescript
+const xml = await device.getPageSource();
+console.log(xml);
+```
+
+---
+
+### `Locator` — Element Actions
+
+All locator actions **auto-wait** for the element to be present, visible, and enabled before executing.
+
+#### Core Actions
+
+| Method | Returns | Description |
+|---|---|---|
+| `.tap()` | `Promise<void>` | Tap (click) the element |
+| `.fill(text)` | `Promise<void>` | Clear and type text into the element |
+| `.getText()` | `Promise<string>` | Get the visible text content |
+| `.isVisible()` | `Promise<boolean>` | Check visibility instantly (no waiting) |
+| `.isEnabled()` | `Promise<boolean>` | Check enabled state instantly (no waiting) |
+| `.waitFor(options?)` | `Promise<void>` | Wait for element to become visible |
+| `.tapAndHold(options?)` | `Promise<void>` | Long-press the element |
+
+#### Swipe Gestures
+
+```typescript
+// Swipe within the element bounds
+await element.swipeLeft();
+await element.swipeRight();
+await element.swipeUp();
+await element.swipeDown();
+
+// With options
+await element.swipeLeft({ duration: 600, distance: 0.8 });
+```
+
+| Method | Options | Description |
+|---|---|---|
+| `.swipeLeft(opts?)` | `duration`, `distance` | Swipe left within bounds |
+| `.swipeRight(opts?)` | `duration`, `distance` | Swipe right within bounds |
+| `.swipeUp(opts?)` | `duration`, `distance` | Swipe up within bounds |
+| `.swipeDown(opts?)` | `duration`, `distance` | Swipe down within bounds |
+
+#### Scroll Gestures
+
+Slower and longer than swipe — ideal for scrolling through lists and pages.
+
+```typescript
+await scrollableList.scrollDown();
+await scrollableList.scrollUp({ duration: 1000, distance: 0.9 });
+```
+
+| Method | Options | Description |
+|---|---|---|
+| `.scrollUp(opts?)` | `duration`, `distance` | Scroll up inside a container |
+| `.scrollDown(opts?)` | `duration`, `distance` | Scroll down inside a container |
+
+---
+
+### `expect` — Auto-retrying Matchers
+
+Mobwright extends Playwright's `expect` with mobile-aware matchers. Each one auto-retries until the assertion passes or the timeout elapses.
+
+```typescript
+import { test, expect } from 'mobwright';
+
+test('login form', async ({ device }) => {
+  await expect(device.locator('~loginBtn')).toBeVisible();
+  await expect(device.locator('~welcomeText')).toHaveText('Welcome!');
+  await expect(device.locator('~submit')).toBeEnabled();
+
+  // Also works with AI locators
+  await expect(device.ai('the success message')).toBeVisible();
+});
+```
+
+| Matcher | Auto-retries | Description |
+|---|:---:|---|
+| `toBeVisible(opts?)` | ✅ | Element is present and displayed |
+| `toHaveText(text \| regex, opts?)` | ✅ | Element's visible text matches |
+| `toBeEnabled(opts?)` | ✅ | Element is enabled (interactable) |
+
+All standard Playwright matchers (`toBe`, `toEqual`, `toThrow`, etc.) still work normally. Negation is supported: `expect(locator).not.toBeVisible()`.
+
+<br />
+
+## 🤖 AI Providers
+
+Mobwright supports **pluggable AI providers** for intelligent locator resolution — describe an element in natural language and let the AI find the right selector from the accessibility tree.
+
+### Supported Providers
+
+| Provider | Default Model | Approx Cost / Call |
+|---|---|---|
+| **Anthropic** | `claude-haiku-4-5-20251001` | ~$0.001 |
+| **OpenAI** | `gpt-4o-mini` | ~$0.005 |
+| **DeepSeek** | `deepseek-chat` | ~$0.0005 |
+
+> 💰 **Cost note:** DeepSeek is ~10× cheaper than OpenAI for locator resolution with comparable quality. It's the recommended default for CI usage.
+
+### Configuration
+
+Set these environment variables to enable AI features:
+
+```ini
+MOBWRIGHT_AI_PROVIDER=deepseek          # 'anthropic' | 'openai' | 'deepseek'
+MOBWRIGHT_AI_API_KEY=sk-your-key-here
+MOBWRIGHT_AI_MODEL=deepseek-chat        # Optional: override default model
+MOBWRIGHT_AI_BASE_URL=https://api.deepseek.com  # Optional: custom endpoint
+```
+
+### Using AI in Tests
+
+The recommended API is `device.ai()` — lazy resolution with caching and confidence gating:
+
+```typescript
+test('checkout with AI locators', async ({ device }) => {
+  await device.ai('the blue Continue button').tap();
+  await device.ai('the credit card number field').fill('4242424242424242');
+  await device.ai('the green Pay button').tap();
+});
+```
+
+### Programmatic Usage (Low-level)
+
+You can also use the provider directly via `device.aiProvider`:
+
+```typescript
+import { createProvider } from 'mobwright';
+
+const provider = createProvider({
+  provider: 'deepseek',
+  model: 'deepseek-chat',
+  apiKey: process.env.DEEPSEEK_API_KEY!,
+});
+
+const result = await provider.resolveLocator({
+  description: 'the login button on the welcome screen',
+  accessibilityTree: xmlSource,
+  platform: Platform.ANDROID,
+});
+
+console.log(result);
+// {
+//   selector: 'loginButton',
+//   strategy: 'accessibility-id',
+//   confidence: 0.95,
+//   rationale: 'Found element with content-desc="loginButton"...'
+// }
+```
+
+### AI Provider Interface
+
+Implement your own provider by satisfying the `AIProvider` interface:
+
+```typescript
+interface AIProvider {
+  readonly name: string;
+  resolveLocator(input: ResolveLocatorInput): Promise<ResolveLocatorResult>;
+}
+
+interface ResolveLocatorInput {
+  description: string;           // Natural-language element description
+  accessibilityTree: string;     // XML page source
+  screenshot?: Buffer;           // Optional screenshot for vision models
+  platform: Platform;            // 'android' | 'ios'
+}
+
+interface ResolveLocatorResult {
+  selector: string;              // e.g. 'loginButton', 'email', '//xpath'
+  strategy: SelectorStrategy;    // 'accessibility-id' | 'id' | 'xpath' | 'text'
+  confidence: number;            // 0..1 — <0.5 is treated as a miss
+  rationale?: string;            // Free-text explanation for debugging
+}
+```
+
+<br />
+
+## 📂 Project Structure
+
+```
+mobwright/
+├── src/
+│   ├── index.ts              # Public API exports
+│   ├── config.ts             # defineConfig() helper
+│   ├── types.ts              # Core type definitions
+│   ├── ai/                   # AI provider layer
+│   │   ├── provider.ts       #   AIProvider interface
+│   │   ├── types.ts          #   Input/output types
+│   │   ├── factory.ts        #   createProvider() factory
+│   │   ├── anthropic.ts      #   Anthropic (Claude) provider
+│   │   ├── openai.ts         #   OpenAI-compatible provider
+│   │   ├── deepseek.ts       #   DeepSeek provider
+│   │   ├── prompts.ts        #   Shared prompt templates
+│   │   └── errors.ts         #   AI-specific error classes
+│   ├── appium/               # Appium session & capabilities
+│   │   ├── capabilities.ts   #   W3C capability builder
+│   │   ├── session.ts        #   Session create/destroy
+│   │   └── ios-utils.ts      #   iOS-specific utilities
+│   ├── device/               # Device & Locator core
+│   │   ├── device.ts         #   Device class (test fixture)
+│   │   ├── locator.ts        #   Locator class (auto-wait, gestures)
+│   │   ├── ai-locator.ts     #   AILocator class (device.ai)
+│   │   ├── tree.ts           #   Accessibility tree cleanup
+│   │   └── selectors.ts      #   Selector parsing & conversion
+│   ├── fixtures/             # Playwright fixture integration
+│   │   └── device.ts         #   test.extend<{ device }>
+│   ├── expect/               # Custom matchers
+│   │   └── matchers.ts       #   toBeVisible, toHaveText, toBeEnabled
+│   ├── cli/                  # CLI commands
+│   │   ├── index.ts          #   Entry point
+│   │   ├── doctor.ts         #   Environment health check
+│   │   ├── init.ts           #   Project scaffold
+│   │   ├── test.ts           #   Test runner wrapper
+│   │   └── templates.ts      #   Generated file templates
+│   └── utils/                # Shared utilities
+│       └── retry.ts          #   pollUntil helper
+├── examples/
+│   └── basic/                # Working example project
+│       ├── playwright.config.ts
+│       ├── tests/
+│       │   ├── android/      #   Android-specific tests
+│       │   ├── ios/          #   iOS-specific tests
+│       │   └── shared/       #   Cross-platform tests
+│       └── .env.example
+├── tests/                    # Library unit tests (Vitest)
+│   ├── unit/
+│   └── integration/
+└── package.json
+```
+
+<br />
+
+## 🧪 Examples
+
+### Basic Onboarding Flow
+
+```typescript
+import { test, expect } from 'mobwright';
+
+test('walk through onboarding and get started', async ({ device }) => {
+  const forwardButton = device.locator('~forwardButton');
+
+  // Tap through 3 onboarding pages
+  for (let i = 0; i < 3; i++) {
+    await forwardButton.tap();
+  }
+
+  // Verify "Get Started" is visible, then tap
+  const getStarted = device.locator('~getStartedButton');
+  await expect(getStarted).toBeVisible();
+  await getStarted.tap();
+
+  // Confirm we left onboarding
+  await expect(forwardButton).not.toBeVisible();
+});
+```
+
+### Swipe Through a Carousel
+
+```typescript
+test('swipe through product carousel', async ({ device }) => {
+  const carousel = device.locator('//android.view.View[@scrollable="true"]');
+  await carousel.waitFor({ timeout: 30_000 });
+
+  for (let i = 0; i < 3; i++) {
+    await carousel.swipeLeft();
+  }
+
+  const lastPage = device.getByText('Start Shopping');
+  await expect(lastPage).toBeVisible();
+});
+```
+
+### Login Flow
+
+```typescript
+test('login with email and password', async ({ device }) => {
+  // Navigate to login
+  await device.locator('~loginButton').tap();
+
+  // Fill credentials
+  await device.locator('#emailInput').fill('user@example.com');
+  await device.locator('#passwordInput').fill('SecurePass123');
+
+  // Submit
+  await device.locator('~submitButton').tap();
+
+  // Verify success — toBeVisible auto-retries up to 15s
+  const dashboard = device.getByText('Dashboard');
+  await expect(dashboard).toBeVisible({ timeout: 15_000 });
+});
+```
+
+### AI-Powered Test (the headline feature)
+
+```typescript
+test('checkout via natural language', async ({ device }) => {
+  if (!device.aiProvider) {
+    test.skip(true, 'AI not configured');
+    return;
+  }
+
+  // Let AI find each element from a description
+  await device.ai('the Continue button on the onboarding screen').tap();
+  await device.ai('the search input field').fill('Wikipedia');
+  await device.ai('the first search result').tap();
+
+  // Mix and match with regular locators
+  await expect(device.locator('~articleTitle')).toBeVisible();
+});
+```
+
+<br />
+
+## 🔧 Running the Example Project
+
+The `examples/basic/` directory contains a fully working example.
+
+```bash
+# 1. Clone & install
+git clone https://gitlab.com/automation-repository/mobwright-at.git
+cd mobwright-at
+pnpm install
+
+# 2. Configure your devices
+cp examples/basic/.env.example examples/basic/.env
+# Edit examples/basic/.env with your device & app paths
+
+# 3. Start Appium
+appium
+
+# 4. Run tests from the example directory
+cd examples/basic
+pnpm test --project android --grep '@initial\.test'
+pnpm test --project ios --grep '@initial\.test'
+
+# Or from the monorepo root
+pnpm --filter mobwright-basic-example test --project android
+pnpm --filter mobwright-basic-example test --project ios
+```
+
+<br />
+
+## ⚙️ Configuration Reference
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| **Android** | | |
+| `MOBWRIGHT_APP_PATH` | ✅ | Absolute path to `.apk` file |
+| `MOBWRIGHT_ANDROID_AVD` | ✅ | Emulator AVD name |
+| `MOBWRIGHT_ANDROID_APP_PACKAGE` | | Override app package |
+| `MOBWRIGHT_ANDROID_APP_ACTIVITY` | | Override launcher activity |
+| **iOS** | | |
+| `MOBWRIGHT_IOS_DEVICE` | | Simulator name (default: `iPhone 15`) |
+| `MOBWRIGHT_IOS_BUNDLE_ID` | ⚠️ | Bundle ID (required if no app path) |
+| `MOBWRIGHT_IOS_APP_PATH` | ⚠️ | Path to `.app` bundle (required if not installed) |
+| `MOBWRIGHT_IOS_UDID` | | Simulator UDID for faster matching |
+| `MOBWRIGHT_IOS_PLATFORM_VERSION` | | e.g. `17.5` |
+| **AI** | | |
+| `MOBWRIGHT_AI_PROVIDER` | | `anthropic`, `openai`, or `deepseek` |
+| `MOBWRIGHT_AI_API_KEY` | | Provider API key |
+| `MOBWRIGHT_AI_MODEL` | | Override default model |
+| `MOBWRIGHT_AI_BASE_URL` | | Custom API endpoint |
+| **Appium** | | |
+| `MOBWRIGHT_APPIUM_PORT` | | Custom Appium port (default: `4723`) |
+
+### `defineConfig()` — Type-Safe Configuration
+
+```typescript
+import { defineConfig, Platform } from 'mobwright';
+
+export default defineConfig({
+  actionTimeout: 10_000,
+  projects: [
+    {
+      name: 'android',
+      use: {
+        platform: Platform.ANDROID,
+        device: { provider: 'emulator', name: 'Pixel_6_API_34' },
+        buildPath: './app-debug.apk',
+      },
+    },
+    {
+      name: 'ios',
+      use: {
+        platform: Platform.IOS,
+        device: { provider: 'simulator', name: 'iPhone 15' },
+        buildPath: './MyApp.app',
+        bundleId: 'com.example.myapp',
+      },
+    },
+  ],
+  ai: {
+    provider: 'deepseek',
+    model: 'deepseek-chat',
+    apiKey: process.env.DEEPSEEK_API_KEY!,
+  },
+});
+```
+
+<br />
+
+## ⚡ Parallelism
+
+| Strategy | Supported | Notes |
+|---|:---:|---|
+| Serial (1 worker) | ✅ v0.1 | Stable on both Android and iOS |
+| iOS multi-simulator parallel | ✅ v0.1 | Multiple booted simulators + `workers: N` works today |
+| Android multi-emulator parallel | 🔜 v0.2 | Needs worker→device routing |
+| CI job-level parallelism | ✅ | Parallelize across machines |
+| Cloud farms (BrowserStack) | 🔜 v0.2 | Native parallelism |
+
+### Why iOS but not Android?
+
+iOS simulator instances are fully isolated — each has its own UDID, filesystem, UI thread, and WebDriverAgent. Multiple Appium sessions can run in parallel without stepping on each other.
+
+Android UiAutomator2 hooks the OS UI thread, and only one instrumentation can exist per device. Running `workers: 2` against a single emulator crashes. Multi-emulator parallel (with worker→device routing) is on the v0.2 roadmap.
+
+<br />
+
+## 🗺️ Roadmap
+
+| Feature | Status |
+|---|---|
+| Playwright-style API (`locator`, `tap`, `fill`, `getText`) | ✅ Shipped |
+| Auto-wait (poll until actionable) | ✅ Shipped |
+| Android + iOS support | ✅ Shipped |
+| Unified selector syntax | ✅ Shipped |
+| Swipe & scroll gestures | ✅ Shipped |
+| Multi-provider AI abstraction (Anthropic, OpenAI, DeepSeek) | ✅ Shipped |
+| `device.ai('description').tap()` — NL locators | ✅ Shipped |
+| Custom matchers (`toBeVisible`, `toHaveText`, `toBeEnabled`) | ✅ Shipped |
+| iOS multi-simulator parallelism | ✅ Shipped |
+| CLI (`mobwright init`, `test`, `doctor`) | ✅ Shipped |
+| Smart iOS app install detection | ✅ Shipped |
+| Self-healing locators | 🔜 v0.2 |
+| Android multi-emulator parallelism | 🔜 v0.2 |
+| BrowserStack / LambdaTest / Sauce Labs | 🔜 v0.2 |
+| Real-device support | 🔜 v0.2 |
+| AI failure analysis & reports | 🔜 v0.3 |
+| Vision-based assertions (`toLookLike`) | 🔜 v0.3 |
+| Terminal recorder (`mobwright record`) | 🔜 v0.4 |
+| Browser-based codegen inspector | 🔜 v0.5 |
+
+<br />
+
+## 🧑‍💻 Development
+
+```bash
+# Clone
+git clone https://gitlab.com/automation-repository/mobwright-at.git
+cd mobwright-at
+
+# Install dependencies
+pnpm install
+
+# Build the library
+pnpm build
+
+# Watch mode (rebuilds on changes)
+pnpm dev
+
+# Run unit tests (Vitest)
+pnpm test
+
+# Run unit tests in watch mode
+pnpm test:watch
+
+# Lint & format
+pnpm lint
+pnpm format
+
+# Type check
+pnpm typecheck
+```
+
+<br />
+
+## 📄 License
+
+[MIT](LICENSE) © Irsyad Prasetyo
+
+---
+
+<div align="center">
+  <br />
+  <p>
+    <sub>Built with ❤️ for QA engineers who deserve better mobile testing tools.</sub>
+  </p>
+</div>