Merge branch 'main' into feat/tracing

Author: gmegidish

.claude/CLAUDE.md

@@ -0,0 +1,8 @@
+# Mobilewright — Claude Code rules
+
+## Commits & branches
+
+- Branch names must follow conventional format: `feat/…`, `fix/…`, `chore/…`, `ci/…`, `docs/…`, `refactor/…`, `test/…`
+- Commit messages must follow Conventional Commits: `feat:`, `fix:`, `chore:`, etc. — single line, no body
+- Always run `npm run lint` and confirm it passes before committing
+- Stage only the files required for the change — never `git add -A` or `git add .`

.claude/commands/release-mobilewright.md

@@ -0,0 +1,55 @@
+Prepare a mobilewright release by updating CHANGELOG.md with the next patch version.
+
+## Steps
+
+### 1. Verify version consistency
+
+- Run `git tag --sort=-version:refname | head -1` to get the latest git tag (e.g. `v0.0.35`)
+- Read the first line of `CHANGELOG.md` to extract the version there (e.g. `## [0.0.35]`)
+- If they do not match, stop and report the mismatch. Do not proceed.
+
+### 2. Compute next version
+
+- Strip the `v` prefix from the latest tag, split on `.`, increment the patch segment by 1
+- Example: `v0.0.35` → `0.0.36`
+
+### 3. Collect changes since last tag
+
+- Run `git log v<LAST_VERSION>..HEAD --oneline` to list commits
+- For each commit, try to find an associated PR number:
+  - Look for `(#NNN)` in the commit message, or
+  - Run `gh pr list --state merged --search "<commit sha>" --json number,title,author` via the GitHub API
+- For each PR found, fetch the author: `gh pr view <NNN> --repo mobile-next/mobilewright --json author --jq '.author.login'`
+
+### 4. Determine contributor credit
+
+- Read `.github/CODEOWNERS` to get the list of maintainer GitHub logins
+- For each change, if the PR author is **not** in the CODEOWNERS maintainers list, append:
+  `thanks to [@<login>](https://github.com/<login>)`
+
+### 5. Format the CHANGELOG entry
+
+Use the existing CHANGELOG.md format:
+
+```
+## [0.0.36] (YYYY-MM-DD)
+* Feat: description ([#NNN](https://github.com/mobile-next/mobilewright/pull/NNN))
+* Fix: description ([#NNN](https://github.com/mobile-next/mobilewright/pull/NNN)), thanks to [@login](https://github.com/login)
+```
+
+- Use today's date for the release date
+- Capitalise the type prefix (`Feat`, `Fix`, `Chore`, etc.) from the conventional commit prefix
+- Omit chore/ci/docs commits that are not user-facing unless they are significant
+- Prepend the new entry at the top of CHANGELOG.md, above the previous `## [...]` line
+
+### 6. Stop — do not commit
+
+Display the new CHANGELOG.md entry and remind the human to review and commit manually when ready.
+The suggested commit and tag commands to show the user:
+
+```
+git add CHANGELOG.md
+git commit -m "chore: update changelog for v0.0.36"
+git tag v0.0.36
+git push && git push --tags
+```

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,76 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in Mobilewright
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening a bug report, please [search existing issues](https://github.com/mobile-next/mobilewright/issues) to avoid duplicates.
+
+  - type: input
+    id: version
+    attributes:
+      label: Mobilewright version
+      placeholder: "e.g. 1.2.3"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "e.g. macOS 15.4, Ubuntu 24.04"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Target platform
+      options:
+        - iOS
+        - Android
+        - Both
+    validations:
+      required: true
+
+  - type: input
+    id: device
+    attributes:
+      label: Device or simulator
+      placeholder: "e.g. iPhone 16 Pro (simulator), Pixel 8 (real device)"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Smallest possible code or steps to reproduce the issue.
+      placeholder: |
+        1. ...
+        2. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Logs, screenshots, or anything else that may be relevant.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,48 @@
+name: Feature Request
+description: Propose a new feature or enhancement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For larger feature proposals, please open this issue to discuss the design **before** sending a PR. This helps avoid wasted effort and keeps changes aligned with the project direction.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What problem does this feature solve? What use case does it unlock?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe the feature you'd like, including any API or behavior changes.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Target platform
+      options:
+        - iOS
+        - Android
+        - Both
+        - Platform-agnostic
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've thought of, and why you prefer this one.
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Mockups, screenshots, references, related issues, or anything else that would help.

.github/workflows/ci.yml

@@ -4,7 +4,17 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'ROADMAP.md'
+      - 'docs/**'
   pull_request:
+    paths-ignore:
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'ROADMAP.md'
+      - 'docs/**'
 
 jobs:
   test:
@@ -19,4 +29,5 @@ jobs:
       - run: npm ci --ignore-scripts
       - run: npm audit
       - run: npm run build
+      - run: npm run lint
       - run: npm test

.github/workflows/publish.yml

@@ -38,10 +38,14 @@ jobs:
         working-directory: packages/test
       - run: npm publish --access public --provenance
         working-directory: packages/test
-      - name: Create GitHub release
+      - name: Create or update GitHub release
         run: |
           VERSION=${GITHUB_REF_NAME#v}
           sed -n "/^## \[$VERSION\]/,/^## \[/{ /^## \[$VERSION\]/p; /^## \[/!p; }" CHANGELOG.md > release-notes.md
-          gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file release-notes.md
+          if gh release view "$GITHUB_REF_NAME" &>/dev/null; then
+            gh release edit "$GITHUB_REF_NAME" --notes-file release-notes.md
+          else
+            gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file release-notes.md
+          fi
         env:
           GH_TOKEN: ${{ github.token }}

.gitignore

@@ -20,23 +20,30 @@ test-results/
 .env.*
 *.log
 
+# Hand-written declaration files — keep these
+!packages/*/src/playwright.d.ts
+
 # TypeScript build artifacts emitted outside dist/
 packages/*/src/**/*.js
 packages/*/src/**/*.js.map
 packages/*/src/**/*.d.ts
 packages/*/src/**/*.d.ts.map
+packages/*/templates/**/*.js
+packages/*/templates/**/*.js.map
+packages/*/templates/**/*.d.ts
+packages/*/templates/**/*.d.ts.map
 e2e/**/*.js
 e2e/**/*.js.map
 e2e/**/*.d.ts
 e2e/**/*.d.ts.map
-
-# Hand-written declaration files — keep these
-!packages/*/src/playwright.d.ts
-
 scripts/**/*.js
 scripts/**/*.js.map
 scripts/**/*.d.ts
 scripts/**/*.d.ts.map
+tests/**/*.js
+tests/**/*.js.map
+tests/**/*.d.ts
+tests/**/*.d.ts.map
 examples/**/*.js
 examples/**/*.js.map
 examples/**/*.d.ts

CHANGELOG.md

@@ -1,3 +1,75 @@
+## [0.0.38] (2026-05-17)
+* Fix(ios): call `getForegroundApp()` before `launchApp()` in mobilecli driver to ensure DeviceKit is running first, preventing a race where its startup minimizes the newly-launched app ([#89](https://github.com/mobile-next/mobilewright/issues/89))
+* Fix(android): using instruments to get view tree, solves bug when constant UI change would fail "uiautomator dump" (fix is in mobilecli 0.3.74)
+* General: skip redundant `mobilecli devices` shell-outs in `connect()` and `installApp()` when device type is already known, reducing test startup time by ~4s
+* General: break early if installApps points to non-zip containers, before allocating devices
+* General: added plenty of verbose logs when `DEBUG=mw:*`
+
+## [0.0.37] (2026-05-16)
+* Feat: add installApps to per-project overrides ([#133](https://github.com/mobile-next/mobilewright/pull/133))
+* Feat: export HardwareButton from @mobilewright/core and add LOCK button ([#132](https://github.com/mobile-next/mobilewright/pull/132))
+* Fix: use Number.NaN and String.raw in tests ([#93](https://github.com/mobile-next/mobilewright/pull/93)), thanks to [@khanhdodang](https://github.com/khanhdodang)
+
+## [0.0.36] (2026-05-16)
+* Feat: add toHaveCount and toBeEmpty assertions ([#122](https://github.com/mobile-next/mobilewright/pull/122)), thanks to [@alexC2K](https://github.com/alexC2K)
+* Feat: add device info annotations to test report ([#125](https://github.com/mobile-next/mobilewright/pull/125))
+* Feat(test): attach accessibility tree on test failure via saveTreeOnFailure ([#111](https://github.com/mobile-next/mobilewright/pull/111)), thanks to [@farhanlabib](https://github.com/farhanlabib)
+* Feat: add eslint with @typescript-eslint and @stylistic rules ([#127](https://github.com/mobile-next/mobilewright/pull/127))
+* Fix(driver): reject .ipa installs on iOS simulators with a clear error ([#74](https://github.com/mobile-next/mobilewright/pull/74)), thanks to [@krismuhi](https://github.com/krismuhi)
+* Fix: only catch LocatorError in expect assertions, rethrow unexpected errors ([#126](https://github.com/mobile-next/mobilewright/pull/126))
+* Fix: respect autoAppLaunch config option in test fixture ([#110](https://github.com/mobile-next/mobilewright/pull/110)), thanks to [@farhanlabib](https://github.com/farhanlabib)
+
+## [0.0.35] (2026-05-12)
+* Fix(android): updated mobilecli to 0.3.73 to fix missing elements that had non-null resource-id ([#120](https://github.com/mobile-next/mobilewright/pull/120))
+
+## [0.0.34] (2026-05-12)
+* Feat(locator): `locator.exists()` is now available — returns `true` if the element is present in the view tree
+* Fix: `--config` flag is now correctly honored in fixtures and device-pool setup ([#109](https://github.com/mobile-next/mobilewright/pull/109))
+* Fix(android): moved away from monkey to run apps, fixes apks compiled with 'test' flag
+
+## [0.0.33] (2026-05-07)
+* Fix(android): warn and continue when foreground app check fails on launch instead of throwing error, thanks [@farhanlabib](https://github.com/farhanlabib) ([#102](https://github.com/mobile-next/mobilewright/pull/102))
+
+## [0.0.32] (2026-05-05)
+* Fix: updated mobilecli to fix 'SYS_KEYS has no physical keys but with factor 2.0%' error on certain Android devices
+
+## [0.0.31] (2026-05-04)
+* Feat: `screen.getByPlaceholder()` is now available ([#84](https://github.com/mobile-next/mobilewright/pull/84))
+* Feat: `launchApp()` now waits for the app to reach the foreground before continuing; pass `noWaitAfter: true` to skip ([#80](https://github.com/mobile-next/mobilewright/pull/80))
+* Feat: Add anonymous telemetry for `test`, `doctor`, and `init` commands - see README for opt-out ([#79](https://github.com/mobile-next/mobilewright/pull/79))
+* Feat: `init` example test template now includes a `device` param and doc comments ([#86](https://github.com/mobile-next/mobilewright/pull/86))
+* Fix: mobilewright --version now reads from `package.json` instead of the hardcoded `'0.0.1'` ([#78](https://github.com/mobile-next/mobilewright/pull/78))
+
+## [0.0.30] (2026-05-01)
+* Fix(config): `loadConfig()` now uses `pathToFileURL` for dynamic import — fixes config not loading on Windows
+* Fix(doctor): Suggest `Microsoft.OpenJDK.17` instead of Azul Zulu for Windows JDK installs
+* Feat(test): `swipe` on a locator — e.g. swipe left on a list item
+* Docs: Added Windows instructions for enabling debug logs (`$env:DEBUG` / `set DEBUG`)
+
+## [0.0.29] (2026-04-30)
+* General: mobilecli agent is automatically installed on simulators and emulators at connect time — no manual `mobilewright install` step needed
+* Fix(cli): `npx mobilewright init` now works correctly — templates were missing from the published dist
+* Fix(driver-mobilecli): Windows 11 is now supported — `win32-x64` resolves to `mobilecli-windows-amd64.exe`
+
+## [0.0.28] (2026-04-29)
+* Fix(test): Stream cloud recordings to disk instead of loading into memory — safe for large video files
+* Fix(test): Video attachments now work with the cloud drivers
+* Fix(cli): Fixed HTML report branding so it now applies when the `html` reporter is configured
+
+## [0.0.27] (2026-04-28)
+* General: New worker/device-pool architecture: workers acquire devices from a shared pool instead of each worker owning a dedicated device
+* General: Track installed apps per slot to skip re-install when the same worker reuses a device
+* General: Per-allocation timeouts via `AbortSignal`; pool shutdown drains waiters and releases all slots
+* General: Stack traces from `expect()` failures now omit mobilewright frames — set `MWDEBUGIMPL=1` to see them
+* General: Upgrade mobilecli to `0.3.67`
+* CLI: Add `--shard` option to the `test` command for multi-host sharding of tests
+* CLI: Add `mobilewright merge-reports` command, needed for sharding
+* Fix: Fix 'text' field from viewTree to fetch from dump's 'text' instead of 'label', thanks to [emor](https://github.com/emor)
+* Fix(allocator-factory): Throw on unknown driver type instead of silently falling back to mobile-use
+* Fix(driver-mobile-use): Only call `fleet.release` on disconnect when this instance owns the lease
+* Fix(device-pool): Re-queue waiters on `NoDeviceAvailableError`; treat `NaN` `--workers` as 1
+* Fix(rpc-client): Close WebSocket nicely with code 1000 and await the close handshake on `disconnect()`
+
 ## [0.0.26] (2026-04-22)
 * Fix(driver-mobile-use): Device allocation now correctly waits for provisioning to complete 
 * Fix(driver-mobile-use): `devices.list` response properly unwrapped from `{ devices: [...] }` envelope

README.md

@@ -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) · [Cloud (mobile-use.com)](https://mobile-use.com)
+[Get Started](#quick-start) · [API Docs](#api-reference) · [Roadmap](ROADMAP.md) · [Cloud (mobile-use.com)](https://mobile-use.com)
 
 ## Why Mobilewright?
 
@@ -144,6 +144,7 @@ screen.getByText(/welcome/i)                        // RegExp match
 screen.getByText('welcome', { exact: false })       // substring match
 screen.getByType('TextField')                       // element type
 screen.getByRole('button', { name: 'Sign In' })     // semantic role + name filter
+screen.getByPlaceholder('Search...')                // placeholder text
 ```
 
 **Direct actions:**
@@ -168,6 +169,8 @@ await locator.tap()
 await locator.doubleTap()
 await locator.longPress({ duration: 1000 })
 await locator.fill('hello@example.com')              // tap to focus + type text
+await locator.swipe({ direction: 'left' })           // swipe on a specific element
+await locator.scrollIntoViewIfNeeded()               // scroll until element is visible
 ```
 
 **Queries:**
@@ -218,7 +221,8 @@ await device.goto('myapp://settings');
 await device.openUrl('https://example.com');
 
 // App lifecycle
-await device.launchApp('com.example.app', { locale: 'fr_FR' });
+await device.launchApp('com.example.app', { locale: '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();
 const foreground = await device.getForegroundApp();
@@ -390,6 +394,16 @@ Need real phones in the cloud? [mobile-use.com](https://mobile-use.com) gives yo
 
 mobile-use.com is the only device cloud with native Mobilewright support.
 
+## Telemetry
+
+Mobilewright collects anonymous usage telemetry via PostHog. To disable it, set the `MOBILEWRIGHT_DISABLE_TELEMETRY` environment variable:
+
+```bash
+MOBILEWRIGHT_DISABLE_TELEMETRY=1 npx mobilewright test
+```
+
+When telemetry is enabled, a random identifier is generated and stored in `~/.config/mobilenext/mobilewright/config.json`. No personal information or test data is ever collected.
+
 ## Contributing
 
 ```bash