MacOS下Playwright强制使用Chromium的解决方案

1. 问题背景与现象描述

最近在MacOS环境下使用Playwright进行Web自动化测试时，遇到了一个颇为棘手的问题：明明在配置文件中指定了使用Chromium浏览器，但每次启动测试脚本时，系统却总是自动调用Safari浏览器执行测试用例。这个问题直接影响了我们的持续集成流程，因为测试环境并未安装Safari的WebDriver，导致每次运行都会报错。

具体现象表现为：

• 在setting.json配置文件中已明确设置"browser": "chromium"
• 工程启动日志显示实际调用的却是Safari浏览器
• 手动检查代码逻辑和配置文件均未发现明显错误
• 系统环境为MacOS Monterey 12.6，Playwright版本1.28.0

提示：这个问题在Playwright社区中并不常见，官方文档也没有明确说明这种特殊情况，因此排查过程颇费周折。

2. 问题排查过程全记录

2.1 初步检查配置文件

首先检查了项目中的两个关键配置文件：

1. setting.json 核心配置：

json复制{
  "browser": "chromium",
  "headless": false,
  "viewport": {
    "width": 1920,
    "height": 1080
  }
}

2. cline_mcp_setting.json 环境配置：

json复制{
  "env": "test",
  "base_url": "http://localhost:8080",
  "timeout": 30000
}

从配置上看，浏览器类型明确指定为Chromium，理论上不应该出现调用Safari的情况。于是开始怀疑是否是代码中有硬编码覆盖了配置。

2.2 代码走查与调试

对测试启动代码进行了详细检查，特别是浏览器初始化的部分：

python复制import playwright
from playwright.sync_api import sync_playwright

def launch_browser():
    with sync_playwright() as p:
        # 理论上应该从配置读取浏览器类型
        browser = p.chromium.launch(headless=False)
        context = browser.new_context()
        page = context.new_page()
        # ...后续测试逻辑

即使强制指定使用chromium，运行时仍然调用了Safari。这让我们意识到问题可能不在代码层面。

2.3 系统环境深度排查

通过以下命令检查系统默认浏览器设置：

bash复制defaults read com.apple.Safari DefaultBrowser

输出显示：

code复制Safari

进一步检查Playwright的浏览器发现逻辑：

python复制from playwright.__main__ import install
print(install.installed_browsers())

输出确认已正确安装Chromium：

code复制['chromium', 'firefox', 'webkit']

3. 问题根源与解决方案

3.1 根本原因分析

经过多次测试验证，发现问题根源在于：

MacOS系统的默认浏览器设置会覆盖Playwright的配置。当系统默认浏览器为Safari时，即使代码和配置明确指定使用Chromium，Playwright在某些情况下仍会优先尝试使用系统默认浏览器。

这种设计可能是为了：

1. 提供更好的本地集成体验
2. 确保浏览器调用总能成功（假设系统默认浏览器总是可用）
3. 兼容某些特殊测试场景

3.2 三种解决方案对比

根据实际测试，我们总结了三种可行的解决方案：

3.3 推荐解决方案实现

对于大多数项目，我们推荐代码强制指定+环境变量覆盖的组合方案：

1. 修改启动代码：

python复制def launch_browser():
    with sync_playwright() as p:
        # 从环境变量读取浏览器类型，默认chromium
        browser_type = os.getenv('PLAYWRIGHT_BROWSER', 'chromium')
        browser = getattr(p, browser_type).launch(
            headless=os.getenv('PLAYWRIGHT_HEADLESS', 'false').lower() == 'true'
        )
        # ...后续逻辑

2. 在CI/CD配置中显式设置环境变量：

yaml复制env:
  PLAYWRIGHT_BROWSER: "chromium"
  PLAYWRIGHT_HEADLESS: "true"

3. 本地开发时可通过.env文件覆盖：

code复制PLAYWRIGHT_BROWSER=firefox
PLAYWRIGHT_HEADLESS=false

4. 深度技术解析与避坑指南

4.1 Playwright的浏览器选择机制

Playwright的浏览器选择遵循以下优先级：

1. 代码显式指定的浏览器类型（最高优先级）
2. 命令行参数传递的--browser选项
3. 配置文件中的browser设置
4. 系统默认浏览器（最低优先级）

在MacOS环境下，当上述1-3项未明确指定或指定无效时，会意外触发第4级选择策略。

4.2 常见配置陷阱

1. JSON配置格式问题：

   • 确保配置文件是有效的JSON
   • 字符串值必须使用双引号
   • 避免尾随逗号

2. 环境变量冲突：

   bash复制# 错误的变量名（大小写敏感）
   export playwright_browser=chromium
   
   # 正确的变量名
   export PLAYWRIGHT_BROWSER=chromium
   

3. 浏览器安装验证：

   bash复制# 检查已安装的浏览器
   npx playwright install --dry-run
   
   # 安装特定浏览器
   npx playwright install chromium
   

4.3 跨平台兼容性处理

为确保脚本在Windows/Linux/Mac上行为一致，建议：

1. 在conftest.py中添加平台检查：

python复制import platform

@pytest.fixture(scope="session")
def browser_type(pytestconfig):
    if platform.system() == "Darwin":
        return "chromium"  # 在Mac上强制使用chromium
    return pytestconfig.getoption("--browser") or "chromium"

2. 使用Playwright的Docker镜像保证环境一致：

dockerfile复制FROM mcr.microsoft.com/playwright:v1.28.0-focal
WORKDIR /tests
COPY . .
CMD ["npm", "test"]

5. 高级调试技巧与性能优化

5.1 启用详细日志

在调试浏览器选择问题时，可以启用Playwright的调试日志：

python复制import os
os.environ['DEBUG'] = 'pw:api'  # 启用API调用日志
os.environ['PLAYWRIGHT_BROWSER'] = 'chromium'  # 显式覆盖

with sync_playwright() as p:
    browser = p.chromium.launch()

日志会显示浏览器选择的全过程，帮助定位问题。

5.2 浏览器启动参数优化

针对不同测试需求，可以调整启动参数：

python复制browser = p.chromium.launch(
    headless=False,
    args=[
        '--disable-blink-features=AutomationControlled',
        '--start-maximized'
    ],
    ignore_default_args=['--enable-automation']
)

5.3 多浏览器并行测试方案

对于需要跨浏览器测试的场景，推荐使用以下模式：

python复制import pytest

@pytest.mark.parametrize("browser_type", ["chromium", "firefox"])
def test_example(browser_type):
    with sync_playwright() as p:
        browser = getattr(p, browser_type).launch()
        page = browser.new_page()
        # 测试逻辑
        browser.close()

我在实际项目中发现，保持浏览器选择逻辑的显式和一致是避免这类问题的关键。特别是在团队协作环境中，建议在项目README中明确记录浏览器选择策略，并在CI流水线中设置强制检查。