Playwright实战：5分钟搞定网页自动化测试（Python版）

如果你是一名Python开发者，正被那些重复、繁琐的网页操作搞得焦头烂额，比如每天要手动测试十几个页面的登录流程，或者需要从一堆动态加载的表格里定时抓取数据，那么这篇文章就是为你准备的。我们不再讨论那些冗长的理论或复杂的架构，而是直接切入核心：如何用Playwright这个现代工具，在最短的时间内，写出能立刻投入生产的自动化脚本。想象一下，原本需要你手动点击、输入、等待的半小时工作，现在只需一段代码、一次运行，就能在后台精准无误地完成。这就是自动化带来的效率革命，而Playwright正是实现这场革命中最锋利的那把瑞士军刀。它不仅仅是一个测试工具，更是任何需要与浏览器交互的自动化场景的终极解决方案。接下来，我将带你绕过基础概念的泥沼，直抵最具实战价值的代码片段和场景化策略，让你在5分钟内，感受到自动化脚本从零到一跑起来的快感。

1. 极速启动：你的第一个自动化脚本

在深入具体场景之前，我们必须先搭建好战场。Playwright的安装和初始化过程异常简洁，这与其强大的功能形成了鲜明对比。很多开发者卡在第一步，往往是因为环境配置或版本兼容性问题，我们将彻底避开这些坑。

首先，打开你的终端，执行以下命令来安装Playwright的Python库及其所需的浏览器内核。这里有一个关键细节：强烈建议在虚拟环境中进行，以避免与系统其他Python包的依赖冲突。

# 创建并激活虚拟环境（以venv为例）
python -m venv playwright-env
source playwright-env/bin/activate  # Linux/macOS
# 或 playwright-env\Scripts\activate  # Windows

# 安装Playwright Python包
pip install playwright

# 安装Chromium, Firefox和WebKit浏览器内核
playwright install

playwright install 这一步至关重要，它会下载所有支持的浏览器（Chromium、Firefox、WebKit）的可执行文件到本地缓存中。这样，你的脚本就具备了跨浏览器运行的能力，而无需在系统上单独安装这些浏览器。

现在，让我们用最少的代码，打开一个浏览器，访问一个页面，并获取其标题。这是验证环境是否就绪的最佳方式。

from playwright.sync_api import sync_playwright

def quick_start():
    with sync_playwright() as p:
        # 启动Chromium浏览器，headless=True表示无头模式（不显示GUI）
        browser = p.chromium.launch(headless=True)
        # 创建一个新的浏览器上下文和页面
        page = browser.new_page()
        # 导航到目标网址
        page.goto("https://httpbin.org/headers")
        # 打印页面标题
        print(f"页面标题: {page.title()}")
        # 关闭浏览器
        browser.close()

if __name__ == "__main__":
    quick_start()

将这段代码保存为 quick_demo.py 并运行。如果一切顺利，你将看到终端打印出 httpbin.org 页面的标题。恭喜，你的自动化引擎已经成功点火！这里我们使用了 sync_playwright 同步API，它更符合大多数脚本编写的直觉。对于需要高并发的复杂场景，Playwright也提供了功能完全一致的异步API (async_playwright)。

注意：在自动化脚本开发初期，建议将 launch(headless=True) 改为 headless=False，这样你可以亲眼看到浏览器的每一步操作，便于调试。上线或定时任务执行时，再切换回无头模式以节省资源。

2. 核心交互：模拟真实用户操作的精髓

自动化脚本的灵魂在于它能多么逼真地模仿人类用户。Playwright提供了一套极其直观且强大的API来处理所有常见交互：点击、输入、选择、拖拽等。我们不再罗列所有方法，而是通过一个整合了多种操作的用户登录与信息编辑的连贯场景来掌握它们。

假设我们要自动化测试一个用户管理后台：登录 -> 进入个人资料页 -> 修改昵称和简介 -> 保存。下面是一个完整的脚本示例：

from playwright.sync_api import sync_playwright
import time

def user_profile_automation():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=False) # 可视化运行，方便观察
        page = browser.new_page()

        # 1. 导航到登录页
        page.goto("https://example-test-site.com/login")
        page.wait_for_load_state("networkidle") # 等待页面网络空闲，确保元素加载完毕

        # 2. 填写登录表单
        # 使用CSS选择器定位输入框并输入文本
        page.fill('input[name="email"]', 'your_email@example.com')
        page.fill('input[name="password"]', 'your_secure_password')

        # 3. 点击登录按钮
        # 这里演示了多种点击方式，推荐使用最精确的选择器
        page.click('button:has-text("Sign In")') # 点击包含“Sign In”文字的按钮

        # 4. 等待登录成功并跳转
        page.wait_for_url("**/dashboard") # 使用通配符等待URL包含dashboard

        # 5. 导航到个人资料页
        profile_link = page.get_by_role("link", name="My Profile") # 使用角色定位，更语义化
        profile_link.click()

        # 6. 在个人资料页进行编辑
        page.wait_for_selector("#profile-form")

        # 清空原有昵称并输入新昵称
        nickname_input = page.locator("#nickname")
        nickname_input.clear()
        nickname_input.type("NewAwesomeNickname", delay=100) # delay模拟真人输入节奏

        # 使用fill快速替换简介（fill会自动先清空）
        page.fill("#bio", "热爱技术，专注自动化，用代码解放双手。")

        # 7. 处理下拉选择框
        page.select_option("#country", label="中国") # 通过显示的文本选择

        # 8. 处理单选框 (Radio Button)
        page.check('input[value="public"]') # 选择值为“public”的单选框

        # 9. 处理复选框 (Checkbox)
        if not page.is_checked("#newsletter"):
            page.check("#newsletter") # 如果未勾选，则勾选订阅复选框

        # 10. 保存表单（模拟键盘回车提交）
        page.press("#profile-form", "Enter")

        # 11. 等待保存成功的提示信息出现
        success_toast = page.locator("text=Profile updated successfully")
        success_toast.wait_for(state="visible")
        print("个人资料更新成功！")

        # 稍作停留以便观察，然后关闭
        time.sleep(2)
        browser.close()

if __name__ == "__main__":
    user_profile_automation()

这个脚本几乎涵盖了80%的日常网页交互操作。其中几个关键点值得深入探讨：

• 选择器策略：page.fill(‘input[name=”email”]‘, …) 使用了属性选择器，非常稳健。page.get_by_role(“link”, name=”My Profile”) 是Playwright推荐的方式，它基于ARIA角色，可访问性最好，且不易因前端样式改动而失效。
• 等待机制：这是编写稳定自动化脚本的重中之重。Playwright内置了智能等待，但显式使用 wait_for_load_state、wait_for_url、wait_for_selector 能让脚本更健壮。networkidle 状态非常实用，表示页面在至少500ms内没有新的网络请求。
• type vs fill：type 会模拟逐个字符输入，并可以设置 delay；fill 则是先清空再一次性设置值，速度更快。根据场景选择，需要触发输入事件时用 type，单纯设置值用 fill。

3. 高级场景与故障处理实战

掌握了基本交互后，我们会遇到更复杂的场景：处理弹窗、上传文件、拦截网络请求、应对动态加载元素。这些才是区分“玩具脚本”和“生产级脚本”的关键。

3.1 处理文件上传与下载

文件上传不再是自动化测试的噩梦。Playwright让你可以像设置输入框文本一样轻松处理文件。

# 片段：处理单文件和多文件上传
page.goto("https://example.com/upload")

# 单文件上传 - 直接设置文件路径
page.set_input_files('input[type="file"]', "path/to/your/file.pdf")

# 多文件上传 - 传递一个路径列表
page.set_input_files('input[type="file"]', ["file1.jpg", "file2.png"])

# 如果需要清空已选文件
page.set_input_files('input[type="file"]', [])

对于文件下载，你需要监听 download 事件，并决定文件的保存路径。

# 片段：监听并保存下载文件
with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()

    # 监听下载事件
    download_event = page.wait_for_event("download")
    # 触发下载的操作，例如点击一个下载链接
    page.click("a#download-report")

    # 等待下载事件发生，并获取下载对象
    download = download_event.value
    # 指定保存路径
    save_path = f"./downloads/{download.suggested_filename}"
    download.save_as(save_path)
    print(f"文件已下载至: {save_path}")

3.2 拦截与修改网络请求

这个功能强大到令人惊叹。你可以拦截请求以模拟慢速网络、修改请求头/响应体、屏蔽某些资源（如图片）以加速测试，或者直接伪造API返回数据。

def intercept_requests():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=True)
        page = browser.new_page()

        # 启用请求拦截
        page.route("**/*.css", lambda route: route.abort())  # 拦截并中止所有CSS请求，加速页面加载
        page.route("**/api/user", lambda route: route.fulfill(
            status=200,
            content_type="application/json",
            body='{"name": "Mock User", "id": 123}'  # 伪造API响应
        ))

        page.goto("https://example.com")
        # 此时页面加载没有CSS，且用户API返回了我们伪造的数据
        browser.close()

3.3 应对弹窗、新窗口与iframe

现代网页应用充满了弹窗和嵌入式内容。Playwright能让你轻松地在不同的上下文之间切换。

def handle_popups_and_frames():
    with sync_playwright() as p:
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()
        page.goto("https://example.com")

        # 监听并处理弹窗（alert, confirm, prompt）
        page.on("dialog", lambda dialog: dialog.accept())  # 自动接受所有弹窗

        # 点击一个会打开新窗口/标签页的链接
        with page.expect_popup() as popup_info:
            page.click("a[target='_blank']")
        new_page = popup_info.value
        # 现在可以在新页面上操作了
        print(new_page.title())

        # 处理iframe内的元素
        frame = page.frame(name="embedded-form")  # 通过name或URL定位iframe
        if frame:
            frame.fill("#inside-frame-input", "Hello from inside iframe")

        browser.close()

3.4 元素等待策略与重试机制

元素定位失败是自动化脚本最常见的错误。除了使用 wait_for_selector，Playwright的 locator 对象本身内置了自动等待和重试机制，这是其稳定性的核心。

# 不稳定的写法：直接操作，如果元素未加载则报错
page.click(".dynamic-button")

# 稳健的写法1：显式等待
page.wait_for_selector(".dynamic-button", state="visible", timeout=10000)
page.click(".dynamic-button")

# 稳健的写法2（推荐）：使用Locator API，它内部已包含等待
button = page.locator(".dynamic-button").first # 获取匹配的第一个元素
button.wait_for(state="attached") # 可选，等待元素附加到DOM
button.click()

# 处理可能因动画而不可点击的情况
button.click(force=True) # force参数可以绕过可点击性检查

为了构建真正健壮的脚本，我通常会封装一个带重试和截图功能的通用操作函数。

def robust_click_with_retry(page, selector, max_retries=3):
    for attempt in range(max_retries):
        try:
            element = page.locator(selector).first
            element.wait_for(state="visible", timeout=5000)
            element.click()
            print(f"成功点击元素: {selector}")
            return True
        except Exception as e:
            print(f"点击尝试 {attempt + 1} 失败: {e}")
            if attempt == max_retries - 1:
                # 最后一次尝试失败，截图保存证据
                page.screenshot(path=f"error_click_{selector.replace(':', '_')}.png")
                raise
            page.wait_for_timeout(1000) # 等待1秒后重试
    return False

4. 从脚本到方案：工程化与持续集成

单个脚本能跑起来只是第一步。如何管理几十上百个测试用例？如何让它们每天自动运行并报告结果？这就需要一点简单的工程化思维。

4.1 使用Pytest组织测试用例

Pytest是Python生态中最主流的测试框架，与Playwright结合得天衣无缝。你可以将每个自动化场景组织成一个独立的测试函数或类。

首先，安装pytest和pytest-playwright插件：

pip install pytest pytest-playwright

然后，创建一个测试文件 test_login.py：

import pytest
from playwright.sync_api import Page

@pytest.fixture(scope="function")
def page(browser):
    # 每个测试函数获得一个全新的页面上下文
    context = browser.new_context()
    page = context.new_page()
    yield page
    context.close()

def test_successful_login(page: Page):
    """测试用户使用正确凭据登录"""
    page.goto("https://example.com/login")
    page.fill("#username", "valid_user")
    page.fill("#password", "valid_pass")
    page.click("#login-btn")
    assert page.url == "https://example.com/dashboard"
    assert page.is_visible("text=Welcome, valid_user")

def test_login_with_wrong_password(page: Page):
    """测试使用错误密码登录应显示错误信息"""
    page.goto("https://example.com/login")
    page.fill("#username", "valid_user")
    page.fill("#password", "wrong_pass")
    page.click("#login-btn")
    error_msg = page.locator(".alert-error")
    assert error_msg.is_visible()
    assert "密码错误" in error_msg.text_content()

使用 pytest test_login.py -v 运行测试，你会看到清晰的通过/失败报告。Pytest的fixture机制（如上面的 page）能优雅地管理浏览器和页面的生命周期。

4.2 生成丰富的测试报告与追踪

Playwright Test（与pytest-playwright不同，是Playwright官方提供的测试运行器）能生成极其详尽的HTML报告，包含每一步的操作截图、时间线追踪和视频录制。虽然本文基于同步API和pytest，但了解这个强大的官方方案也很有必要。你可以通过 playwright.config.py 配置文件轻松启用视频录制：

# playwright.config.py
import os
from playwright.sync_api import Playwright, sync_playwright

def run(playwright: Playwright):
    browser = playwright.chromium.launch(headless=False)
    context = browser.new_context(record_video_dir="./videos/") # 启用视频录制
    page = context.new_page()
    # ... 你的测试步骤 ...
    context.close()
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

4.3 集成到CI/CD流水线

最后，让自动化脚本在GitHub Actions、GitLab CI或Jenkins上定时运行，是实现其价值的最后一公里。核心是在CI环境中安装浏览器依赖并以无头模式运行。

下面是一个GitHub Actions工作流的示例片段：

# .github/workflows/playwright-ci.yml
name: Playwright Automation Tests
on: [push, schedule] # 支持定时任务
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.10'
    - name: Install dependencies
      run: |
        pip install -r requirements.txt
        playwright install --with-deps chromium # CI中通常只安装一个浏览器以节省时间
    - name: Run your automation script
      run: python your_main_automation_script.py
    - name: Run Pytest Tests
      run: pytest --html=report.html --self-contained-html
    - uses: actions/upload-artifact@v3
      if: always() # 即使测试失败也上传报告
      with:
        name: test-report
        path: |
          report.html
          ./videos/*.webm
          ./error_screenshots/*.png

当你的脚本能在这个工作流中稳定运行，并将报告和问题截图自动归档时，你就构建了一个低维护成本、高反馈效率的自动化监控或测试系统。这不再是简单的脚本，而是一个可靠的数字员工。