1. 项目概述为什么选择Playwright作为UI自动化起点如果你正在寻找一个现代、强大且易于上手的Web UI自动化工具那么Playwright绝对值得你投入时间。作为一名在自动化测试领域摸爬滚打了十多年的老手我见证过从Selenium RC到WebDriver再到各种基于JavaScript的测试框架的变迁。Playwright的出现让我感觉UI自动化测试终于进入了一个“开箱即用”的时代。它不像一些老牌工具那样需要你花费大量时间去处理浏览器驱动兼容性、元素等待策略或是复杂的异步操作。Playwright由微软开发天生就带着“开发者友好”的基因其设计哲学是让自动化脚本的编写像与真实用户交互一样直观和可靠。这个系列教程的第一篇我们就从最基础的“安装与配置”开始。别小看这个起点一个干净、正确的环境是后续所有复杂操作和稳定运行的基石。我见过太多项目因为初期环境配置的疏忽导致后期脚本运行诡异、难以调试最终团队对自动化失去信心。所以无论你是刚接触UI自动化的新手还是从Selenium等工具迁移过来的老手我都建议你花点时间跟着我把Playwright的环境从头到尾搭一遍理解每一步背后的“为什么”这能帮你避开未来无数的坑。简单来说Playwright能帮你做什么它能让你用代码控制Chromium、Firefox和WebKitSafari的内核浏览器模拟用户的点击、输入、导航、文件上传下载等所有操作并且支持移动端设备模拟、网络请求拦截与修改、生成脚本录像等高级功能。无论是做日常的冒烟测试、回归测试还是复杂的前端交互验证它都是一个得力的助手。2. 环境准备构建稳固的自动化地基在开始安装Playwright之前我们需要确保你的“作战平台”——也就是你的开发环境——是准备就绪的。这不仅仅是安装一个Python包那么简单它关乎到后续所有脚本的稳定性和可维护性。2.1 Python环境版本与虚拟环境管理首先确认你的Python版本。Playwright for Python 要求 Python 3.7 或更高版本。我强烈建议使用 Python 3.8以获得更好的性能和语言特性支持。你可以在命令行中通过python --version或python3 --version来检查。注意很多Linux和macOS系统预装了Python 2.7请务必确认你使用的是Python 3。如果系统同时存在多个版本可能需要使用python3和pip3命令。接下来是虚拟环境。这是我必须强调的一点永远不要将项目依赖直接安装到系统的全局Python环境中。使用虚拟环境可以为每个项目创建独立的、干净的依赖库避免版本冲突。这是Python开发的最佳实践对于自动化项目尤为重要因为你可能会同时维护多个使用不同库版本的项目。创建和激活虚拟环境的方法如下对于Windows系统# 创建虚拟环境venv是环境文件夹名可以自定义 python -m venv playwright_env # 激活虚拟环境 playwright_env\Scripts\activate对于macOS/Linux系统# 创建虚拟环境 python3 -m venv playwright_env # 激活虚拟环境 source playwright_env/bin/activate激活后你的命令行提示符前通常会显示虚拟环境的名字如(playwright_env)这表示你已进入该环境后续的所有pip install操作都只会影响这个环境。2.2 包管理工具pip的优化虚拟环境激活后我们先升级一下pip确保使用的是最新版本能更好地处理依赖关系。python -m pip install --upgrade pip有时候从默认的PyPI源下载包速度较慢特别是安装Playwright这种需要下载浏览器二进制文件的工具时。我们可以临时或永久地更换为国内的镜像源来加速。以下是在安装命令中临时使用清华源的方法pip install playwright -i https://pypi.tuna.tsinghua.edu.cn/simple如果你希望永久更换可以修改pip的配置文件。但就安装Playwright而言临时指定镜像源通常就足够了。3. 核心安装Playwright库与浏览器引擎环境准备好后我们就可以开始安装Playwright本体了。Playwright的安装分为两部分Python客户端库和浏览器引擎。3.1 安装Python客户端库安装命令非常简单pip install playwright这条命令会从PyPI下载并安装playwright这个Python包。这个包包含了与Playwright服务进行通信的所有Python API。安装过程通常很快因为它本身不大。安装完成后你可以验证一下是否成功python -c “import playwright; print(playwright.__version__)”如果输出了版本号例如1.40.0说明Python库安装成功。3.2 安装浏览器二进制文件核心步骤这是Playwright设计上非常聪明的一点也是它与Selenium等工具在体验上的一个巨大分水岭。Selenium需要你手动去下载对应版本的浏览器驱动如chromedriver并确保驱动版本与本地安装的浏览器版本匹配这个过程常常是新手的第一道噩梦。Playwright则把这个过程自动化、标准化了。它内置了一个命令可以一键下载所有它需要支持的浏览器引擎的特定版本。这些浏览器是专门为自动化测试优化过的版本与你在官网下载的消费者版本是隔离的这保证了测试环境的一致性——在任何机器上只要安装了相同版本的Playwright得到的浏览器环境是完全一样的彻底解决了“在我机器上是好的”这类问题。安装所有支持的浏览器Chromium, Firefox, WebKitplaywright install这条命令会开始下载三个浏览器的二进制文件。由于需要从微软的CDN下载几百MB的数据耗时取决于你的网络速度。这里是我遇到的第一个“坑”如果你的网络环境访问海外资源较慢这个下载过程可能会非常漫长甚至失败。解决方案与实操心得使用镜像源推荐Playwright 1.18版本之后支持通过环境变量PLAYWRIGHT_DOWNLOAD_HOST来指定下载镜像。国内可以使用淘宝的镜像源加速# 在Windows PowerShell或CMD中 set PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ playwright install # 在macOS/Linux的bash/zsh中 export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright/ playwright install设置这个环境变量后下载速度会有质的提升。仅安装所需浏览器如果你确定只使用Chrome或Chromium内核的Edge进行测试可以只安装Chromium节省时间和磁盘空间。playwright install chromium其他可用的浏览器标识符有firefox,webkit。离线安装在内网或严格隔离的环境下你可以先在一台能联网的机器上执行playwright install然后将下载的浏览器缓存目录默认在~/.cache/ms-playwright或%USERPROFILE%\AppData\Local\ms-playwright整个拷贝到目标机器对应的位置再运行playwright install它会检查缓存并跳过下载。下载完成后Playwright的安装就真正完成了。这些浏览器二进制文件会被存放在用户目录下的一个固定位置与你的多个Python项目共享。4. 验证安装编写并运行你的第一个脚本理论说再多不如跑一个例子看看。我们来创建一个最简单的脚本验证整个环境是否工作正常。创建一个名为test_install.py的文件内容如下from playwright.sync_api import sync_playwright def main(): # 使用 sync_playwright 上下文管理器它会自动管理Playwright进程的启动和关闭 with sync_playwright() as p: # 启动一个Chromium浏览器实例headlessFalse表示显示浏览器界面 browser p.chromium.launch(headlessFalse) # 创建一个新的浏览器页面标签页 page browser.new_page() # 导航到百度首页 page.goto(“https://www.baidu.com”) # 获取页面标题并打印 print(f“页面标题是{page.title()}”) # 在搜索框输入“Playwright” page.fill(‘input#kw’, ‘Playwright’) # 点击“百度一下”按钮 page.click(‘input#su’) # 等待页面导航完成这里简单等待2秒实际项目应用更智能的等待 page.wait_for_timeout(2000) # 关闭浏览器 browser.close() if __name__ “__main__”: main()保存文件后在你的虚拟环境中运行它python test_install.py如果一切顺利你会看到以下情况一个Chromium浏览器窗口自动打开。浏览器访问百度首页。搜索框被自动填入“Playwright”并执行搜索。命令行输出页面标题是百度一下你就知道。浏览器自动关闭。恭喜你你的第一个Playwright自动化脚本成功运行了这个简单的流程验证了Python库、浏览器驱动、以及基本的API调用都是正常的。实操心得第一次运行脚本时如果遇到浏览器启动失败或页面卡住别慌。首先检查防火墙或安全软件是否阻止了Playwright启动子进程。其次尝试将p.chromium.launch(headlessFalse)改为p.chromium.launch(headlessTrue, slow_mo1000)。headlessTrue表示无头模式不显示界面排除了GUI可能带来的干扰slow_mo1000让每个操作延迟1秒方便你观察脚本执行到哪里出的问题。5. 开发工具链配置提升脚本编写效率一个顺手的开发环境能极大提升编写和维护自动化脚本的效率。这里我分享我的VSCode配置方案你也可以根据自己习惯的IDE进行调整。5.1 代码编辑器与智能提示Playwright为Python提供了非常好的类型提示Type Hints。在VSCode中配合Pylance或Python扩展你可以获得精准的代码自动补全、参数提示和API文档查看。确保你的VSCode安装了官方的Python扩展。在虚拟环境激活的状态下用VSCode打开项目文件夹编辑器通常会自动识别并使用该虚拟环境中的Python解释器。你可以在VSCode底部状态栏看到当前选择的Python版本和环境名。关键配置为了让智能提示更准确建议在项目根目录创建一个pyrightconfig.json或mypy.ini配置文件如果你用mypy但更简单的方式是确保你的虚拟环境中安装了playwright包VSCode的Python扩展会自动从已安装的包中读取类型信息。5.2 内置命令行工具CLI的妙用Playwright安装后会自带一个强大的命令行工具playwright。我们之前用它安装了浏览器playwright install。它还有几个在开发和调试阶段极其有用的功能5.2.1 代码生成器Codegen—— 自动化脚本的“录音笔”这是我最喜欢的功能尤其适合快速生成脚本原型或学习定位器。它打开一个浏览器和一个编辑器记录你的操作并实时生成代码。playwright codegen https://www.baidu.com执行上述命令会同时打开两个窗口一个浏览器和一个代码生成面板。你在浏览器里的所有点击、输入操作都会实时转换成Python或其他语言代码显示在面板上。你可以直接复制这些代码到你的脚本中。这是学习Playwright API和编写定位器最直观的方式。5.2.2 打开浏览器工具Open如果你想快速用某个浏览器打开一个网页用于手动测试或查看元素可以用playwright open --device“iPhone 13” https://m.baidu.com这个命令会以模拟iPhone 13设备的方式打开移动版百度对于测试响应式网页非常方便。5.2.3 截图工具Screenshot无需写脚本直接命令行截取网页全屏或完整页面。# 截取百度首页可视区域保存为baidu.png playwright screenshot https://www.baidu.com baidu.png # 截取完整长页面 playwright screenshot --full-page https://www.baidu.com baidu-full.png5.3 调试技巧让问题无处遁形编写脚本时调试是家常便饭。除了使用IDE的调试器打断点外Playwright自身也提供了多种调试手段。开启有头模式与慢动作在脚本开发初期务必使用headlessFalse来启动浏览器亲眼看到脚本的执行过程。配合slow_mo毫秒数参数可以像慢镜头一样观察每一步操作精准定位是哪个步骤出了问题。browser p.chromium.launch(headlessFalse, slow_mo1000) # 每个操作间隔1秒录制执行视频与追踪Playwright可以录制整个自动化过程的视频并生成一个可视化的追踪文件Trace。这在调试偶发问题或向开发反馈Bug时非常有用。context browser.new_context( record_video_dir“videos/”, # 视频保存目录 record_har_path“network.har” # 可选记录所有网络请求为HAR文件 ) # 启动追踪 context.tracing.start(screenshotsTrue, snapshotsTrue, sourcesTrue) # ... 执行你的测试步骤 ... # 停止追踪并保存 context.tracing.stop(path“trace.zip”)生成的trace.zip可以用Playwright的命令行工具playwright show-trace trace.zip打开这是一个图形化界面可以逐帧查看DOM状态、网络请求、控制台日志是终极调试利器。6. 项目结构规划为可持续维护做准备在开始大规模编写脚本前花一点时间规划一下项目目录结构未来你会感谢自己。一个混乱的项目很快就会变得难以维护。以下是我经过多个项目总结出的一个清晰结构your_ui_auto_project/ ├── requirements.txt # 项目依赖声明 ├── conftest.py # Pytest的全局配置、Fixture定义如果使用Pytest ├── pytest.ini # Pytest配置文件 ├── pages/ # 页面对象模型Page Object目录 │ ├── __init__.py │ ├── login_page.py # 登录页面 │ └── home_page.py # 主页 ├── locators/ # 定位器集中管理可选可与Page Object合并 │ ├── __init__.py │ └── login_locators.py ├── tests/ # 测试用例目录 │ ├── __init__.py │ ├── test_login.py # 登录测试 │ └── test_search.py # 搜索测试 ├── fixtures/ # 测试数据、全局Fixture │ └── test_data.json ├── utils/ # 工具函数 │ ├── __init__.py │ ├── logger.py # 日志工具 │ └── api_client.py # 封装API调用用于混合测试 ├── reports/ # 测试报告输出目录.gitignore忽略 │ └── allure-results/ ├── videos/ # 录屏输出目录.gitignore忽略 ├── traces/ # 追踪文件输出目录.gitignore忽略 └── .gitignore关键文件说明requirements.txt: 使用pip freeze requirements.txt生成确保团队成员环境一致。conftest.py: 如果你使用Pytest作为测试运行框架我强烈推荐可以在这里定义全局的浏览器Fixture这样每个测试用例无需自己管理浏览器的启动和关闭。# conftest.py 示例 import pytest from playwright.sync_api import Page, BrowserContext pytest.fixture(scope“session”) def browser_context_args(browser_context_args): # 为所有浏览器上下文添加默认设置如视口大小、语言 return { **browser_context_args, “viewport”: {“width”: 1920, “height”: 1080}, “locale”: “zh-CN” } pytest.fixture(scope“function”) def page(context: BrowserContext): # 为每个测试函数提供一个全新的页面 new_page context.new_page() yield new_page new_page.close()pages/: 采用**页面对象模型Page Object Model, POM**设计模式。将每个页面的元素定位和操作封装成类。这是保持代码可维护性的黄金法则。例如login_page.py里会有LoginPage类包含用户名输入框、密码输入框、登录按钮的定位器以及login(username, password)这样的方法。7. 常见问题与排查技巧实录即便按照步骤操作你也可能会遇到一些问题。这里我整理了新手最常遇到的几个“坑”及其解决方案。7.1 浏览器安装失败或速度极慢问题现象执行playwright install时卡住或报网络错误、超时。排查与解决检查网络连接确保你的机器可以访问外网。尝试ping一下playwright.azureedge.net。使用国内镜像这是最有效的解决方案。如前所述设置PLAYWRIGHT_DOWNLOAD_HOST环境变量为https://npmmirror.com/mirrors/playwright/。手动下载如果镜像也不行可以尝试在Playwright的GitHub Release页面找到对应版本的浏览器包手动下载然后放到缓存目录。但这种方法较复杂不推荐新手。权限问题Windows如果在公司网络或受控环境中可能需要管理员权限才能向%USERPROFILE%\AppData\Local目录写入文件。尝试以管理员身份运行命令行。7.2 执行脚本时报浏览器启动错误问题现象运行脚本时提示Executable doesn‘t exist at ...或Failed to launch browser。排查与解决确认浏览器已安装运行playwright install chromium确保指定浏览器已成功安装。检查缓存目录是否存在对应的浏览器可执行文件。杀毒软件/防火墙拦截一些安全软件可能会将Playwright启动的浏览器子进程误判为恶意软件而阻止。尝试临时关闭杀毒软件或防火墙或将Playwright的缓存目录加入白名单。端口冲突Playwright启动浏览器时会使用一些本地端口。如果端口被占用可能导致启动失败。重启电脑通常可以解决临时性的端口占用问题。7.3 脚本运行时元素找不到定位器问题问题现象脚本报错Timeout 30000ms exceeded. waiting for selector “...”这是新手最高频的错误。排查与解决使用Codegen生成定位器对于不熟悉的页面先用playwright codegen录制操作看看它生成的定位器是什么。Playwright的定位器语法非常强大且易读。检查页面加载状态在操作元素前确保页面已经加载完成。可以使用page.wait_for_load_state(‘networkidle’)等待网络空闲或page.wait_for_selector(‘selector’)等待特定元素出现。处理动态内容/iframe如果元素在iframe内部你需要先切换到对应的framepage.frame_locator(‘iframe-selector’).locator(‘inner-element’)。如果元素是动态生成的如Ajax加载需要等待其出现在DOM中。使用更稳健的定位器优先使用page.get_by_role()、page.get_by_text()、page.get_by_test_id()这些基于语义和可访问性的定位器它们比纯粹的CSS或XPath更稳定。例如page.get_by_role(“button”, name“登录”)就比page.click(“#loginBtn”)更能抵抗前端代码的微小改动。7.4 在CI/CD环境如Jenkins、GitHub Actions中运行失败问题现象脚本在本地运行良好但在无界面的CI服务器上失败。排查与解决确保安装依赖在CI的构建步骤中不仅要pip install playwright还必须运行playwright install --with-deps chromium。--with-deps参数会安装Chromium运行所需的系统依赖如字体库这在纯净的Linux Docker镜像中尤其重要。使用无头模式在CI中必须使用headlessTrue默认就是True来启动浏览器。配置合适的沙盒环境在某些严格的容器环境如某些Docker配置中需要禁用沙盒模式才能启动Chromiumbrowser p.chromium.launch(args[‘--no-sandbox’, ‘--disable-setuid-sandbox’])。注意这降低了安全性仅应在你完全信任的隔离测试环境中使用。安装和配置是万里长征的第一步但也是最关键的一步。一个稳定、可复现的环境是自动化测试资产你的测试脚本能够持续产生价值的基础。花时间理解并解决好环境问题后续的脚本开发就会顺畅很多。在下一篇教程中我们将深入Playwright的核心API学习如何与页面元素进行丰富而稳健的交互。