1. 项目概述为什么是Playwright如果你还在用Selenium做Web自动化测试或者正在为各种浏览器兼容性、元素等待、异步加载等问题头疼那今天这个内容就是为你准备的。我做了十多年的自动化测试从QTP、Selenium一路用过来直到遇到了Playwright才真正感觉找到了一个“现代”的解决方案。它不是一个简单的工具升级而是一种思路的革新。简单说Playwright是一个由微软开源的、用于Web自动化和端到端测试的框架。它支持所有主流浏览器Chromium、Firefox、WebKit并且是跨平台的。但它的核心优势远不止于此原生支持无头模式、自动等待、强大的网络拦截、多页面/多上下文并行操作这些特性让它从一众自动化工具中脱颖而出。更重要的是它提供了Python、Node.js、Java、.NET四种语言的API这意味着无论你的技术栈是什么都能快速上手。这篇文章我会从一个一线测试开发者的角度带你从零开始手把手搞定Playwright的安装、基础使用并深入剖析那些官方文档里不会写的“坑”和实战技巧。无论你是刚入门自动化测试的新手还是想从Selenium迁移过来的老手都能在这里找到直接能用的“干货”。2. 环境准备与安装一步到位的正确姿势安装Playwright看似简单但里面有不少细节决定了你后续开发的顺畅程度。很多人卡在第一步就是因为环境没配好。2.1 Python环境与Playwright库安装首先确保你有一个健康的Python环境。我强烈建议使用Python 3.7及以上版本并且使用虚拟环境如venv或conda来管理项目依赖避免包冲突。# 创建并激活虚拟环境以venv为例 python -m venv playwright-env # Windows playwright-env\Scripts\activate # macOS/Linux source playwright-env/bin/activate激活虚拟环境后安装Playwright的Python库非常简单pip install playwright这条命令会安装playwright这个核心Python包。但请注意这仅仅安装了控制浏览器所需的Python客户端库浏览器引擎本身还没有安装。这是新手最容易困惑的一点Playwright的库和浏览器驱动是分开的。2.2 安装浏览器引擎playwright install的玄机安装完Python库后你需要安装实际的浏览器引擎。这是Playwright设计精妙的地方它自带了一套经过专门优化和测试的浏览器版本而不是依赖你系统里安装的Chrome或Firefox。这保证了测试环境的高度一致性和可复现性。运行以下命令来安装所有支持的浏览器Chromium, Firefox, WebKitplaywright install这个命令会下载大约几百MB的浏览器二进制文件到你的用户目录下。在Windows上路径通常是%USERPROFILE%\AppData\Local\ms-playwright在macOS/Linux上是~/Library/Caches/ms-playwright或~/.cache/ms-playwright。我建议让Playwright管理自己的浏览器不要尝试去修改或替换这些二进制文件否则可能会出现奇怪的兼容性问题。如果你只需要特定的浏览器可以指定安装playwright install chromium # 只安装ChromiumChrome/Edge内核 playwright install firefox # 只安装Firefox playwright install webkit # 只安装WebKitSafari内核实操心得网络问题与镜像源在国内网络环境下直接运行playwright install可能会因为网络问题下载失败或极慢。这里有个小技巧可以设置环境变量来指定下载镜像源。例如在命令行中临时设置set PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright playwright install或者在代码中设置import os os.environ[“PLAYWRIGHT_DOWNLOAD_HOST”] “https://npmmirror.com/mirrors/playwright”这个镜像源由淘宝NPM镜像提供速度会快很多。如果安装过程中卡住多半是网络问题检查镜像源设置和代理。2.3 验证安装编写你的第一个脚本安装完成后我们来写一个最简单的脚本验证一切是否正常。创建一个名为test_hello.py的文件from playwright.sync_api import sync_playwright with sync_playwright() as p: # 启动Chromium浏览器无头模式即不显示界面 browser p.chromium.launch(headlessFalse) # 设置为False可以看到浏览器界面 page browser.new_page() page.goto(“https://www.baidu.com) print(f”页面标题是{page.title()}“) # 截图保存 page.screenshot(path”baidu.png“) browser.close()运行这个脚本python test_hello.py如果一切顺利你会看到一个浏览器窗口自动打开访问百度然后在控制台打印出页面标题并在当前目录生成一张baidu.png的截图。恭喜你的Playwright环境已经搭建成功3. 核心概念与API设计哲学在深入写复杂脚本之前理解Playwright的几个核心概念至关重要。这能帮你写出更高效、更健壮的代码而不是简单地把Selenium的写法搬过来。3.1 同步 vs. 异步API如何选择Playwright为Python提供了两套API同步sync_api和异步async_api。这是它比Selenium先进的地方之一直接拥抱了现代Python的并发编程模式。同步API (sync_api): 使用with sync_playwright() as p:上下文管理器。代码是顺序执行的写起来直观类似于传统的Selenium脚本。适合大多数简单的线性操作脚本和初学者。异步API (async_api): 使用async with async_playwright() as p:并结合asyncio。允许你在单个线程内并发执行多个浏览器操作例如同时操作多个标签页。适合需要高性能、高并发的测试场景比如同时模拟多个用户操作或者需要处理大量I/O等待的场景。我个人的建议是如果你是新手或者项目不涉及复杂的并发先从同步API开始它更简单易懂。当你需要提升测试执行速度或者处理大量并行任务时再考虑迁移到异步API。文章开头的对比示例已经清晰展示了异步模式带来的性能提升11.5秒 vs 6秒。3.2 核心对象模型Browser, Context, PagePlaywright的对象层级非常清晰理解它们的关系是高效使用的关键Browser: 对应一个浏览器进程实例如一个Chrome窗口。通过launch()方法创建。创建成本较高。BrowserContext: 浏览器上下文。这可能是Playwright最强大的概念之一。你可以把它想象成一个完全独立的浏览器会话它拥有独立的cookie、localStorage、缓存和证书存储。在一个Browser实例下可以创建多个Context它们彼此隔离速度远快于启动新的Browser。这是实现多用户并行测试、避免状态污染的核心。Page: 对应一个浏览器标签页。在Context中创建。我们绝大部分的自动化操作如点击、输入都发生在Page对象上。它们的关系是Browser- 一个或多个BrowserContext- 一个或多个Page。 这种设计让你可以灵活地管理测试的隔离性和资源共享。例如你可以用一个Browser为每个测试用例创建一个独立的Context这样测试之间完全不会互相干扰又避免了反复启动关闭浏览器的开销。3.3 自动等待告别痛苦的time.sleep这是Playwright对比Selenium最大的杀手锏之一。在Selenium里我们经常需要写大量的WebDriverWait和time.sleep来等待元素加载既繁琐又不稳定。Playwright的绝大多数操作如click,fill,goto内置了智能等待。它会自动等待元素变得可交互可见、可点击、非禁用后再执行操作。你基本不需要手动写等待。# Playwright的方式简洁可靠 page.click(“button#submit”) # 自动等待按钮可点击后再点击 # 传统Selenium方式冗长且可能失效 from selenium.webdriver.common.by import By from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC element WebDriverWait(driver, 10).until( EC.element_to_be_clickable((By.ID, “submit”)) ) element.click()当然Playwright也提供了显式等待的方法如page.wait_for_selector()用于更复杂的等待条件但在80%的场景下你都不需要用到它。4. 实战从录制到编写健壮脚本理论讲完了我们动手做点实际的。Playwright提供了一个极其好用的工具——代码录制器Codegen它能将你在浏览器里的操作实时转换成代码是快速入门和编写原型的神器。4.1 使用Playwright Codegen录制脚本在命令行中运行playwright codegen https://www.baidu.com这会自动打开一个浏览器窗口和一个录制器窗口。你在浏览器里的所有操作点击、输入、导航都会实时显示在录制器里并生成对应的Python代码。你可以直接复制这些代码。高级录制选项-o script.py: 将生成的代码保存到文件。--target python-async: 生成异步API的代码。--device”iPhone 12 Pro”: 模拟移动设备访问。--save-storageauth.json: 录制登录状态cookies, localStorage方便后续脚本复用登录态。--load-storageauth.json: 加载之前保存的状态直接从登录后开始录制。注意事项录制代码的局限性录制生成的代码是一个很好的起点但通常不是最终的生产代码。它生成的定位器如text登录可能不够健壮代码结构也比较线性。你需要对生成的代码进行重构提取公共操作成函数、使用更稳定的定位器如CSS Selector或XPath、添加断言和错误处理。把录制当作“脚手架”而不是最终成品。4.2 编写一个完整的测试用例以搜索为例让我们抛开录制手动编写一个更健壮、可维护的测试用例。假设我们要测试百度搜索功能。from playwright.sync_api import sync_playwright, expect # 引入expect断言库 import pytest # 推荐与pytest测试框架结合 def test_baidu_search(): with sync_playwright() as p: # 1. 启动浏览器推荐在无头模式下运行测试更快更稳定 browser p.chromium.launch(headlessTrue) # 集成环境设为True # 2. 创建上下文可以设置视口大小、User-Agent等 context browser.new_context( viewport{‘width’: 1920, ‘height’: 1080}, user_agent’Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36’ ) # 3. 创建页面 page context.new_page() try: # 4. 导航到目标页面 page.goto(“https://www.baidu.com) # 使用expect进行断言更直观 expect(page).to_have_title(“百度一下你就知道”) # 5. 定位元素并操作 - 使用CSS Selector比text定位更稳定 search_box page.locator(”#kw“) # 百度搜索框的ID search_box.fill(“Playwright自动化测试”) search_box.press(“Enter”) # 模拟键盘回车 # 6. 等待结果页面加载并断言 # 等待搜索结果区域出现 page.wait_for_selector(”#content_left“, state”attached“) # 断言结果中包含特定文本 expect(page.locator(”text微软开源“)).to_be_visible() # 7. 也可以截图作为证据 page.screenshot(path”search_results.png“, full_pageTrue) print(“测试通过”) except Exception as e: # 8. 出错时截图便于排查 page.screenshot(path”error.png“) print(f”测试失败{e}“) raise e finally: # 9. 清理资源 context.close() browser.close() if __name__ “__main__”: test_baidu_search()代码解读与技巧headlessTrue: 在CI/CD环境或后台运行测试时务必使用无头模式节省资源且避免UI干扰。browser.new_context(): 在这里可以注入Cookie、设置权限如地理位置、通知、模拟网络条件等非常强大。page.locator(): 这是Playwright推荐的元素定位方式。它返回一个Locator对象支持链式调用和自动等待。比直接用page.click(”selector“)更灵活。expect()断言库: Playwright内置了丰富的断言如to_be_visible,to_have_text,to_have_count等语义清晰比单纯的assert更强大。异常处理与截图: 在try…except块中捕获异常并在失败时截图这是定位线上问题的黄金手段。资源清理: 务必在finally块中关闭context和browser确保资源释放避免进程残留。4.3 处理复杂场景文件上传、下载、弹窗现代Web应用充满各种交互Playwright对此有很好的支持。文件上传传统上传需要找input type”file”元素然后send_keysPlaywright更简单。# 方法1直接设置文件路径适用于input元素可见 page.locator(”input[type’file’]“).set_input_files(”path/to/file.pdf“) # 方法2通过事件触发文件选择器更通用 with page.expect_file_chooser() as fc_info: page.click(”button:has-text(‘上传’)“) # 点击触发文件选择对话框 file_chooser fc_info.value file_chooser.set_files(”path/to/file.pdf“)文件下载等待并保存下载的文件。# 开始下载并等待下载完成 with page.expect_download() as download_info: page.click(”a#download-link“) # 点击下载链接 download download_info.value # 指定保存路径 save_path “./downloads/” download.suggested_filename download.save_as(save_path) print(f”文件已下载到{save_path}“)处理弹窗Alert, Confirm, Prompt# 监听弹窗并接受 page.on(“dialog”, lambda dialog: dialog.accept()) page.click(“button#trigger-alert”) # 点击触发alert # 或者更精确地处理 def handle_dialog(dialog): print(f”弹窗消息{dialog.message}“) if dialog.type “alert”: dialog.accept() elif dialog.type “confirm”: dialog.dismiss() # 取消 elif dialog.type “prompt”: dialog.accept(“输入的文字”) # 接受并输入文字 page.on(“dialog”, handle_dialog)处理新窗口/标签页# 监听新页面标签页打开 with page.context.expect_page() as new_page_info: page.click(“a[target’_blank’]“) # 点击一个在新窗口打开的链接 new_page new_page_info.value new_page.wait_for_load_state() # 等待新页面加载 print(f”新页面标题{new_page.title()}“) # 操作新页面... new_page.close() # 操作完后关闭5. 高级特性与最佳实践当你掌握了基础操作后这些高级特性能让你的自动化脚本如虎添翼。5.1 网络拦截与模拟Mock请求这是Playwright相比Selenium的另一个巨大优势。你可以拦截和修改网络请求这对于测试前端错误处理、模拟后端接口返回、屏蔽第三方资源如广告以加速测试等场景非常有用。# 拦截所有请求并修改或阻止某些请求 def handle_route(route): request route.request # 如果请求的是广告资源则中止请求 if “ads.com” in request.url: route.abort() # 如果请求某个API则返回Mock数据 elif “/api/user” in request.url: route.fulfill( status200, content_type“application/json”, bodyjson.dumps({“name”: “Mock User”, “id”: 123}) ) else: # 其他请求继续 route.continue_() # 在页面加载前设置路由 page.route(“**/*”, handle_route) page.goto(“https://your-app.com”)5.2 执行JavaScript有时需要通过执行JS来获取或操作一些Playwright API不易处理的内容。# 获取页面性能指标 performance_timing page.evaluate(“”” () { return JSON.stringify(window.performance.timing); } “””) print(performance_timing) # 滚动到页面底部 page.evaluate(“window.scrollTo(0, document.body.scrollHeight)”) # 修改DOM元素样式 page.evaluate(“”” () { document.querySelector(‘.ad-banner’).style.display ‘none’; } “””)5.3 与Pytest测试框架集成单独运行脚本不是长久之计将Playwright集成到成熟的测试框架如pytest中才能进行有效的测试管理、报告生成和持续集成。首先安装pytest插件pip install pytest-playwright创建一个测试文件test_search.py:import pytest from playwright.sync_api import Page, expect pytest.fixture(scope”session”) def browser_context_args(browser_context_args): # 全局上下文设置如视口大小 return { **browser_context_args, “viewport”: {“width”: 1920, “height”: 1080}, “ignore_https_errors”: True # 忽略HTTPS证书错误用于测试环境 } pytest.fixture def page(context): # 为每个测试用例提供一个干净的页面 page context.new_page() yield page page.close() def test_baidu_search_title(page: Page): page.goto(“https://www.baidu.com”) expect(page).to_have_title(“百度一下你就知道”) def test_baidu_search_functionality(page: Page): page.goto(“https://www.baidu.com”) page.locator(“#kw”).fill(“Playwright”) page.locator(“#su”).click() # 等待搜索结果出现 expect(page.locator(“#content_left”)).to_be_visible() # 断言结果中包含特定链接 expect(page.locator(“textplaywright.dev”)).to_be_visible()运行测试pytest test_search.py -v # 指定浏览器运行 pytest test_search.py --browser chromium --browser firefox # 跨浏览器测试pytest-playwright插件自动管理了Browser和Context的生命周期你只需要关注Page对象和测试逻辑即可大大简化了代码。6. 常见问题与排查技巧实录在实际使用中你肯定会遇到各种问题。这里记录了我踩过的一些坑和解决方案。6.1 元素定位失败定位器策略这是自动化测试中最常见的问题。Playwright提供了多种定位器优先级如下首选按角色Role和文本定位这是最接近用户视角的方式可读性最强。page.locator(“button”, has_text”登录”).click() page.locator(“input[name’username’]”).fill(“admin”)次选CSS Selector 或 XPath当角色定位不适用时使用。CSS Selector通常性能更好。page.locator(“.submit-button”).click() page.locator(“//button[id’submit’]”).click() # XPath避免使用page.text()或page.click(‘textxxx’)纯文本定位在页面动态变化时非常脆弱。尽量结合其他属性。使用page.locator().filter()进行精细过滤# 找到第三个具有“item”类的div page.locator(“.item”).nth(2).click() # 找到包含特定文本的列表项 page.locator(“li”).filter(has_text”特定项目”).click()调试定位器使用Playwright Inspector (playwright open或playwright codegen) 的“拾取”功能可以实时验证你的定位器是否唯一匹配。6.2 等待与超时问题虽然Playwright有自动等待但某些场景仍需注意导航超时page.goto()默认30秒。对于慢速网络或页面可以增加超时时间。page.goto(“https://slow-site.com”, timeout60000) # 60秒自定义等待条件使用page.wait_for_function()或page.wait_for_selector()。# 等待某个元素内部文本变为特定值 page.wait_for_function(“”” () document.querySelector(‘.status’).textContent ‘完成’ “””, timeout10000)等待网络空闲对于单页应用SPA页面load事件触发后可能还有AJAX请求。使用page.wait_for_load_state(‘networkidle’)等待网络基本空闲。page.goto(“https://app.com”) page.wait_for_load_state(“networkidle”) # 默认等待500ms没有新请求6.3 跨平台与浏览器兼容性Playwright号称支持所有主流浏览器但细微差异仍需处理。浏览器启动参数不同浏览器可能需要不同的启动参数。# Firefox可能需要禁用一些特性以获得更稳定的自动化环境 browser p.firefox.launch(headlessFalse, firefox_user_prefs{ “dom.ipc.processCount”: 8, “browser.tabs.remote.autostart”: False, })功能检测某些API可能只在特定浏览器中可用。使用try…except或检查browser_type.name。if browser.browser_type.name ‘chromium’: # 使用Chromium特有功能如CDP协议 pass视觉差异CSS渲染在不同浏览器内核上可能有像素级差异。如果做视觉回归测试截图对比需要设置一致的视口、缩放比例并考虑使用专门的工具如pixelmatch进行容差比较。6.4 性能与稳定性优化复用Browser Context如前所述创建Context比创建Browser快得多。在测试套件级别复用Browser在测试用例级别使用独立的Context。并行执行利用pytest-xdist进行测试并行化并配合Playwright的Context隔离可以极大缩短测试总时间。禁用不必要的功能在无头模式下可以禁用图片、样式表、字体等加载以加速。context browser.new_context( java_script_enabledTrue, bypass_cspTrue, ignore_https_errorsTrue, # 拦截请求阻止图片等资源加载 **kwargs ) # 或者通过路由拦截 page.route(“**/*.{png,jpg,jpeg}”, lambda route: route.abort())清理状态确保每个测试用例结束后关闭它打开的Page和Context避免状态泄露影响下一个用例。6.5 在CI/CD中运行在Jenkins、GitHub Actions等CI环境中运行Playwright需要注意安装依赖CI机器上需要安装Playwright的浏览器。确保在安装Python包后运行playwright install --with-deps chromium--with-deps会同时安装系统依赖如字体库。无头模式务必设置headlessTrue。沙盒环境某些CI环境如Docker容器可能需要禁用沙盒模式才能启动浏览器。browser p.chromium.launch(headlessTrue, args[‘--no-sandbox’, ‘--disable-dev-shm-usage’])--disable-dev-shm-usage可以防止在Docker等受限环境中因共享内存不足而崩溃。视频和追踪对于失败的测试可以自动录制视频或保存追踪文件便于事后分析。context browser.new_context(record_video_dir”videos/“) # … 运行测试 … # 测试失败时保存视频 if test_failed: page.video.save_as(f”failure_{test_name}.webm”)7. 从脚本到框架构建可维护的测试体系单个脚本解决了“能用”的问题但要团队协作和长期维护我们需要一个清晰的框架结构。以下是一个我实践中总结的简单目录结构your-automation-project/ ├── conftest.py # Pytest全局配置定义Browser/Context Fixture ├── requirements.txt # 项目依赖 ├── pytest.ini # Pytest配置文件 ├── pages/ # 页面对象模型Page Object Model │ ├── __init__.py │ ├── base_page.py # 基础页面类封装公共方法 │ ├── login_page.py # 登录页面 │ └── home_page.py # 主页 ├── locators/ # 定位器集中管理可选 │ ├── __init__.py │ └── login_locators.py ├── tests/ # 测试用例 │ ├── __init__.py │ ├── test_login.py │ └── test_search.py ├── utils/ # 工具函数 │ ├── __init__.py │ ├── helpers.py # 通用帮助函数 │ └── data_loader.py # 数据加载 └── reports/ # 测试报告由Allure等生成核心思想页面对象模型POM将每个页面的元素定位和操作封装成一个类。测试用例只调用页面对象的方法不直接包含定位器。这样当页面UI变化时只需修改对应的页面类测试用例基本不用动。数据驱动将测试数据如用户名、密码、搜索关键词从测试逻辑中分离出来存放在JSON、YAML或Excel文件中。使用pytest的pytest.mark.parametrize装饰器实现数据驱动测试。配置管理使用config.ini或config.yaml管理环境URL、超时时间、浏览器类型等配置方便在不同环境测试、预生产、生产间切换。最后我个人最大的体会是Playwright最大的价值不在于它比Selenium快多少而在于它极大地降低了编写和维护稳定、可靠自动化测试的心智负担和成本。它的设计是“为测试而生”很多贴心功能如自动等待、强大的选择器、网络拦截都是直接命中测试工程师的痛点。花时间学好它绝对是笔划算的投资。开始可能会觉得概念有点多但一旦上手你会发现自己再也不想回去写那些满是WebDriverWait和time.sleep的脚本了。