Playwright+Python自动化测试环境搭建与脚本录制实战指南

1. 项目概述：为什么选择 Playwright + Python？

如果你正在寻找一个既能轻松上手，又能应对现代复杂 Web 应用自动化测试或数据抓取的方案，那么 Playwright 搭配 Python 的组合，绝对值得你花时间深入了解。我最初接触它，是为了解决一个棘手的项目：一个大量使用动态加载、单页应用（SPA）技术栈的后台管理系统。传统的基于 Selenium 的方案，在等待元素、处理 iframe 和网络请求拦截上总是磕磕绊绊，脚本既不稳定又难以维护。直到尝试了 Playwright，我才发现自动化脚本可以写得如此优雅和可靠。

简单来说，Playwright 是一个由微软开源的现代化浏览器自动化库。它支持 Chromium、Firefox 和 WebKit 三大浏览器引擎，这意味着你可以用一套脚本测试你的网站在 Chrome、Firefox 和 Safari 上的表现是否一致。而 Python，以其简洁的语法和庞大的生态，成为了连接 Playwright 强大能力与开发者之间的最佳桥梁。这个组合的核心价值在于：“开箱即用”的稳定性和“所见即所得”的脚本录制能力。你不需要花费大量时间处理浏览器驱动版本兼容、元素等待超时等琐事，可以更专注于业务逻辑本身。无论是测试工程师想要进行端到端（E2E）测试，还是开发人员需要编写爬虫或自动化操作脚本，甚至是运营同学想自动化一些重复的网页操作，这个组合都能大幅提升效率。

2. 环境搭建全流程详解与避坑指南

环境搭建是万里长征的第一步，也是最容易踩坑的环节。一个干净、隔离的环境是后续所有稳定操作的基础。下面我将以最常用的 Windows 系统为例，详细拆解每一步，并附上 macOS 和 Linux 的关键差异点。

2.1 Python 环境安装与配置

Python 是这一切的基石。虽然系统可能预装了 Python，但我强烈建议你进行独立安装，并使用虚拟环境管理，以避免包依赖冲突。

1. 下载与安装 Python访问 Python 官方网站，下载最新的稳定版本（如 Python 3.11 或 3.12）。安装时，务必勾选“Add python.exe to PATH”这个选项。这是很多新手忽略导致命令行无法识别python命令的根源。

注意：如果你电脑上已有多个 Python 版本（比如 Anaconda 自带的），在命令行输入python或python3可能会指向不同的解释器。安装完成后，在终端（CMD 或 PowerShell）中输入python --version来验证是否安装成功以及版本是否正确。

2. 创建专属虚拟环境虚拟环境就像一个独立的“沙箱”，你在这个沙箱里安装的所有包都不会影响系统全局的 Python 环境。这是 Python 开发的最佳实践。 打开终端，进入你计划存放项目的目录，执行以下命令：

# 创建名为 playwright-env 的虚拟环境 python -m venv playwright-env # 激活虚拟环境 (Windows) playwright-env\Scripts\activate # 激活虚拟环境 (macOS/Linux) source playwright-env/bin/activate

激活后，你的命令行提示符前通常会显示(playwright-env)，表示你已经在这个虚拟环境中了。后续所有 pip 安装操作都应在此状态下进行。

2.2 安装 Playwright for Python

在激活的虚拟环境中，安装 Playwright 的 Python 包非常简单：

pip install playwright

这条命令会从 PyPI 下载并安装 Playwright 的核心 Python 客户端库。为了加速下载，可以考虑使用国内的镜像源，例如：

pip install playwright -i https://pypi.tuna.tsinghua.edu.cn/simple

安装后验证：可以执行pip list | findstr playwright（Windows）或pip list | grep playwright（macOS/Linux）来查看是否安装成功及其版本。

2.3 安装浏览器驱动（核心步骤）

Playwright 的强大之处在于它自带浏览器引擎。安装完 Python 包后，你需要安装它需要操作的“浏览器本体”。这是通过 Playwright 自带的命令行工具完成的。

playwright install

这条命令会下载 Chromium、Firefox 和 WebKit 的预备版本。这些不是你在桌面看到的 Chrome 或 Safari，而是 Playwright 专门优化、用于自动化的版本，更轻量且行为一致。

• playwright install chromium：如果你只需要 Chromium（与 Chrome 同内核），可以只安装它，以节省磁盘空间和时间。
• 网络问题处理：如果下载速度慢或失败，Playwright 会尝试从多个镜像下载。如果遇到困难，可以设置环境变量PLAYWRIGHT_DOWNLOAD_HOST为国内镜像，例如：

  set PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright # Windows export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright # macOS/Linux

  然后再运行playwright install。

至此，一个完整的 Playwright + Python 开发环境就已经搭建好了。你可以通过一个简单的脚本来验证：

import asyncio from playwright.async_api import async_playwright async def main(): async with async_playwright() as p: browser = await p.chromium.launch(headless=False) # 非无头模式，可以看到浏览器 page = await browser.new_page() await page.goto('https://www.example.com') print(await page.title()) await browser.close() asyncio.run(main())

运行这个脚本，如果弹出了浏览器并打印出 “Example Domain”，恭喜你，环境配置成功。

3. 脚本录制：CodeGen 工具实战教学

手工编写自动化脚本虽然灵活，但对于快速创建基础脚本或学习 API 来说，录制功能是一个无可替代的利器。Playwright 提供了强大的命令行录制工具playwright codegen。

3.1 启动录制与基本操作

在终端（确保虚拟环境已激活）中，输入以下命令：

playwright codegen https://www.baidu.com

执行后，会同时发生两件事：

1. 弹出一个浏览器窗口（默认为 Chromium），并自动导航到百度首页。
2. 弹出一个名为“Playwright Inspector”的窗口。这个窗口就是你的“指挥中心”，它实时显示你操作所生成的 Python 代码。

现在，你可以在浏览器里进行任何操作：点击搜索框、输入文字、点击“百度一下”按钮。你的每一个操作，都会实时在 Inspector 窗口中生成对应的代码。例如，你点击一下搜索框，可能会生成：

page.locator("#kw").click()

你输入 “Playwright”，可能会生成：

page.locator("#kw").fill("Playwright")

录制模式详解：

• playwright codegen：默认使用 Chromium 录制。
• playwright codegen --target python：明确指定生成 Python 代码（默认就是）。
• playwright codegen -b firefox https://example.com：使用 Firefox 浏览器进行录制。
• playwright codegen --viewport-size=800,600：设置录制时浏览器的视口大小。
• playwright codegen --save-trace=trace.zip：同时录制一个追踪文件（trace），用于后续调试复杂场景。

3.2 定位策略优化与代码导出

默认生成的代码使用的是locator()API 并尽可能使用稳定的选择器（如id、>playwright codegen https://www.baidu.com -o my_script.py

这样，你录制的代码会实时保存到my_script.py文件中。录制结束后，你就得到了一个可独立运行的 Python 脚本。

3. 处理等待与断言录制工具也会记录你的等待。比如，点击一个按钮后页面跳转，生成的代码会自动加入page.wait_for_url()或page.wait_for_load_state()。你可以在录制过程中，在 Inspector 的 “Assertions” 面板手动添加断言（如检查某个文本是否存在），这些也会被生成到代码中。

4. 从录制代码到健壮脚本的进阶改造

录制生成的代码是一个完美的起点，但它通常是线性的、脆弱的，缺乏错误处理和结构。直接使用录制的脚本在生产环境运行，很容易因为网络延迟、元素加载稍慢等问题而失败。因此，将录制代码改造为健壮的脚本是必经之路。

4.1 结构化与引入等待策略

录制的代码往往所有操作都堆砌在一个主函数里。我们需要将其模块化，并显式地加入可靠的等待。

原始录制代码可能类似：

from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=False) page = browser.new_page() page.goto("https://target-site.com/login") page.locator("input[name='username']").fill("myuser") page.locator("input[name='password']").fill("mypass") page.locator("button:has-text('登录')").click() # 可能立即开始下一步操作，此时页面可能还未跳转完成 page.locator(".dashboard").click()

改造后代码：

from playwright.sync_api import sync_playwright, expect import logging logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) def login(page, username, password): """登录功能封装""" logger.info("导航到登录页") page.goto("https://target-site.com/login") # 显式等待关键元素出现，比隐式等待更可靠 page.wait_for_selector("input[name='username']", state="visible") logger.info(f"输入用户名: {username}") page.locator("input[name='username']").fill(username) logger.info("输入密码") page.locator("input[name='password']").fill(password) logger.info("点击登录按钮") with page.expect_navigation(): # 等待导航完成，这是一个最佳实践 page.locator("button:has-text('登录')").click() logger.info("验证登录成功") # 使用 Playwright 的断言库，更优雅 expect(page).to_have_url("https://target-site.com/dashboard") expect(page.locator(".welcome-msg")).to_contain_text(username) def main(): with sync_playwright() as p: browser = p.chromium.launch(headless=True) # 生产环境通常用无头模式 context = browser.new_context(viewport={'width': 1920, 'height': 1080}) # 固定视口 page = context.new_page() try: login(page, "myuser", "mypass") # ... 其他业务操作 logger.info("所有操作执行完毕") except Exception as e: logger.error(f"脚本执行失败: {e}") # 失败时截图，极其重要的调试手段 page.screenshot(path="error.png", full_page=True) raise finally: browser.close() if __name__ == "__main__": main()

4.2 处理动态内容与复杂交互

现代 Web 应用充满动态内容，这是录制脚本最常见的失败原因。例如，列表是异步加载的，弹窗是动态渲染的。

1. 等待动态元素：不要使用固定的time.sleep(5)，而是使用 Playwright 提供的智能等待。

# 等待一个动态出现的弹窗 popup = page.locator(".modal-content") popup.wait_for(state="visible") # 等待它可见 # 等待列表项加载完成（至少出现1个） page.wait_for_selector(".list-item", state="attached") # 等待某个元素消失 page.wait_for_selector(".loading-spinner", state="hidden")

2. 处理 iframe：如果操作对象在 iframe 内，必须先获取 iframe 对象。

# 通过名称、URL或选择器定位 iframe frame = page.frame(name="editor-frame") # 方式1 # 或 frame = page.frame(url=re.compile(r".*/editor/.*")) # 方式2 # 或 frame = page.frame_locator("iframe[title='编辑器']").content_frame # 方式3 # 然后在 frame 内操作 frame.locator("button#submit").click()

3. 处理网络请求：录制工具不会录制网络请求。但有时我们需要拦截或等待特定请求完成。

# 等待一个特定的 API 调用完成后再继续 with page.expect_response("**/api/getData") as response_info: page.locator("#refresh-btn").click() response = response_info.value data = response.json() print(f"获取到数据: {data}") # 拦截并修改请求（例如，修改请求头） def handle_route(route): headers = route.request.headers headers['x-custom-token'] = 'my-token' route.continue_(headers=headers) page.route("**/api/**", handle_route)

5. 常见问题排查与性能优化技巧

即使脚本写得再完善，在复杂的真实环境中也会遇到各种问题。以下是基于大量实战总结的排查清单和优化点。

5.1 高频错误与解决方案速查表

5.2 提升脚本性能与可维护性

1. 复用浏览器上下文每次测试都启动关闭浏览器开销很大。对于测试套件，可以复用 BrowserContext。

import pytest from playwright.sync_api import Page @pytest.fixture(scope="session") def browser_context(browser): context = browser.new_context(viewport={'width': 1920, 'height': 1080}) yield context context.close() @pytest.fixture def page(browser_context): page = browser_context.new_page() yield page page.close()

2. 并行执行Playwright Test 运行器（pytest-playwright）天然支持并行测试。对于大量独立用例，可以极大缩短总执行时间。在pytest.ini中配置-n auto即可。

3. 使用 Trace 进行可视化调试当脚本失败时，光看日志和截图可能不够。在运行脚本时启用 Trace 记录，可以像看录像一样回放所有操作。

context = browser.new_context() # 启动追踪 context.tracing.start(screenshots=True, snapshots=True, sources=True) try: # ... 你的脚本操作 ... except Exception as e: # 出错时保存追踪文件 context.tracing.stop(path = “trace.zip”) raise

使用playwright show-trace trace.zip命令打开可视化查看器。

4. 集成到 CI/CD 流程在 Docker 或 GitHub Actions 等 CI 环境中，需要安装系统依赖。Playwright 提供了playwright install-deps命令来安装所需的系统库（如字体、共享库）。在 Dockerfile 中，通常的步骤是：

FROM mcr.microsoft.com/playwright/python:v1.40.0-jammy COPY requirements.txt . RUN pip install -r requirements.txt RUN playwright install --with-deps chromium # 安装 Chromium 及其系统依赖 COPY . . CMD [“python”, “main_script.py”]

从环境搭建到脚本录制，再到将脆弱的录制代码锤炼为工业级可用的自动化脚本，这个过程本身就是对现代 Web 应用交互逻辑的深度理解。Playwright 提供的强大 API 和工具链，让这个过程的起点变得非常低，但天花板却很高。我个人的体会是，不要满足于“脚本能跑通”，多思考如何让脚本更稳定（可靠的等待与断言）、更清晰（良好的结构与封装）、更高效（复用与并行）。当你开始习惯用 Playwright 的思维去分析页面交互时，你会发现很多之前令人头疼的自动化难题，都迎刃而解了。最后一个小建议：多使用playwright inspector和show-trace，它们是你调试复杂场景时最得力的“眼睛”。