Playwright 入门教程：使用 Python 自动化浏览器操作

Playwright 是由 Microsoft 开发的现代化浏览器自动化工具，支持 Chromium、Firefox 和 WebKit 三大浏览器引擎。它具备速度快、功能强大、跨平台、支持无头/有头模式、自动等待、网络拦截、截图录屏等特性，是 Web 自动化测试、爬虫、端到端测试的理想选择。

本教程将带你从零开始掌握 Playwright 的基本用法。

---

1. 安装 Playwright

安装 Python 包

pip install playwright

安装浏览器驱动

Playwright 需要下载对应的浏览器二进制文件（Chromium、Firefox、WebKit）：

playwright install

如果你只需要特定浏览器（如仅 Chromium），可以运行：

playwright install chromium

注意：首次运行 playwright install 可能需要几分钟，因为它会下载多个浏览器。

---

2. 第一个 Playwright 脚本

创建一个名为 first_script.py 的文件：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)  # 启动 Chromium，有头模式
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    page.screenshot(path="example.png")
    browser.close()

运行：

python first_script.py

你会看到浏览器窗口打开，访问 example.com，打印页面标题，并保存截图。

---

3. 启动浏览器与页面

启动选项

• headless=True（默认）：无头模式（后台运行）
• headless=False：有头模式（可见浏览器）
• slow_mo=100：每步操作延迟 100ms，便于调试
• devtools=True：自动打开开发者工具

browser = p.chromium.launch(
    headless=False,
    slow_mo=100,
    devtools=True
)

创建新页面

page = browser.new_page()

访问 URL

page.goto("https://www.baidu.com")

goto() 会自动等待页面加载完成（包括网络空闲状态）。

---

4. 定位元素

Playwright 支持多种定位策略：

方法	说明
page.locator("text=登录")	按文本定位
page.locator("#username")	CSS 选择器
page.locator("input[name='email']")	CSS 选择器
page.locator("xpath=//button[@id='submit']")	XPath（不推荐，优先用 CSS 或文本）
page.get_by_role("button", name="Submit")	按 ARIA 角色和名称（推荐）
page.get_by_label("Username")	按 label 关联的输入框

示例

# 通过文本点击按钮
page.locator("text=立即登录").click()

# 通过 CSS 输入文本
page.locator("#kw").fill("Playwright 教程")

# 通过角色定位（更语义化）
page.get_by_role("button", name="搜索").click()

推荐：优先使用 get_by_* 系列方法（如 get_by_role, get_by_label, get_by_placeholder），它们更稳定、可读性更强。

---

5. 交互操作

常用操作

操作	方法
输入文本	fill()（清空后输入）或 type()（逐字输入）
点击	click()
双击	dblclick()
右键	click(button="right")
悬停	hover()
选择下拉框	select_option()
上传文件	set_input_files()
检查复选框	check() / uncheck()

示例

# 填写表单
page.locator("#username").fill("user123")
page.locator("#password").fill("pass456")

# 点击登录
page.locator("button[type='submit']").click()

# 选择下拉选项
page.locator("#country").select_option("China")

# 上传文件
page.locator("input[type='file']").set_input_files("test.pdf")

# 检查复选框
page.locator("#agree").check()

---

6. 等待机制

Playwright 自动等待元素可操作（可见、可点击等），但有时仍需显式等待。

自动等待（推荐）

# 自动等待按钮可点击后才点击
page.locator("#submit").click()

显式等待

• 等待元素出现：

  page.wait_for_selector("#result", state="visible")

• 等待导航完成：

  with page.expect_navigation():
      page.click("a[href='/next']")

• 等待特定 URL：

  page.wait_for_url("**/dashboard")

• 等待函数返回真值：

  page.wait_for_function("() => window.innerWidth < 100")

---

7. 截图与录屏

截图

# 整页截图
page.screenshot(path="full.png", full_page=True)

# 元素截图
page.locator(".header").screenshot(path="header.png")

录屏（视频）

browser = p.chromium.launch()
context = browser.new_context(record_video_dir="videos/")
page = context.new_page()
page.goto("https://example.com")
# ... 操作
context.close()  # 视频保存在 videos/ 目录

视频文件名格式：<timestamp>-<random>.webm

---

8. 网络请求拦截与模拟

拦截请求

def handle_route(route):
    if "ads" in route.request.url:
        route.abort()  # 屏蔽广告
    else:
        route.continue_()

page.route("**/*", handle_route)

修改响应

def mock_api(route):
    route.fulfill(json={"status": "mocked"})

page.route("**/api/data", mock_api)

监听响应

def log_response(response):
    if "/api/" in response.url:
        print(f"API Response: {response.url} -> {response.status}")

page.on("response", log_response)

---

9. 上下文（Context）与多页面

上下文（Context）

• 一个浏览器可创建多个上下文（类似隐身窗口）
• 上下文之间完全隔离（Cookie、Storage 等不共享）

context1 = browser.new_context()
page1 = context1.new_page()

context2 = browser.new_context()
page2 = context2.new_page()

多页面操作

page1 = context.new_page()
page1.goto("https://a.com")

page2 = context.new_page()
page2.goto("https://b.com")

# 切换页面
page1.bring_to_front()

页面事件监听

def on_popup(popup):
    print("新弹窗打开:", popup.url)

page.on("popup", on_popup)

---

10. 配置与最佳实践

使用 pytest + Playwright（推荐用于测试）

安装：

pip install pytest-playwright

编写测试：

# test_example.py
def test_homepage_has_title(page):
    page.goto("https://example.com")
    assert page.title() == "Example Domain"

运行：

pytest --browser chromium --headed

配置文件 playwright.config.py

# playwright.config.py
import os

def get_config():
    return {
        "use": {
            "headless": True,
            "viewport": {"width": 1920, "height": 1080},
            "locale": "zh-CN",
            "timezone_id": "Asia/Shanghai",
        },
        "projects": [
            {"name": "chromium", "use": {"browser_name": "chromium"}},
            {"name": "firefox", "use": {"browser_name": "firefox"}},
        ]
    }

最佳实践

• 优先使用 get_by_* 定位器
• 避免使用 time.sleep()，用 Playwright 内置等待
• 使用上下文隔离不同用户会话
• 在 CI 中使用无头模式
• 敏感操作（如密码）使用环境变量

---

11. 常见问题

Q1: Playwright 和 Selenium 有什么区别？

• Playwright 更现代，API 更简洁
• Playwright 自动等待，减少 flaky 测试
• Playwright 支持网络拦截、录屏、移动端模拟等高级功能
• Playwright 启动速度更快，资源占用更低

Q2: 如何处理 iframe？

frame = page.frame_locator("iframe[name='myframe']")
frame.locator("#inside-input").fill("text")

Q3: 如何模拟移动端？

iphone = p.devices["iPhone 13"]
context = browser.new_context(**iphone)

Q4: 如何保存/加载 Cookie？

# 保存
storage = context.storage_state(path="auth.json")

# 加载
context = browser.new_context(storage_state="auth.json")

---

结语

Playwright 是目前最强大的浏览器自动化工具之一，其简洁的 API、强大的功能和良好的文档使其成为 Python 自动化开发的首选。

📚 官方文档：https://playwright.dev/python/

现在，你可以开始构建自己的自动化脚本、爬虫或端到端测试了！

---

Happy Coding with Playwright! 🚀