移动端浏览器自动化：Playwright for Android 实战

在移动互联网时代，移动端 Web 应用的质量直接影响用户体验。传统的移动端自动化工具如 Appium 虽然功能强大，但配置复杂、执行速度慢，且学习曲线陡峭。微软推出的 Playwright 框架凭借其现代的 API 设计、出色的稳定性和卓越的性能，迅速成为 Web 自动化测试的首选工具。本文将深入探讨 Playwright 在 Android 平台上的应用，从环境搭建到实战案例，全面展示如何利用 Playwright 实现高效的移动端浏览器自动化。

一、Playwright for Android 概述

Playwright 是微软开发的开源 Web 自动化测试框架，支持 Chromium、Firefox 和 WebKit 三大浏览器引擎，提供统一的 API 接口。自 2020 年发布以来，Playwright 不断拓展其能力边界，引入了对 Android 平台的实验性支持，能够直接控制 Android 设备上的 Chrome 浏览器和 WebView 组件Playwright。

1.1 核心优势

• 统一 API 体验：与桌面端 Web 自动化使用完全相同的 API，无需学习新的语法
• 直接浏览器控制：通过 CDP 协议直接与浏览器通信，执行速度远超 Appium
• 内置等待机制：自动等待元素就绪，大幅减少不稳定测试（flaky tests）
• 丰富的调试工具：支持截图、视频录制、追踪功能，问题定位更便捷
• 多语言支持：支持 JavaScript/TypeScript、Python、Java 和.NET
• 无需额外服务器：不依赖 Appium Server，直接通过 ADB 与设备通信

1.2 适用场景

• 移动 Web 应用的功能测试和回归测试
• 混合应用（Hybrid App）中的 WebView 部分测试
• 响应式 Web 设计在真实 Android 设备上的验证
• PWA（渐进式 Web 应用）的自动化测试
• 跨平台 Web 应用的一致性测试

二、环境搭建

2.1 开发环境准备

首先需要安装以下基础工具：

1. Node.js ：推荐 LTS 版本（v18+），可从nodejs.org下载
2. ADB（Android Debug Bridge）：连接 Android 设备的核心工具

ADB 安装方式：

• 推荐方式：安装 Android Studio，自动配置 SDK 和 ADB
• 轻量方式 ：单独安装平台工具
  • macOS：brew install android-platform-tools
  • Windows：下载ADB 压缩包并配置环境变量
  • Linux：sudo apt-get install android-sdk-platform-tools

配置环境变量：

• 设置ANDROID_HOME指向 SDK 安装目录
• 将$ANDROID_HOME/platform-tools添加到系统PATH中

验证安装：

bash

运行

adb version
adb devices

2.2 Android 设备配置

1. 开启开发者选项：

   • 进入「设置」→「关于手机」
   • 连续点击「版本号」7 次，直到提示 "开发者模式已启用"

2. 配置开发者选项：

   • 进入「设置」→「开发者选项」
   • 开启「USB 调试」
   • 开启「USB 安装」（部分设备需要）
   • 开启「保持唤醒状态」（可选，防止设备休眠）
   • 开启「USB 调试（安全设置）」（部分小米设备需要）

3. Chrome 浏览器配置：

   • 确保设备上安装了 Chrome 87 或更高版本
   • 打开 Chrome 浏览器，访问chrome://flags
   • 搜索并启用 "Enable command line on non-rooted devices"Playwright
   • 重启 Chrome 浏览器使设置生效

2.3 Playwright 安装

创建新项目并安装 Playwright：

bash

运行

# 创建项目目录
mkdir playwright-android-demo
cd playwright-android-demo

# 初始化Node.js项目
npm init -y

# 安装Playwright
npm install playwright

验证安装：创建一个简单的测试脚本test-connection.js

javascript

运行

const { _android: android } = require('playwright');

(async () => {
  try {
    // 列出所有已连接的Android设备
    const devices = await android.devices();
    console.log(`发现 ${devices.length} 台已连接的Android设备`);
    
    if (devices.length === 0) {
      console.log('未检测到任何设备，请检查USB连接和开发者选项设置');
      return;
    }
    
    // 连接第一台设备
    const device = devices[0];
    console.log(`设备型号: ${device.model()}`);
    console.log(`设备序列号: ${device.serial()}`);
    console.log(`Android版本: ${device.sdkVersion()}`);
    
    // 关闭连接
    await device.close();
    console.log('设备连接测试成功！');
  } catch (error) {
    console.error('连接失败:', error.message);
  }
})();

运行脚本：

bash

运行

node test-connection.js

如果一切配置正确，你将看到设备信息输出。

三、核心概念与 API

3.1 设备连接与管理

Playwright 通过_android对象提供 Android 设备的访问能力：

javascript

运行

const { _android: android } = require('playwright');

// 获取所有已连接设备
const devices = await android.devices();

// 连接指定设备（通过序列号）
const device = await android.connect({
  deviceSerialNumber: 'your-device-serial',
  adbPort: 5037 // 默认ADB端口
});

// 设备基本信息
console.log('型号:', device.model());
console.log('序列号:', device.serial());
console.log('SDK版本:', device.sdkVersion());

// 关闭设备连接
await device.close();

3.2 浏览器启动与上下文

Playwright 可以直接在 Android 设备上启动 Chrome 浏览器，并创建浏览器上下文：

javascript

运行

// 强制停止已运行的Chrome（避免冲突）
await device.shell('am force-stop com.android.chrome');

// 启动Chrome浏览器并创建上下文
const context = await device.launchBrowser({
  args: ['--disable-popup-blocking', '--no-first-run'],
  viewport: { width: 390, height: 844 }, // Pixel 8尺寸
  locale: 'zh-CN',
  timezoneId: 'Asia/Shanghai'
});

// 创建新页面
const page = await context.newPage();

// 与桌面端完全相同的API
await page.goto('https://m.baidu.com');
await page.fill('input[name="word"]', 'Playwright Android');
await page.click('input[type="submit"]');
await page.waitForNavigation();

// 截图
await page.screenshot({ path: 'baidu-search.png', fullPage: true });

// 关闭上下文
await context.close();

3.3 WebView 自动化

Playwright 最强大的功能之一是能够自动化原生应用中的 WebView 组件：

javascript

运行

// 启动包含WebView的应用
await device.shell('am start -n org.chromium.webview_shell/.WebViewShellActivity');

// 等待WebView出现
const webview = await device.webView({ pkg: 'org.chromium.webview_shell' });

// 获取WebView中的页面对象
const page = await webview.page();

// 现在可以使用所有Playwright Web API
await page.goto('https://github.com/microsoft/playwright');
console.log('页面标题:', await page.title());

// 与WebView中的元素交互
await page.click('a[href="/microsoft/playwright/issues"]');
await page.waitForNavigation();

// 截图WebView内容
await page.screenshot({ path: 'webview-github.png' });

3.4 设备级操作

除了浏览器控制，Playwright 还提供了设备级别的操作能力：

javascript

运行

// 执行Shell命令
const output = await device.shell('ls /sdcard/');
console.log('SD卡内容:', output);

// 设备截图（整个屏幕）
await device.screenshot({ path: 'device-fullscreen.png' });

// 模拟按键事件
await device.press('BACK'); // 返回键
await device.press('HOME'); // 主页键
await device.press('MENU'); // 菜单键
await device.press('VOLUME_UP'); // 音量加

// 模拟触摸和滑动
await device.tap({ x: 100, y: 200 }); // 点击坐标
await device.swipe({ 
  startX: 200, startY: 500, 
  endX: 200, endY: 200, 
  duration: 500 
}); // 向上滑动

// 文件传输
// 推送文件到设备
await device.push(Buffer.from('Hello Playwright!'), '/sdcard/test.txt');

// 从设备拉取文件
const fileContent = await device.pull('/sdcard/test.txt');
console.log('文件内容:', fileContent.toString());

四、实战案例

4.1 案例一：移动 Web 应用登录流程测试

让我们编写一个完整的测试脚本，模拟用户在移动 Web 应用上的登录流程：

javascript

运行

const { _android: android } = require('playwright');

async function testMobileLogin() {
  // 连接设备
  const [device] = await android.devices();
  console.log(`连接到设备: ${device.model()}`);
  
  try {
    // 启动Chrome浏览器
    await device.shell('am force-stop com.android.chrome');
    const context = await device.launchBrowser();
    const page = await context.newPage();
    
    // 访问登录页面
    console.log('访问登录页面...');
    await page.goto('https://example.com/mobile/login');
    
    // 等待页面加载完成
    await page.waitForLoadState('networkidle');
    
    // 输入用户名和密码
    console.log('输入登录信息...');
    await page.fill('input[name="username"]', 'testuser');
    await page.fill('input[name="password"]', 'testpassword123');
    
    // 点击登录按钮
    console.log('点击登录按钮...');
    await Promise.all([
      page.waitForNavigation({ waitUntil: 'networkidle' }),
      page.click('button[type="submit"]')
    ]);
    
    // 验证登录成功
    const welcomeText = await page.locator('.welcome-message').textContent();
    if (welcomeText.includes('欢迎回来，testuser')) {
      console.log('✅ 登录测试通过！');
    } else {
      console.log('❌ 登录测试失败！');
    }
    
    // 截图保存结果
    await page.screenshot({ path: 'login-success.png' });
    
    // 测试登出功能
    console.log('测试登出功能...');
    await page.click('.user-menu');
    await page.click('text=退出登录');
    await page.waitForNavigation();
    
    // 验证已登出
    const loginButton = await page.locator('button[type="submit"]').isVisible();
    if (loginButton) {
      console.log('✅ 登出测试通过！');
    } else {
      console.log('❌ 登出测试失败！');
    }
    
    await context.close();
    console.log('所有测试完成！');
  } catch (error) {
    console.error('测试过程中发生错误:', error);
    // 错误时截图
    await device.screenshot({ path: 'test-error.png' });
  } finally {
    await device.close();
  }
}

testMobileLogin();

4.2 案例二：混合应用 WebView 自动化测试

这个案例展示如何测试一个包含 WebView 的原生 Android 应用：

javascript

运行

const { _android: android } = require('playwright');

async function testHybridAppWebView() {
  const [device] = await android.devices();
  console.log(`连接到设备: ${device.model()}`);
  
  try {
    // 启动混合应用
    console.log('启动混合应用...');
    await device.shell('am force-stop com.example.hybridapp');
    await device.shell('am start -n com.example.hybridapp/.MainActivity');
    
    // 等待应用启动并出现WebView
    console.log('等待WebView加载...');
    const webview = await device.webView({ 
      pkg: 'com.example.hybridapp',
      timeout: 10000
    });
    
    const page = await webview.page();
    console.log('WebView连接成功！');
    
    // 等待WebView内容加载
    await page.waitForLoadState('domcontentloaded');
    
    // 与WebView中的内容交互
    console.log('测试WebView中的表单提交...');
    await page.fill('#name', '张三');
    await page.fill('#email', 'zhangsan@example.com');
    await page.selectOption('#city', { label: '北京' });
    await page.check('#agree-terms');
    
    // 提交表单
    await Promise.all([
      page.waitForNavigation(),
      page.click('#submit-button')
    ]);
    
    // 验证提交结果
    const successMessage = await page.locator('.success-message').textContent();
    console.log('提交结果:', successMessage);
    
    // 测试WebView与原生应用的交互
    console.log('测试WebView与原生交互...');
    await page.click('#open-native-dialog');
    
    // 使用设备级API点击原生弹窗的"确定"按钮
    await device.locator('text=确定').click({ timeout: 5000 });
    
    // 验证WebView收到了原生应用的回调
    const callbackResult = await page.locator('#callback-result').textContent();
    console.log('原生回调结果:', callbackResult);
    
    console.log('✅ 混合应用WebView测试通过！');
  } catch (error) {
    console.error('测试失败:', error);
    await device.screenshot({ path: 'hybrid-app-error.png' });
  } finally {
    await device.close();
  }
}

testHybridAppWebView();

4.3 案例三：设备级操作与多场景测试

这个案例展示了如何结合设备级操作进行更复杂的测试：

javascript

运行

const { _android: android } = require('playwright');

async function testDeviceLevelOperations() {
  const [device] = await android.devices();
  console.log(`连接到设备: ${device.model()}`);
  
  try {
    // 测试1：切换网络状态
    console.log('\n测试1：切换网络状态');
    await device.shell('svc wifi disable');
    await page.waitForTimeout(2000);
    await device.shell('svc wifi enable');
    await page.waitForTimeout(2000);
    console.log('✅ 网络切换测试通过');
    
    // 测试2：模拟不同屏幕方向
    console.log('\n测试2：屏幕方向测试');
    await device.shell('settings put system user_rotation 1'); // 横屏
    await page.waitForTimeout(1000);
    await device.screenshot({ path: 'landscape.png' });
    
    await device.shell('settings put system user_rotation 0'); // 竖屏
    await page.waitForTimeout(1000);
    await device.screenshot({ path: 'portrait.png' });
    console.log('✅ 屏幕方向测试通过');
    
    // 测试3：多页面切换
    console.log('\n测试3：多页面切换测试');
    const context = await device.launchBrowser();
    
    const page1 = await context.newPage();
    await page1.goto('https://www.baidu.com');
    console.log('页面1标题:', await page1.title());
    
    const page2 = await context.newPage();
    await page2.goto('https://www.github.com');
    console.log('页面2标题:', await page2.title());
    
    // 切换回第一个页面
    await page1.bringToFront();
    await page1.fill('input[name="wd"]', 'Playwright Android');
    await page1.press('Enter');
    await page1.waitForNavigation();
    
    console.log('✅ 多页面切换测试通过');
    
    // 测试4：文件下载测试
    console.log('\n测试4：文件下载测试');
    const downloadPromise = page1.waitForEvent('download');
    await page1.click('a[href$=".pdf"]'); // 点击PDF下载链接
    const download = await downloadPromise;
    
    console.log('下载文件名:', download.suggestedFilename());
    await download.saveAs(`./downloads/${download.suggestedFilename()}`);
    console.log('✅ 文件下载测试通过');
    
    await context.close();
    console.log('\n所有设备级操作测试完成！');
  } catch (error) {
    console.error('测试失败:', error);
  } finally {
    await device.close();
  }
}

testDeviceLevelOperations();

五、高级用法

5.1 多设备并行测试

Playwright 支持同时连接多台 Android 设备进行并行测试：

javascript

运行

const { _android: android } = require('playwright');

async function runTestOnDevice(deviceSerial, testName) {
  const device = await android.connect({ deviceSerialNumber: deviceSerial });
  console.log(`在设备 ${device.model()} (${deviceSerial}) 上运行测试: ${testName}`);
  
  try {
    const context = await device.launchBrowser();
    const page = await context.newPage();
    
    await page.goto('https://example.com');
    await page.screenshot({ path: `${testName}-${deviceSerial}.png` });
    
    await context.close();
    console.log(`✅ 设备 ${deviceSerial} 测试完成`);
  } catch (error) {
    console.error(`❌ 设备 ${deviceSerial} 测试失败:`, error);
  } finally {
    await device.close();
  }
}

async function parallelTest() {
  const devices = await android.devices();
  console.log(`发现 ${devices.length} 台设备，开始并行测试...`);
  
  const testPromises = devices.map((device, index) => 
    runTestOnDevice(device.serial(), `test-${index + 1}`)
  );
  
  await Promise.all(testPromises);
  console.log('所有并行测试完成！');
}

parallelTest();

5.2 云设备集成

Playwright 可以与云测试平台（如 LambdaTest、BrowserStack）集成，在远程真实设备上运行测试：

javascript

运行

const { _android: android } = require('playwright');

async function testOnLambdaTest() {
  const capabilities = {
    "LT:Options": {
      "platformName": "android",
      "deviceName": "Pixel 8",
      "platformVersion": "14",
      "isRealMobile": true,
      "build": "Playwright Android Build",
      "name": "移动Web测试",
      "user": process.env.LT_USERNAME,
      "accessKey": process.env.LT_ACCESS_KEY,
      "network": true,
      "video": true,
      "console": true
    }
  };
  
  const device = await android.connect(
    `wss://cdp.lambdatest.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
  );
  
  console.log('连接到LambdaTest云设备成功！');
  
  try {
    const context = await device.launchBrowser();
    const page = await context.newPage();
    
    await page.goto('https://m.baidu.com');
    await page.fill('input[name="word"]', '云测试');
    await page.click('input[type="submit"]');
    await page.waitForNavigation();
    
    console.log('页面标题:', await page.title());
    await page.screenshot({ path: 'lambda-test-result.png' });
    
    await context.close();
    console.log('✅ 云设备测试通过！');
  } catch (error) {
    console.error('云设备测试失败:', error);
  } finally {
    await device.close();
  }
}

testOnLambdaTest();

5.3 CI/CD 集成

将 Playwright Android 测试集成到 CI/CD 流水线中：

GitHub Actions 配置示例 （.github/workflows/android-test.yml）：

yaml

name: Android Playwright Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Setup Android SDK
        uses: android-actions/setup-android@v3
        with:
          api-level: 34
          build-tools: 34.0.0
      
      - name: Create AVD
        run: |
          sdkmanager "system-images;android-34;google_apis;x86_64"
          echo "no" | avdmanager create avd -n test-avd -k "system-images;android-34;google_apis;x86_64" --device "pixel_8"
      
      - name: Start emulator
        run: |
          emulator -avd test-avd -no-window -no-audio -no-boot-anim &
          adb wait-for-device
          adb shell settings put global window_animation_scale 0
          adb shell settings put global transition_animation_scale 0
          adb shell settings put global animator_duration_scale 0
      
      - name: Install Chrome
        run: |
          wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
          adb install google-chrome-stable_current_amd64.deb
      
      - name: Run Playwright tests
        run: npm test
      
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: |
            screenshots/
            videos/
            test-results/

六、Playwright Android vs Appium 对比

表格

特性	Playwright Android	Appium
主要用途	移动 Web、WebView、PWA 测试	原生应用、混合应用、移动 Web 测试
架构	直接通过 ADB 和 CDP 与浏览器通信	客户端 - 服务器架构，依赖 Appium Server
执行速度	非常快（直接控制浏览器）	较慢（需要通过多个中间层）
配置复杂度	简单（仅需 ADB）	复杂（需要 Appium Server、驱动、SDK）
API 设计	现代、简洁、统一	基于 WebDriver 协议，相对繁琐
原生应用支持	有限（仅 WebView 部分）	完整支持
调试能力	强大（内置追踪、视频、截图）	有限，需要额外工具
学习曲线	平缓（与桌面 Web 相同 API）	陡峭
跨平台支持	目前仅支持 Android	支持 Android 和 iOS
社区生态	快速增长	成熟庞大

选择建议：

• 如果主要测试移动 Web 应用 或混合应用的 WebView 部分，优先选择 Playwright
• 如果需要测试纯原生应用 或iOS 应用，Appium 仍然是更好的选择
• 可以结合使用：用 Playwright 测试 Web 部分，用 Appium 测试原生部分

七、常见问题与解决方案

7.1 设备连接问题

问题 ：adb devices能看到设备，但 Playwright 无法连接 解决方案：

• 确保设备已接受 USB 调试授权
• 重启 ADB 服务：adb kill-server && adb start-server
• 检查 Chrome 版本是否为 87+
• 确保在chrome://flags中启用了 "Enable command line on non-rooted devices"
• 尝试使用不同的 USB 线和 USB 端口

7.2 WebView 无法找到

问题 ：device.webView()超时，无法找到 WebView 解决方案：

• 确保应用已正确启动
• 检查包名是否正确：adb shell dumpsys window | grep mCurrentFocus
• 增加超时时间：device.webView({ timeout: 20000 })
• 确保 WebView 已启用调试模式：在应用代码中添加WebView.setWebContentsDebuggingEnabled(true)

7.3 权限弹窗处理

问题 ：应用请求权限时，测试脚本卡住 解决方案：

javascript

运行

// 处理位置权限弹窗
try {
  await device.locator('text=允许').click({ timeout: 3000 });
} catch (e) {
  console.log('未检测到位置权限弹窗');
}

// 或者使用更通用的方法
async function handlePermissionPopup(device) {
  const permissionButtons = ['允许', '始终允许', '仅在使用中允许'];
  for (const buttonText of permissionButtons) {
    try {
      await device.locator(`text=${buttonText}`).click({ timeout: 1000 });
      return true;
    } catch (e) {
      continue;
    }
  }
  return false;
}

7.4 性能优化技巧

• 强制停止 Chrome ：每次测试前使用am force-stop com.android.chrome确保干净的环境
• 禁用动画：在开发者选项中禁用窗口动画、过渡动画和动画时长缩放
• 使用无头模式 ：虽然 Android 不支持真正的无头模式，但可以使用--headless=new参数
• 合理设置超时：根据设备性能调整超时时间，避免不必要的等待
• 并行测试：利用多设备并行执行提高测试效率

八、最佳实践

1. 保持测试独立性：每个测试应该独立运行，不依赖其他测试的结果
2. 使用页面对象模式：将页面元素和操作封装成页面对象，提高代码可维护性
3. 合理使用等待 ：优先使用 Playwright 的自动等待机制，避免使用waitForTimeout
4. 完善的错误处理：在测试失败时自动截图、录制视频，便于问题定位
5. 参数化测试：使用不同的测试数据覆盖更多场景
6. 定期清理设备：测试完成后清理应用数据和缓存，避免影响后续测试
7. 结合设备模拟：在开发阶段使用 Playwright 的设备模拟功能快速验证，在 CI 阶段使用真实设备
8. 版本控制：锁定 Playwright 和 Chrome 的版本，避免因版本更新导致测试失败

九、总结与展望

Playwright for Android 为移动端浏览器自动化带来了全新的体验。它继承了 Playwright 在桌面端的所有优势，提供了统一的 API、出色的性能和强大的调试能力。虽然目前仍处于实验阶段，且主要专注于 Web 和 WebView 测试，但它已经能够满足大多数移动 Web 应用的自动化需求。

随着微软的持续投入和社区的不断发展，我们可以期待 Playwright 在移动端的能力会进一步增强。未来可能会看到：

• 对 iOS 平台的支持
• 更完善的原生应用自动化能力
• 更好的性能和稳定性
• 与更多云测试平台的集成

对于开发和测试团队来说，现在是开始探索和采用 Playwright for Android 的好时机。它不仅能够提高测试效率，还能让团队从繁琐的配置和维护工作中解放出来，专注于编写高质量的测试用例。