1. 项目概述为什么是Python与Playwright最近几年自动化测试领域可以说是“卷”得飞起。从早期的QTP、Selenium到后来的Cypress、Puppeteer工具层出不穷。但如果你问我现在要上手一个兼顾Web、移动端H5、桌面应用并且对跨平台Windows/Linux/macOS支持友好上手又快的自动化框架我会毫不犹豫地推荐Python Playwright这个组合。我最早接触Playwright是在一个需要同时覆盖Windows服务器和Linux CI/CD环境的项目中。当时团队还在用Selenium每次环境迁移、驱动版本匹配、浏览器兼容性都是一场“灾难”。Playwright的出现几乎把这些问题都打包解决了。它内置了Chromium、Firefox和WebKit三大浏览器引擎通过一个统一的API进行控制并且由微软官方维护生态和稳定性都很有保障。用Python来驱动它更是把“简洁高效”发挥到了极致——不需要复杂的WebDriver管理一条命令就能装好所有环境。所以这篇内容就是把我从零开始在Windows 10/11和主流Linux发行版如Ubuntu 20.04/22.04, CentOS 7/8上搭建一套稳定、可复用的PythonPlaywright自动化测试环境的完整过程、踩过的坑以及最佳实践毫无保留地分享出来。无论你是测试开发新手还是想从Selenium等框架迁移过来的老手都能在这里找到可以直接“抄作业”的配置。2. 环境搭建前的核心思路与工具选型在动手敲命令之前我们先花几分钟把整个搭建的逻辑理清楚。盲目操作很容易陷入“装是装上了但不知道为啥”或者“在我机器上好好的一上服务器就崩”的窘境。2.1 为什么选择Python Playwright首先我们得明确选型理由这决定了后续所有技术决策的走向。真正的“开箱即用” vs “依赖地狱”Selenium需要你单独下载浏览器、匹配对应版本的WebDriver并确保PATH配置正确。Playwright则通过playwright install命令自动下载匹配的、经过测试的浏览器二进制文件到本地缓存默认在~/.cache/ms-playwright完全屏蔽了底层差异。这对于需要统一测试环境的团队来说价值巨大。强大的异步支持与多上下文Playwright原生支持异步操作Async API对于现代单页应用SPA的等待逻辑处理得更优雅。同时它“浏览器上下文”Browser Context的概念比Selenium的窗口和标签页管理更轻量、更隔离非常适合做并行测试和数据隔离。跨平台一致性Playwright的API在Windows、Linux、macOS上行为高度一致。它甚至提供了playwright.devices来模拟移动设备如iPhone 13, Pixel 5这对于响应式网页的测试来说比手动调整浏览器窗口方便太多了。丰富的调试能力自带录制器playwright codegen、追踪查看器playwright show-trace、网络监听、截图/录屏等功能这些在Selenium中都需要借助第三方工具或复杂配置才能实现。而选择Python作为胶水语言是因为其语法简洁生态丰富Pytest, Allure等测试框架无缝集成非常适合快速构建和维护测试脚本。Playwright for Python的API设计也非常Pythonic。2.2 整体环境架构设计一个健壮的自动化测试环境不仅仅是能跑通脚本。我建议按以下层次来思考你的环境基础层操作系统 系统依赖确保系统有必要的运行时库。这在Linux上尤其重要比如Playwright的浏览器需要一些图形库和音频库才能正常运行。运行时层Python解释器推荐使用Pyenv、Conda等工具管理Python版本避免与系统Python冲突。项目级隔离是专业化的第一步。核心工具层Playwright通过pip安装Playwright的Python包然后安装浏览器。工程化层项目管理使用虚拟环境venv、依赖管理文件requirements.txt/pyproject.toml和版本控制Git来管理你的测试项目。执行与集成层如何运行测试Pytest CLI如何集成到CI/CD如Jenkins, GitHub Actions。我们的搭建将严格遵循这个层次从下往上确保每一层都稳固。注意对于企业级应用强烈建议将浏览器二进制文件部署在内网镜像或文件服务器上通过环境变量PLAYWRIGHT_BROWSERS_PATH指定路径以加速CI/CD流程并避免因网络问题导致的安装失败。3. Windows系统环境搭建详解Windows通常是开发者的主力桌面系统环境搭建相对直观但也有一些细节需要注意。3.1 安装与配置Python环境虽然你可以从Python官网下载安装包但我更推荐使用Microsoft Store安装Python。好处是自动添加到PATH且更新方便避免了手动配置的麻烦。安装Python打开Microsoft Store搜索“Python 3.12”建议使用3.8以上版本点击获取并安装。安装完成后打开PowerShell建议使用Windows Terminal输入python --version验证。如果显示版本号说明安装成功且PATH已配置。创建项目目录与虚拟环境 永远不要将包直接安装到全局Python环境中。虚拟环境是项目隔离的黄金标准。# 打开PowerShell进入你的工作目录例如 D:\Projects cd D:\Projects # 创建你的测试项目文件夹 mkdir playwright-auto-test cd playwright-auto-test # 创建虚拟环境环境文件夹名为 .venv python -m venv .venv这会在当前目录下创建一个名为.venv的文件夹里面包含了一个独立的Python解释器和pip。激活虚拟环境# 在PowerShell中激活虚拟环境 .\.venv\Scripts\Activate.ps1激活后你的命令行提示符前会出现(.venv)字样。这意味着之后所有的pip安装操作都只影响这个项目。3.2 安装Playwright Python包与浏览器在激活的虚拟环境中执行以下命令安装Playwright库pip install playwright这个命令会安装Playwright的核心Python客户端库。安装浏览器二进制文件playwright install这是最关键的一步。这条命令会下载Chromium、Firefox和WebKit的最新稳定版浏览器到用户目录下的缓存中。首次运行时间较长请保持网络通畅。如果你只需要特定浏览器可以使用playwright install chromium或playwright install firefox。如果你想安装带Google API的Chrome/Edge非Chromium需要额外步骤但自动化测试通常推荐使用纯净的Chromium。3.3 验证安装与快速测试环境装好了我们来写一个最简单的脚本验证一下。在项目根目录下创建一个文件test_demo.py。写入以下内容import asyncio from playwright.async_api import async_playwright async def main(): async with async_playwright() as p: # 启动Chromium浏览器headlessFalse表示显示界面 browser await p.chromium.launch(headlessFalse) # 创建一个新的浏览器上下文类似于无痕会话 context await browser.new_context() # 打开新页面 page await context.new_page() # 导航到百度 await page.goto(https://www.baidu.com) # 截图保存 await page.screenshot(pathbaidu.png) # 等待3秒方便观察 await page.wait_for_timeout(3000) # 关闭浏览器 await browser.close() # 运行异步主函数 asyncio.run(main())在激活的虚拟环境的PowerShell中运行python test_demo.py如果一切正常你会看到Chromium浏览器自动打开访问百度首页截图保存为baidu.png然后关闭。实操心得在Windows上有时会遇到Playwright无法启动浏览器提示类似“Executable doesn‘t exist at ...”的错误。这通常是因为杀毒软件或Windows Defender实时保护拦截了浏览器二进制文件的执行。解决方法是将Playwright的缓存目录C:\Users\你的用户名\AppData\Local\ms-playwright添加到杀毒软件的信任列表或排除列表中。4. Linux系统环境搭建详解Linux环境特别是用于CI/CD的服务器环境搭建的重点在于解决系统依赖和以“无头模式”Headless稳定运行。这里以最常用的Ubuntu 22.04 LTS为例其他发行版如CentOS的命令会有差异但思路一致。4.1 安装系统依赖与PythonLinux系统通常预装了Python 3但我们仍需要安装一些系统库来支持浏览器运行。更新系统并安装必要依赖sudo apt update sudo apt install -y python3-pip python3-venv \ libwoff1 libopus0 libwebp6 libwebpdemux2 libenchant-2-2 libgudev-1.0-0 \ libsecret-1-0 libhyphen0 libgles2 libevent-2.1-7 libnotify4 \ libvpx7 libxslt1.1 libatomic1这些库涵盖了字体、音频、视频、图形渲染等浏览器运行所需的基础组件。Playwright官方文档会提供针对不同发行版的依赖安装脚本但上面这个列表在Ubuntu 22.04上比较通用。可选使用Pyenv管理多版本Python 如果系统自带的Python版本不符合要求建议使用Pyenv。# 安装Pyenv依赖 sudo apt install -y make build-essential libssl-dev zlib1g-dev \ libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \ libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev # 安装Pyenv curl https://pyenv.run | bash # 按照提示将pyenv初始化命令添加到 ~/.bashrc 或 ~/.zshrc echo export PATH$HOME/.pyenv/bin:$PATH ~/.bashrc echo eval $(pyenv init --path) ~/.bashrc echo eval $(pyenv virtualenv-init -) ~/.bashrc source ~/.bashrc # 安装指定版本的Python例如3.10.12 pyenv install 3.10.12 pyenv global 3.10.124.2 创建虚拟环境并安装Playwright这一步与Windows类似但都在终端中进行。创建项目目录和虚拟环境mkdir -p ~/projects/playwright-linux cd ~/projects/playwright-linux python3 -m venv .venv source .venv/bin/activate # 激活虚拟环境 (bash/zsh)激活后提示符前同样会出现(.venv)。安装Playwright包及浏览器pip install playwright playwright install chromium # 在服务器上通常只安装Chromium就够了重要在CI/CD服务器或Docker容器中务必使用playwright install --with-deps chromium。这个--with-deps参数会尝试自动安装缺失的系统依赖能解决大部分因依赖缺失导致的启动失败问题。4.3 验证Linux环境无头模式在服务器上我们通常在没有图形界面的“无头模式”下运行测试。创建一个验证脚本headless_test.pyfrom playwright.sync_api import sync_playwright def run(): with sync_playwright() as p: # headlessTrue 是无头模式的关键 browser p.chromium.launch(headlessTrue) context browser.new_context() page context.new_page() page.goto(https://example.com) # 获取页面标题 title page.title() print(fPage title: {title}) # 截图依然可以工作 page.screenshot(pathexample-headless.png) browser.close() return title if __name__ __main__: result run() assert Example Domain in result print(Headless test passed!)运行它python headless_test.py你应该在终端看到输出 “Page title: Example Domain” 和 “Headless test passed!”并且当前目录下会生成截图example-headless.png。这个过程不会有任何浏览器窗口弹出。注意事项在Docker中运行Playwright推荐直接使用微软官方维护的镜像mcr.microsoft.com/playwright/python:v1.40.0-jammy。这个镜像已经包含了所有依赖和浏览器省去了搭建环境的麻烦。你只需要在Dockerfile中COPY你的测试代码和pip install -r requirements.txt即可。5. 项目工程化与最佳实践环境能跑通只是第一步。要让这个环境真正能在团队协作和CI/CD流水线中发挥作用我们需要进行工程化改造。5.1 依赖管理与项目结构一个标准的Python项目应该有这样清晰的结构playwright-auto-test/ ├── .venv/ # 虚拟环境目录.gitignore忽略 ├── requirements.txt # 项目依赖清单 ├── .gitignore # Git忽略文件 ├── conftest.py # Pytest全局配置可选 ├── pages/ # 页面对象模型Page Object目录 │ ├── __init__.py │ └── login_page.py ├── tests/ # 测试用例目录 │ ├── __init__.py │ ├── test_login.py │ └── test_search.py ├── fixtures/ # 测试夹具目录可选 ├── utils/ # 工具函数目录 ├── reports/ # 测试报告输出目录 └── playwright.config.py # Playwright全局配置可选生成依赖文件在虚拟环境激活状态下运行pip freeze requirements.txt。这个文件记录了当前环境所有包的精确版本其他成员可以通过pip install -r requirements.txt一键复现环境。使用pyproject.toml更现代对于新项目推荐使用pyproject.toml来管理依赖和项目元数据。它可以配合poetry或pdm这类更强大的包管理工具。[project] name playwright-auto-test version 0.1.0 dependencies [ playwright1.40.0, pytest7.4.0, pytest-playwright0.4.0, # 官方Pytest插件 allure-pytest2.13.0, # 用于生成Allure报告 ] [build-system] requires [setuptools61.0] build-backend setuptools.build_meta5.2 集成Pytest测试框架单纯用Python脚本写测试用例不利于管理和批量执行。Pytest是Python社区事实上的标准测试框架与Playwright结合得天衣无缝。安装Pytest及插件pip install pytest pytest-playwright allure-pytest编写一个使用Pytest的测试用例tests/test_basic.pyimport re from playwright.sync_api import Page, expect def test_visit_example(page: Page): 测试访问Example网站并验证标题 page.goto(https://example.com) # 使用Playwright的expect断言更智能的等待 expect(page).to_have_title(re.compile(rExample Domain)) def test_baidu_search(page: Page): 测试百度搜索功能 page.goto(https://www.baidu.com) # 定位搜索框并输入 page.locator(input#kw).fill(Playwright) # 点击“百度一下”按钮 page.locator(input#su).click() # 等待结果出现并断言结果中包含Playwright expect(page.locator(textPlaywright).first).to_be_visible()注意这里使用了page这个fixture它是由pytest-playwright插件自动提供的代表一个已经创建好的浏览器页面。运行测试# 运行所有测试 pytest # 运行特定文件 pytest tests/test_basic.py # 运行并生成Allure结果数据 pytest --alluredir./reports/allure-results # 以无头模式并显示浏览器UI适用于调试 pytest --headed5.3 配置Playwright全局选项我们可以创建一个playwright.config.py文件来集中管理浏览器启动选项、超时时间、截图设置等。import os from playwright.sync_api import Playwright, BrowserType # 判断是否为CI环境如GitHub Actions is_ci os.getenv(CI) is not None def run_browser(playwright: Playwright) - None: # 这里可以定义浏览器启动逻辑但更常用的是在Pytest fixture中配置 pass # 以下是Pytest-playwright插件会读取的配置 # 参考https://playwright.dev/python/docs/test-runners import pytest pytest.fixture(scopesession) def browser_type_launch_args(browser_type_launch_args): 自定义浏览器启动参数 # 在CI环境中增加超时网络可能较慢 if is_ci: return {**browser_type_launch_args, timeout: 60000} return browser_type_launch_args pytest.fixture(scopesession) def browser_context_args(browser_context_args, playwright): 自定义浏览器上下文参数如视口大小、语言等 return { **browser_context_args, viewport: {width: 1920, height: 1080}, locale: zh-CN, # 设置浏览器语言为中文 # 忽略HTTPS证书错误仅测试环境使用 ignore_https_errors: True if os.getenv(TEST_ENV) staging else False, } # 全局超时设置 pytest_playwright_launch_args { headless: is_ci, # CI环境无头本地开发可显示 slow_mo: 100 if not is_ci else 0, # 本地调试时放慢操作便于观察 args: [--disable-blink-featuresAutomationControlled] # 隐藏自动化特征防反爬 }6. 跨平台兼容性处理与常见问题排查即使Playwright号称跨平台在Windows和Linux之间迁移脚本时还是会遇到一些“坑”。这里总结几个最常见的问题和解决方案。6.1 路径与文件系统差异这是最经典的跨平台问题。问题脚本中使用了硬编码的Windows路径如C:\Users\test\data.txt在Linux上无法找到。解决方案使用相对路径尽可能使用相对于项目根目录的路径。使用pathlib模块这是Python处理路径的现代、跨平台推荐方式。from pathlib import Path # 获取项目根目录 PROJECT_ROOT Path(__file__).parent.parent # 定义数据文件路径 data_file PROJECT_ROOT / data / input.json screenshot_dir PROJECT_ROOT / reports / screenshots # 创建目录如果不存在 screenshot_dir.mkdir(parentsTrue, exist_okTrue) # 保存截图路径自动适应操作系统 page.screenshot(pathstr(screenshot_dir / error.png))6.2 换行符与编码问题在Windows上生成的文本文件\r\n换行在Linux上查看格式可能不对或者脚本文件本身因编码问题无法执行。解决方案在Git中设置core.autocrlf为inputLinux/macOS或trueWindows让Git自动处理换行符转换。在Python脚本开头明确指定编码# -*- coding: utf-8 -*-。读写文件时使用open(file, r, encodingutf-8)指定UTF-8编码。6.3 环境变量与命令行问题脚本中依赖特定的环境变量或者调用了系统命令。解决方案使用os.getenv(VAR_NAME, default_value)安全地获取环境变量并提供默认值。执行系统命令时使用subprocess模块并注意命令在不同系统上的差异如dir和ls。尽量避免在测试脚本中直接调用系统命令。6.4 常见启动失败问题排查表以下表格整理了在Windows和Linux上部署Playwright时最可能遇到的错误及解决方法。现象可能原因Windows解决方案Linux解决方案浏览器启动失败提示“Executable doesn‘t exist”1. 浏览器未安装。2. 杀毒软件拦截。1. 运行playwright install。2. 将Playwright缓存目录加入杀毒软件白名单。1. 运行playwright install --with-deps。2. 检查磁盘空间是否充足。浏览器启动后立即崩溃系统依赖库缺失Linux常见。通常与Windows无关检查显卡驱动。运行playwright install-deps或手动安装章节4.1中列出的依赖包。无头模式下截图/录屏为黑屏缺少图形或GPU相关依赖。1. 尝试添加启动参数--use-glswiftshader。2. 更新显卡驱动。1. 安装xvfb(X虚拟帧缓冲)sudo apt install xvfb并用xvfb-run命令运行脚本xvfb-run --auto-servernum --server-args-screen 0 1920x1080x24 python your_script.py。2. 或使用Docker官方镜像。页面加载超时或网络错误1. 网络代理问题。2. 系统/浏览器代理设置冲突。1. 在浏览器启动参数中配置代理browser.launch(proxy{server: http://myproxy:8080})。2. 检查系统代理设置。同上。在CI环境中确保测试机可以访问目标网址。playwright命令未找到Playwright的CLI工具未安装或PATH未配置。确保在安装playwright包的Python环境虚拟环境中执行命令。同上。使用python -m playwright代替playwright命令如python -m playwright install。元素定位失败在Windows正常Linux失败1. 字体渲染差异导致文本识别不同。2. 页面加载速度差异。1. 使用更稳定的定位器如CSS Selector (page.locator(“.btn-primary”)) 或>同上。在CI环境中网络和资源加载可能更慢需要增加超时时间。6.5 在CI/CD中集成的最佳实践最后分享一下在GitHub Actions中运行Playwright测试的配置片段这是跨平台自动化测试的终极应用场景。# .github/workflows/playwright-test.yml name: Playwright Tests on: [push, pull_request] jobs: test: timeout-minutes: 10 runs-on: ubuntu-latest # 使用Linux runner strategy: matrix: python-version: [‘3.10’, ‘3.11’] # 测试不同Python版本兼容性 steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: ${{ matrix.python-version }} - name: Install system dependencies run: | sudo apt-get update sudo apt-get install -y libwoff1 libopus0 libwebp6 libwebpdemux2 libenchant-2-2 libgudev-1.0-0 libsecret-1-0 libhyphen0 libgles2 libevent-2.1-7 libnotify4 libvpx7 libxslt1.1 libatomic1 - name: Install Python dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt - name: Install Playwright browsers run: | python -m playwright install --with-deps chromium - name: Run your tests run: | pytest --headless - name: Upload test artifacts (screenshots, traces) if: always() # 即使测试失败也上传 uses: actions/upload-artifactv3 with: name: playwright-report path: | reports/ test-results/ retention-days: 7这个工作流定义了在Ubuntu最新版上安装依赖、安装Playwright浏览器、运行测试并上传结果报告的过程。你可以根据需要在matrix中添加windows-latest来同时测试Windows环境。环境搭建从来不是一劳永逸的事情尤其是跨平台场景。核心思路是标准化、隔离化、自动化。用虚拟环境隔离Python用配置文件管理参数用CI脚本固化部署流程。把这次搭建过程中遇到的每一个错误和解决方案都记录下来积累成你自己的“运维手册”下次再遇到类似问题处理起来就会游刃有余。