browserstack

BrowserStack 集成

在 BrowserStack 云端网格上运行 Playwright 测试，进行跨浏览器和跨设备测试。

前提条件

必须设置环境变量：

• BROWSERSTACK_USERNAME — 你的 BrowserStack 用户名
• BROWSERSTACK_ACCESS_KEY — 你的访问密钥

如果未设置，请告知用户如何从 browserstack.com/accounts/settings 获取these，并停止操作。

BrowserStack MCP 服务未自动注册（issue #978）。 pw-browserstack 已从插件的 .mcp.json 中移除，因为它对所有用户都无法连接（插件不包含 node_modules）。下文使用的 browserstack_* MCP 工具以及 /pw:browserstack 命令，在手动启用之前都会因“tool not found”而失败，具体参见插件 CLAUDE.md 中的 Integrations 部分（cd integrations/browserstack-mcp && npm install，然后在你自己的用户/项目 MCP 配置中注册该服务）。仅设置环境变量是不够的。

功能

1. 配置 BrowserStack

/pw:browserstack setup

步骤：

1. 检查当前的 playwright.config.ts
2. 添加 BrowserStack connect 选项：

// Add to playwright.config.ts
import { defineConfig } from '@playwright/test';

const isBS = !!process.env.BROWSERSTACK_USERNAME;

export default defineConfig({
  // ... existing config
  projects: isBS ? [
    {
      name: "chromelatestwindows-11",
      use: {
        connectOptions: {
          wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(JSON.stringify({
            'browser': 'chrome',
            'browser_version': 'latest',
            'os': 'Windows',
            'os_version': '11',
            'browserstack.username': process.env.BROWSERSTACK_USERNAME,
            'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY,
          }))}`,
        },
      },
    },
    {
      name: "firefoxlatestwindows-11",
      use: {
        connectOptions: {
          wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(JSON.stringify({
            'browser': 'playwright-firefox',
            'browser_version': 'latest',
            'os': 'Windows',
            'os_version': '11',
            'browserstack.username': process.env.BROWSERSTACK_USERNAME,
            'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY,
          }))}`,
        },
      },
    },
    {
      name: "webkitlatestos-x-ventura",
      use: {
        connectOptions: {
          wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(JSON.stringify({
            'browser': 'playwright-webkit',
            'browser_version': 'latest',
            'os': 'OS X',
            'os_version': 'Ventura',
            'browserstack.username': process.env.BROWSERSTACK_USERNAME,
            'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY,
          }))}`,
        },
      },
    },
  ] : [
    // ... local projects fallback
  ],
});

3. 添加 npm 脚本："test:e2e:cloud": "npx playwright test --project='chrome@*' --project='firefox@*' --project='webkit@*'"

2. 在 BrowserStack 上运行测试

/pw:browserstack run

步骤：

1. 验证凭据已设置
2. 使用 BrowserStack 项目运行测试：

   BROWSERSTACK_USERNAME=$BROWSERSTACK_USERNAME \
   BROWSERSTACK_ACCESS_KEY=$BROWSERSTACK_ACCESS_KEY \
   npx playwright test --project='chrome@*' --project='firefox@*'
   

3. 监控执行过程
4. 按浏览器报告结果

3. 获取构建结果

/pw:browserstack results

步骤：

1. 调用 browserstack_get_builds MCP 工具
2. 获取最新构建的会话
3. 对每个会话：
   • 状态（通过/失败）
   • 浏览器和操作系统
   • 持续时间
   • 视频 URL
   • 日志 URL
4. 整理为汇总表格

4. 检查可用浏览器

/pw:browserstack browsers

步骤：

1. 调用 browserstack_get_browsers MCP 工具
2. 筛选兼容 Playwright 的浏览器
3. 显示可用的浏览器/操作系统组合

5. 本地测试

/pw:browserstack local

用于测试位于防火墙后的 localhost 或预发布环境：

1. 安装 BrowserStack Local：npm install -D browserstack-local
2. 在配置中添加本地隧道
3. 提供设置说明

使用的 MCP 工具

工具	使用时机
browserstack_get_plan	检查账户限制
browserstack_get_browsers	列出可用浏览器
browserstack_get_builds	列出最近的构建
browserstack_get_sessions	获取构建中的会话
browserstack_get_session	获取会话详情（视频、日志）
browserstack_update_session	标记通过/失败
browserstack_get_logs	获取文本/网络日志

输出

• 跨浏览器测试结果表格
• 每个浏览器的通过/失败状态
• 指向 BrowserStack 仪表板视频/截图的链接
• 高亮显示特定浏览器的失败项