@mobilewright/test 0.0.46 → 0.0.47

package/README.md

@@ -1,6 +1,6 @@
 # Mobilewright
 
-[![npm](https://img.shields.io/npm/dw/mobilewright?style=flat-square&label=npm%20downloads)](https://www.npmjs.com/package/mobilewright)
+[![npm](https://img.shields.io/npm/dm/mobilewright?style=flat-square&label=npm%20downloads)](https://www.npmjs.com/package/mobilewright)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
@@ -8,7 +8,7 @@ Framework for mobile device automation, inspired by Playwright's architecture an
 
 **Mobilewright** targets iOS and Android devices, simulators, and emulators through a clean, auto-waiting API built on top of [mobilecli](https://github.com/mobile-next/mobilecli).
 
-[Get Started](#quick-start) · [API Docs](#api-reference) · [Roadmap](ROADMAP.md) · [Cloud (mobile-use.com)](https://mobile-use.com)
+[Get Started](#quick-start) · [API Docs](#api-reference) · [Roadmap](ROADMAP.md) · [Mobile Next Cloud](https://mobilenext.ai)
 
 ## Why Mobilewright?
 
@@ -21,7 +21,7 @@ If you've used Playwright, you already know Mobilewright.
 | Setup | `npm install mobilewright` | Server + drivers + caps | React Native only | Xcode/AS only |
 | Cross-platform | iOS + Android, one API | Yes, verbose | React Native only | Single platform |
 | AI agent support | First-class (accessibility tree) | Limited | No | No |
-| Real devices in the cloud | Via [mobile-use.com](https://mobile-use.com) | Yes (complex) | Simulators only | Yes |
+| Real devices in the cloud | Via [Mobile Next Cloud](https://mobilenext.ai) | Yes (complex) | Simulators only | Yes |
 | Locators | Semantic roles + labels | XPath, CSS, ID | Test IDs | Native queries |
 
 ## Built for AI agents
@@ -93,10 +93,10 @@ It checks Xcode, Android SDK, simulators, ADB, and other dependencies — and te
 | `@mobilewright/test` | Test fixtures |
 | `@mobilewright/protocol` | TypeScript interfaces (`MobilewrightDriver`, `ViewNode`) |
 | `@mobilewright/driver-mobilecli` | WebSocket JSON-RPC client for mobilecli |
-| `@mobilewright/driver-mobile-use` | WebSocket JSON-RPC client for [mobile-use.com](https://mobile-use.com) cloud devices |
-| `@mobilewright/mobilewright-core` | `Device`, `Screen`, `Locator`, `expect` — the user-facing API |
+| `@mobilewright/driver-mobilenext` | WebSocket JSON-RPC client for [Mobile Next Cloud](https://mobilenext.ai) cloud devices |
+| `@mobilewright/core` | `Device`, `Screen`, `Locator`, `expect` — the user-facing API |
 
-Most users only need `mobilewright` (or `@mobilewright/test` for vitest integration).
+Most users only need `mobilewright` (or `@mobilewright/test` for Playwright Test integration).
 
 ## API Reference
 
@@ -120,13 +120,13 @@ const device = await ios.launch({ deviceName: /My.*iPhone/ });
 const device = await ios.launch({ deviceId: '5A5FCFCA-...' });
 
 // List available devices
-const devices = ios.devices();
-const devices = android.devices();
+const devices = await ios.devices();
+const devices = await android.devices();
 ```
 
 `launch()` handles the full lifecycle:
 1. Checks if mobilecli is reachable (auto-starts it for local URLs if not running)
-2. Discovers booted devices (prefers simulators over real devices)
+2. Discovers booted devices (picks the first device that matches your criteria)
 3. Connects and optionally launches the app
 4. On `device.close()`, kills the auto-started server
 
@@ -156,6 +156,9 @@ await screen.swipe('up')
 await screen.swipe('down', { distance: 300, duration: 500 })
 await screen.pressButton('HOME')
 await screen.tap(195, 400)                           // raw coordinate tap
+await screen.doubleTap(195, 400)                     // raw coordinate double-tap
+await screen.longPress(195, 400, 1000)               // raw coordinate long-press (optional duration in ms)
+const tree = await screen.viewTree()                 // raw accessibility tree (ViewNode[])
 ```
 
 ### Locator
@@ -168,14 +171,38 @@ Lazy, chainable element reference. No queries execute until you call an action o
 await locator.tap()
 await locator.doubleTap()
 await locator.longPress({ duration: 1000 })
-await locator.fill('hello@example.com')              // tap to focus + type text
+await locator.fill('hello@example.com')              // tap to focus, clear, then type text
+await locator.clear()                                // tap to focus + clear the field
 await locator.swipe({ direction: 'left' })           // swipe on a specific element
 await locator.scrollIntoViewIfNeeded()               // scroll until element is visible
+await locator.screenshot()                           // capture just this element (cropped PNG)
+```
+
+**Narrowing & combining** — refine a locator that matches multiple elements:
+
+```typescript
+locator.filter({ hasText: 'In stock' })              // keep matches whose subtree contains text
+locator.filter({ hasNotText: /sold out/i })          // keep matches whose subtree does NOT contain text
+locator.filter({ has: screen.getByRole('button') })  // keep matches containing a child locator
+locator.filter({ hasNot: screen.getByText('Ad') })   // keep matches NOT containing a child locator
+locator.and(screen.getByRole('button'))              // match both this and another locator
+locator.or(screen.getByText('Retry'))                // match either this or another locator
+```
+
+**Multiple matches** — work with locators that resolve to more than one element:
+
+```typescript
+locator.first()                                      // first match
+locator.last()                                       // last match
+locator.nth(2)                                       // match at index (negative counts from the end)
+await locator.count()                                // number of matching elements
+await locator.all()                                  // array of Locators, one per match
 ```
 
 **Queries:**
 
 ```typescript
+await locator.exists()                               // boolean — present in the hierarchy (no wait)
 await locator.isVisible()                            // boolean
 await locator.isEnabled()                            // boolean
 await locator.isSelected()                           // boolean
@@ -183,6 +210,7 @@ await locator.isFocused()                            // boolean
 await locator.isChecked()                            // boolean
 await locator.getText()                              // waits for visibility first
 await locator.getValue()                             // raw value (e.g. text field content)
+await locator.boundingBox()                          // { x, y, width, height }
 ```
 
 **Explicit waiting:**
@@ -207,6 +235,30 @@ const title = await screen.getByType('NavigationBar').getByType('StaticText').ge
 
 When chaining, child lookups use bounds-based containment: any element whose bounds fit within the parent's bounds is considered a child. This works correctly with mobilecli's flat element lists.
 
+### WebView (hybrid apps)
+
+Apps that embed web content — Cordova, Capacitor, Ionic, or a raw `WKWebView` / Android `WebView` — expose a real DOM behind the native view. `screen.getByWebView()` bridges into that DOM and hands you a **Playwright-compatible** `Page`, so web content is driven with the exact Playwright API you already know.
+
+```typescript
+// Find the web view and resolve its page (Playwright-style)
+const webview = screen.getByWebView();               // optionally { testId: 'checkout-web' }
+const page = await webview.page();
+
+// From here it's the standard Playwright Page / Locator API
+await page.goto('https://example.com/login');
+await page.getByLabel('Email').fill('user@example.com');
+await page.getByRole('button', { name: 'Sign In' }).click();
+
+await expect(page).toHaveURL(/dashboard/);
+await expect(page.getByText('Welcome')).toBeVisible();
+```
+
+**Page** — navigation and lifecycle: `goto`, `reload`, `goBack`, `goForward`, `url`, `title`, `content`, `waitForURL`, `waitForLoadState`, `close`. Locator factories: `locator`, `getByRole`, `getByText`, `getByLabel`, `getByPlaceholder`, `getByTestId`, `getByAltText`, `getByTitle`.
+
+**Web Locator** — actions: `click`, `fill`, `type`, `press`, `focus`, `hover`, `scrollIntoViewIfNeeded`. Queries: `getText`, `getValue`, `textContent`, `innerText`, `innerHTML`, `inputValue`, `getAttribute`, `boundingBox`, `isVisible`, `isHidden`, `isEnabled`, `isDisabled`, `isChecked`. Plus `waitFor`, `first`/`last`/`nth`, `count`, and `all`. Assertions (`expect`) work the same as on native locators.
+
+`MobileWebViewPage` and `MobileWebViewLocator` are exported from `mobilewright` for advanced use (`Page` / `WebLocator` remain as back-compat aliases).
+
 ### Device
 
 Manages the connection lifecycle and exposes device/app-level controls.
@@ -216,12 +268,15 @@ Manages the connection lifecycle and exposes device/app-level controls.
 await device.setOrientation('landscape');
 const orientation = await device.getOrientation();
 
+// Screen dimensions and pixel density: { width, height, scale }
+const size = await device.screenSize();
+
 // URLs / deep links (goto is a Playwright-style alias for openUrl)
 await device.goto('myapp://settings');
 await device.openUrl('https://example.com');
 
 // App lifecycle
-await device.launchApp('com.example.app', { locale: 'fr_FR' }); // waits until app is in foreground
+await device.launchApp('com.example.app', { locales: ['fr-FR'] }); // waits until app is in foreground
 await device.launchApp('com.example.app', { noWaitAfter: true }); // skip foreground wait
 await device.terminateApp('com.example.app');
 const apps = await device.listApps();
@@ -242,13 +297,24 @@ import { expect } from 'mobilewright';
 
 await expect(locator).toBeVisible();
 await expect(locator).not.toBeVisible();
+await expect(locator).toBeHidden();
 
 await expect(locator).toBeEnabled();
-await expect(locator).not.toBeEnabled();
+await expect(locator).toBeDisabled();
+
+await expect(locator).toBeSelected();
+await expect(locator).toBeFocused();
+await expect(locator).toBeChecked();
 
 await expect(locator).toHaveText('Welcome back!');
 await expect(locator).toHaveText(/welcome/i);
 await expect(locator).toContainText('back');
+await expect(locator).toBeEmpty();                   // element has no text
+
+await expect(locator).toHaveValue('user@example.com'); // text field / input value
+await expect(locator).toHaveValue(/@example\.com$/);
+
+await expect(locator).toHaveCount(3);                // number of matching elements
 
 await expect(locator).toBeVisible({ timeout: 10_000 });
 ```
@@ -299,13 +365,44 @@ All options:
 | `bundleId` | `string` | App bundle ID (optional) |
 | `deviceId` | `string` | Explicit device UDID (optional) |
 | `deviceName` | `RegExp` | RegExp to match device name (optional) |
-| `timeout` | `number` | Global locator timeout in ms (optional) |
+| `installApps` | `string \| string[]` | App paths (APK/IPA) to install before launching (optional) |
+| `autoAppLaunch` | `boolean` | Automatically launch the app after connecting. Default: `true` |
+| `viewTree` | `'on-failure' \| 'off'` | Attach the accessibility tree as JSON to the report on failure. Default: `'off'` |
+| `timeout` | `number` | Per-test timeout in ms (optional) |
+| `globalTimeout` | `number` | Hard cap on the entire test suite run in ms (optional) |
 | `testDir` | `string` | Directory to search for test files (optional) |
 | `testMatch` | `string \| RegExp \| Array` | Glob patterns for test files (optional) |
+| `testIgnore` | `string \| RegExp \| Array` | Glob patterns for files to skip during discovery (optional) |
+| `outputDir` | `string` | Output directory for test artifacts. Default: `test-results` |
 | `reporter` | `'list' \| 'html' \| 'json' \| 'junit' \| Array` | Reporter to use (optional) |
 | `retries` | `number` | Maximum retry count for flaky tests (optional) |
+| `workers` | `number \| string` | Number of concurrent workers (optional) |
+| `fullyParallel` | `boolean` | Run all tests in parallel. Default: `false` |
+| `use` | `MobilewrightUseOptions` | Per-action defaults applied to all tests (optional) |
+| `expect` | `MobilewrightExpectConfig` | Default options for `expect()` assertions (optional) |
+| `globalSetup` | `string \| string[]` | Setup file(s) run once before all tests (optional) |
+| `globalTeardown` | `string \| string[]` | Teardown file(s) run once after all tests (optional) |
 | `projects` | `MobilewrightProjectConfig[]` | Multi-device / multi-platform project matrix (optional) |
 
+The `use` object holds per-action defaults shared by every test:
+
+| `use` option | Type | Description |
+|---|---|---|
+| `platform` | `'ios' \| 'android'` | Platform for the run (optional) |
+| `deviceName` | `RegExp` | RegExp to match device name (optional) |
+| `bundleId` | `string` | App bundle ID (optional) |
+| `installApps` | `string \| string[]` | App paths to install — overrides top-level `installApps` (optional) |
+| `animations` | `'on' \| 'off'` | Toggle system animations on the device; left unchanged if omitted |
+| `actionTimeout` | `number` | Default timeout for locator actions (tap, fill, …) in ms. Default: `5000` |
+| `appLaunchTimeout` | `number` | Timeout waiting for the app to reach foreground after launch, in ms. Default: `20000` |
+| `installTimeout` | `number` | Timeout for app installation in ms (optional) |
+
+The `expect` object sets assertion defaults:
+
+| `expect` option | Type | Description |
+|---|---|---|
+| `timeout` | `number` | Default timeout for assertions (`toBeVisible`, `toHaveText`, …) in ms. Default: `5000` |
+
 Config values are used as defaults — `LaunchOptions` passed to `ios.launch()` always take precedence.
 
 Mobilewright will use the first device that matches your configured criteria.
@@ -335,6 +432,26 @@ test('can sign in', async ({ device, screen, bundleId }) => {
 
 The `device` fixture connects once per worker (reading from `mobilewright.config.ts`) and calls `device.close()` after all tests complete. The `screen` fixture provides `device.screen` to each test, with automatic screenshot-on-failure and optional video recording.
 
+**`test.use()` options** — override config per file (or per `test.describe` block):
+
+| Option | Type | Description |
+|---|---|---|
+| `bundleId` | `string` | App bundle ID for these tests |
+| `platform` | `'ios' \| 'android'` | Target platform |
+| `deviceName` | `RegExp` | RegExp to match the device name |
+| `installApps` | `string \| string[]` | App paths (APK/IPA) to install before the tests run |
+| `autoAppLaunch` | `boolean` | Launch the app automatically before each test. Default: `true` |
+| `viewTree` | `'on-failure' \| 'off'` | Attach the accessibility tree as JSON when a test fails. Default: `'off'` |
+| `video` | `'on' \| 'retain-on-failure' \| 'off'` | Record video — always, only on failure, or never. Default: `'off'` |
+
+```typescript
+test.use({
+  bundleId: 'com.example.myapp',
+  video: 'retain-on-failure',
+  viewTree: 'on-failure',
+});
+```
+
 ## CLI
 
 ### `mobilewright init`
@@ -365,6 +482,41 @@ ID                                      Name                     Platform  Type
 5A5FCFCA-27EC-4D1B-B412-BAE629154EE0    iPhone 17 Pro            ios       simulator   booted
 ```
 
+### `mobilewright inspect`
+
+Open the Mobilewright Inspector — a browser-based UI showing a live screenshot of your connected device alongside every element and its best locator.
+
+```bash
+npx mobilewright inspect
+npx mobilewright inspect --port 4621   # use a specific port (default: 4621)
+```
+
+The Inspector opens automatically in your browser. Select a device from the picker at the top, then click **Refresh** or enable **Auto refresh**. Click any row in the element list to highlight its bounding box on the screenshot. Elements that share a locator with another element get a `dup` badge.
+
+Locator priority matches what mobilewright uses: `getByTestId` > `getByRole` > `getByLabel` > `getByText`.
+
+### `mobilewright screenshot`
+
+Capture a screenshot of a connected device. Auto-starts mobilecli if it isn't running.
+
+```bash
+npx mobilewright screenshot                          # saves screenshot.png
+npx mobilewright screenshot -o home.png              # custom output path
+npx mobilewright screenshot -d <device-id>           # target a specific device
+npx mobilewright screenshot --url ws://host:12000    # remote mobilecli server
+```
+
+### `mobilewright install`
+
+Install the mobilecli agent on a connected device.
+
+```bash
+npx mobilewright install                             # install on the first device
+npx mobilewright install -d <device-id>              # target a specific device
+npx mobilewright install --force                     # force reinstall
+npx mobilewright install --provisioning-profile <p>  # iOS provisioning profile
+```
+
 ### `mobilewright test`
 
 Run your tests. Auto-discovers `mobilewright.config.ts` in the current directory.
@@ -388,11 +540,20 @@ npx mobilewright show-report
 npx mobilewright show-report mobilewright-report/
 ```
 
-## Run on real devices with mobile-use.com
+### `mobilewright merge-reports`
+
+Merge blob reports from sharded/parallel CI runs into a single report.
+
+```bash
+npx mobilewright merge-reports ./blob-reports        # merge into an HTML report (default)
+npx mobilewright merge-reports ./blob-reports --reporter json
+```
+
+## Run on real devices with Mobile Next Cloud
 
-Need real phones in the cloud? [mobile-use.com](https://mobile-use.com) gives you API access to hundreds of real Android and iOS devices. Your Mobilewright scripts run with zero modification — point your config at the mobile-use.com endpoint and go.
+Need real phones in the cloud? [Mobile Next Cloud](https://mobilenext.ai) gives you API access to hundreds of real Android and iOS devices. Your Mobilewright scripts run with zero modification — point your config at the Mobile Next Cloud endpoint and go.
 
-mobile-use.com is the only device cloud with native Mobilewright support.
+Mobile Next Cloud is the only device cloud with native Mobilewright support.
 
 ## Telemetry
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobilewright/test",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "description": "Test fixtures for Mobilewright",
   "homepage": "https://mobilewright.dev",
   "license": "Apache-2.0",
@@ -29,10 +29,10 @@
     "dist"
   ],
   "dependencies": {
-    "@mobilewright/core": "^0.0.46",
-    "@mobilewright/protocol": "^0.0.46",
+    "@mobilewright/core": "^0.0.47",
+    "@mobilewright/protocol": "^0.0.47",
     "@playwright/test": "1.58.2",
     "debug": "^4.4.3",
-    "mobilewright": "^0.0.46"
+    "mobilewright": "^0.0.47"
   }
 }