Playwright 移动端真机测试：Android/iOS 设备连接与自动化

引言：告别模拟器痛点，拥抱真机测试新范式

你是否还在忍受移动端模拟器测试的三大痛点？耗时的环境配置、与真实设备的行为差异、无法覆盖传感器交互场景？本文将系统讲解如何使用 Playwright 实现 Android/iOS 真机自动化测试，从设备连接到复杂场景验证，全程实战代码驱动，帮你构建稳定、高效的移动端测试体系。

读完本文你将掌握：

• Android 设备 ADB 连接与权限配置全流程
• iOS 设备 WebDriverAgent 部署与调试技巧
• 跨平台真机自动化 API 实战（包括文件传输、传感器模拟）
• 多设备并行测试与 CI 集成方案
• 真机测试常见问题诊断与性能优化策略

一、环境准备：构建跨平台真机测试基础

1.1 核心依赖与系统要求

环境	最低版本要求	推荐配置
Node.js	v16.13+	v18.17 LTS
Python	3.8+	3.11+
JDK	11+	17 LTS
ADB (Android)	1.0.41+	1.0.42
Xcode (iOS)	14.3+	15.0+
Playwright	1.32.0+	1.40.0+

1.2 Android 设备准备流程

# 1. 安装 Android SDK 平台工具
sudo apt install android-sdk-platform-tools  # Ubuntu/Debian
brew install android-platform-tools          # macOS

# 2. 验证 ADB 版本
adb --version  # 需显示 1.0.41+

# 3. 启用开发者模式（设备端）
# - 打开设置 > 关于手机 > 连续点击"版本号"7次
# - 返回设置 > 系统 > 开发者选项 > 启用"USB调试"

# 4. 验证设备连接
adb devices -l
# 预期输出：List of devices attached
#          XXXXXXXX               device product:XXX model:XXX device:XXX

1.3 iOS 设备准备流程

# 1. 安装 Xcode 命令行工具
xcode-select --install

# 2. 安装 WebDriverAgent
brew install carthage
git clone https://gitcode.com/appium/WebDriverAgent.git
cd WebDriverAgent
./Scripts/bootstrap.sh

# 3. 配置代码签名（需Apple开发者账号）
# - 打开 WebDriverAgent.xcodeproj
# - 选择 WebDriverAgentRunner 目标
# - 在"Signing & Capabilities"中配置团队信息

# 4. 启动 WDA 服务
xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=设备UDID' test

二、Playwright 真机测试核心 API

2.1 设备连接与管理

// Android 设备连接示例
import { _android } from 'playwright';

(async () => {
  // 列出已连接设备
  const devices = await _android.devices();
  console.log(`发现 ${devices.length} 台设备`);
  
  // 连接指定设备（通过序列号）
  const [device] = devices;
  console.log(`连接设备: ${device.model()}`);
  
  // 启动 Chrome 浏览器
  const context = await device.launchBrowser();
  const page = await context.newPage();
  
  // 基本操作示例
  await page.goto('https://m.baidu.com');
  await page.fill('input[name="word"]', 'Playwright 真机测试');
  await page.click('input[type="submit"]');
  
  // 截图验证
  await page.screenshot({ path: 'android-search-result.png' });
  
  // 关闭资源
  await context.close();
  await device.close();
})();

2.2 文件传输与 shell 操作

// 设备文件操作示例
async function deviceFileOperations(device) {
  // 推送文件到设备
  await device.push(
    Buffer.from('测试文件内容'), 
    '/data/local/tmp/test-file.txt'
  );
  
  // 读取设备文件
  const fileContent = await device.pull('/data/local/tmp/test-file.txt');
  console.log('文件内容:', fileContent.toString());
  
  // 执行 shell 命令
  const batteryStatus = await device.shell('dumpsys battery');
  console.log('电池状态:', batteryStatus.toString());
  
  // 安装应用（APK）
  await device.shell('pm install -r /data/local/tmp/app-debug.apk');
}

2.3 iOS 特有功能实现

// iOS 设备操作示例
import { chromium } from 'playwright';

(async () => {
  // 连接已启动的 WebDriverAgent
  const browser = await chromium.connect({
    wsEndpoint: 'ws://localhost:8100'  // WDA 默认端口
  });
  
  // 创建上下文（模拟设备特性）
  const context = await browser.newContext({
    viewport: { width: 375, height: 812 },
    deviceScaleFactor: 3,
    isMobile: true,
    hasTouch: true
  });
  
  // 打开 Safari 并操作
  const page = await context.newPage();
  await page.goto('https://m.taobao.com');
  
  // 模拟触摸操作
  await page.touchscreen.tap(187, 406);  // 点击屏幕中心
  
  // 获取应用日志
  const logs = await browser.on('console', msg => 
    console.log(`[iOS Log] ${msg.text()}`)
  );
  
  await browser.close();
})();

三、自动化测试框架设计

3.1 测试架构设计

flowchart TD
    A[测试用例] --> B[设备管理器]
    B --> C{设备类型}
    C -->|Android| D[ADB 连接池]
    C -->|iOS| E[WebDriverAgent 代理]
    D & E --> F[Playwright 会话]
    F --> G[页面操作模块]
    F --> H[设备控制模块]
    G & H --> I[结果验证模块]
    I --> J[测试报告生成]

3.2 多设备并行测试配置

// playwright.config.js
const { devices } = require('@playwright/test');

module.exports = {
  testDir: './tests',
  timeout: 30 * 1000,
  workers: 2,  // 根据设备数量调整
  projects: [
    {
      name: 'Android-Pixel6',
      use: {
        deviceSerialNumber: 'emulator-5554',  // 设备序列号
        launchOptions: {
          channel: 'chrome'
        }
      }
    },
    {
      name: 'iOS-iPhone13',
      use: {
        deviceName: 'iPhone 13',  // 设备名称
        wdaEndpoint: 'ws://localhost:8100'
      }
    }
  ]
};

3.3 测试用例示例：电商 App 登录流程

// tests/e2e/login.spec.ts
import { test, expect } from '@playwright/test';

test.describe('移动端登录流程', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/login');
  });

  test('使用有效凭证登录', async ({ page }) => {
    // 输入账号密码
    await page.fill('id=username', 'test-user');
    await page.fill('id=password', 'secure-pass123');
    
    // 点击登录按钮（处理可能的遮挡）
    await page.locator('id=login-btn').click({ force: true });
    
    // 验证登录成功
    await expect(page.locator('id=user-avatar')).toBeVisible({
      timeout: 15000  // 真机操作增加超时时间
    });
    
    // 验证跳转URL
    await expect(page).toHaveURL('/home');
  });

  test('验证密码错误提示', async ({ page }) => {
    await page.fill('id=username', 'test-user');
    await page.fill('id=password', 'wrong-pass');
    await page.click('id=login-btn');
    
    // 验证错误提示
    const errorToast = page.locator('xpath=//*[@text="密码错误，请重试"]');
    await expect(errorToast).toBeVisible();
    await expect(errorToast).toHaveText('密码错误，请重试');
  });
});

四、高级应用与性能优化

4.1 传感器模拟

// 模拟地理位置和网络状态
async function simulateDeviceConditions(device) {
  // 模拟 GPS 位置（北京天安门）
  await device.setGeolocation({ latitude: 39.9042, longitude: 116.4074 });
  
  // 模拟网络状态（4G）
  await device.setNetworkConditions({
    offline: false,
    download: 15 * 1024 * 1024,  // 15Mbps
    upload: 7 * 1024 * 1024,    // 7Mbps
    latency: 30                 // 30ms延迟
  });
  
  // 模拟电池状态（低电量）
  await device.setBatteryInfo({
    percentage: 15,
    isCharging: false
  });
}

4.2 测试报告与视频录制

// playwright.config.js 增强配置
module.exports = {
  reporter: [
    ['html', { open: 'never' }],  // 生成HTML报告
    ['json', { outputFile: 'test-results.json' }]
  ],
  use: {
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',  // 仅失败用例保留视频
    trace: 'retain-on-failure',  // 记录详细追踪信息
    videoSize: { width: 375, height: 812 }  // 适配移动设备
  }
};

4.3 CI/CD 集成方案

# .github/workflows/mobile-test.yml (GitHub Actions)
name: 移动端真机测试
on: [push]

jobs:
  android-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 18 }
      - run: npm ci
      - run: npx playwright install --with-deps
      
      - name: 启动 Android 模拟器
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 33
          script: adb devices
      
      - name: 执行测试
        run: npx playwright test --project=Android-Pixel6
      
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: android-test-results
          path: playwright-report/

  ios-test:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 18 }
      - run: npm ci
      - run: npx playwright install --with-deps
      
      - name: 启动 iOS 模拟器
        run: |
          xcrun simctl boot "iPhone 14"
          xcrun simctl list | grep Booted
      
      - name: 执行测试
        run: npx playwright test --project=iOS-iPhone13
      
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: ios-test-results
          path: playwright-report/

五、常见问题诊断与解决方案

5.1 设备连接问题排查

问题现象	可能原因	解决方案
ADB 无法识别设备	USB调试未启用	重新启用开发者选项中的USB调试
device unauthorized	信任弹窗未确认	重新连接USB并在设备上确认信任
WDA 启动失败	签名配置错误	检查Xcode签名设置并重建项目
连接超时	网络防火墙限制	关闭VPN或添加5037端口例外规则

5.2 性能优化策略

1. 测试执行提速

   // 复用浏览器上下文
   test.use({ contextOptions: { reuseExistingServer: true } });
   

2. 减少不必要的操作

   // 仅首次登录时执行完整流程
   test.describe.configure({ retries: 0 });  // 减少重试次数
   

3. 并行测试优化

   // 按设备分组执行测试
   module.exports = {
     projects: [
       { name: 'group1', testMatch: 'tests/group1/**/*.spec.ts' },
       { name: 'group2', testMatch: 'tests/group2/**/*.spec.ts' }
     ]
   };
   

六、总结与未来展望

Playwright 移动端真机测试方案通过统一的 API 抽象，解决了传统测试工具跨平台兼容性差、配置复杂的问题。随着 WebDriver BiDi 标准的普及，未来我们将看到：

1. 更深度的设备集成 - 直接控制相机、麦克风等硬件
2. AI 驱动的测试生成 - 基于应用行为自动生成测试用例
3. 实时性能监控 - 整合 Lighthouse 等性能分析工具

建议测试团队优先在以下场景应用本文方案：

• 需要验证传感器交互的场景（地图应用、AR功能）
• 支付流程等关键路径的兼容性验证
• 用户体验相关的手势操作测试

通过本文提供的工具链和最佳实践，你可以构建一套稳定、高效的移动端测试体系，将回归测试时间从小时级缩短到分钟级，同时显著提升测试覆盖率和问题发现能力。

行动指南：

1. 今天：按本文步骤配置至少1台Android/iOS设备
2. 本周：实现3个核心场景的自动化测试
3. 本月：将真机测试集成到CI/CD流程

记住，移动端测试的目标不仅是发现bug，更是保障用户在真实环境中的体验一致性。Playwright 为我们提供了实现这一目标的强大工具，而本文的实战经验将帮助你快速掌握并发挥其最大价值。