mobile-next/mobilewright

Mobilewright – 适用于 iOS 和 Android 的 Playwright 风格自动化

简介 – 一个 TypeScript/Node.js 框架，允许您使用与 Playwright 为 Web 浏览器提供的相同易用 API，为真实 iOS/Android 设备、模拟器或模拟器编写端到端测试。

重要性 – 它暴露了设备的辅助功能树，因此操作可以以语义术语（getByRole('button')、fill、tap）表达，而不是脆弱的坐标或 XPath。这使得该库对 AI 代理特别友好，因为它们可以读取辅助功能树并发出确定性命令，而无需视觉模型。

核心概念

• 启动器（ios、android） – 发现并连接设备、启动应用、管理生命周期。
• Screen – 在当前视图中查找元素的根定位器。
• Locator – 惰性、可链式引用的定位器，在操作前自动等待可见性、启用性和稳定性。
• 断言 – Playwright 兼容的 expect，轮询直到条件满足。
• WebView 支持 – 桥接到嵌入的 Web 内容，并使用完整的 Playwright Page API 驱动它。
• 远程驱动程序 – 可选连接到 Mobile Next Cloud 或任何 mobilecli 服务器，用于设备实验室设置。

主要功能

• Playwright 风格 API（screen.getByRole('button').tap()）。
• 零配置设备发现；适用于已启动的模拟器、模拟器或已连接的手机。
• 内置自动等待和可重试断言。
• 统一的 iOS/Android 接口；相同的测试代码可在两个平台上运行。
• 通过辅助功能树提供一流的 AI 代理支持。
• 测试夹具（@mobilewright/test）与 Playwright Test 运行器集成。
• 可通过 mobilewright.config.ts 文件配置，支持多设备矩阵、超时、重试等。

典型工作流

npm install mobilewright @mobilewright/test
npx mobilewright init   # 创建配置和测试脚手架

import { test, expect } from '@mobilewright/test';

test('登录流程', async ({ screen }) => {
  await screen.getByLabel('Email').fill('user@example.com');
  await screen.getByLabel('Password').fill('password123');
  await screen.getByRole('button', { name: 'Sign In' }).tap();
  await expect(screen.getByText('Welcome back')).toBeVisible();
});

npx mobilewright test   # 在发现的设备上运行

安装和先决条件

• Node.js ≥ 22.12。
• 已启动的 iOS 模拟器、Android 模拟器或通过 USB 连接的真实设备。
• 运行 npx mobilewright doctor 验证 Xcode、Android SDK、ADB 等。

适用场景

• 原生移动应用（包括 React Native、Flutter 等）的自动化 UI 测试。
• 需要确定性、令牌高效的手机控制的 AI 驱动代理。
• 需要单一 API 支持两个平台的持续集成管道。
• 混合应用：在 WebView 内切换到 Playwright Page 并重用现有 Web 测试代码。

项目结构

包	作用
mobilewright	核心库、CLI、启动器、expect、配置
@mobilewright/test	Playwright 测试集成夹具
@mobilewright/protocol	驱动通信的类型定义
@mobilewright/driver-mobilecli	本地 mobilecli 服务器的 WebSocket 客户端
@mobilewright/driver-mobilenext	Mobile Next Cloud 设备客户端
@mobilewright/core	共享运行时工具

文档和资源

• 快速入门指南和 API 参考位于仓库的 docs 文件夹中。
• 路线图：ROADMAP.md。
• 云设备访问：Mobile Next Cloud (https://mobilenext.ai/cloud)。

总结 – Mobilewright 为移动应用提供了现代、自动等待、跨平台的自动化层，特意设计为人类开发者和 AI 代理均可使用。