一、安装与入口（极简）
pip install playwright playwright install # 安装浏览器驱动
from playwright.sync_api import sync_playwrightwith sync_playwright() as p:browser = p.chromium.launch(headless=False) # 或 firefox / webkitpage = browser.new_page()# ... 业务代码browser.close()
二、页面导航与基础信息
page.goto("https://example.com") # 跳转 page.goto("https://example.com", wait_until="networkidle")page.url # 当前URL page.title() # 标题 page.content() # 页面HTML page.screenshot(path="s.png", full_page=True) # 截图 page.pdf(path="out.pdf") # 仅无头chromium
三、元素定位（Locator，重点）
推荐统一用 page.locator(selector)，返回 Locator 对象，可链式操作。
1）CSS / ID / 类 / 属性
page.locator("#id") # ID page.locator(".class") # class page.locator("input[name='pwd']") # 属性 page.locator("div.container > button") # 层级
2）XPath
page.locator("//button[@type='submit']")
3）文本定位（最实用）
page.get_by_text("登录") # 模糊匹配 page.get_by_text("登录", exact=True) # 精确匹配 page.locator("text=登录") # 等价写法
4）角色定位（现代页面优先）
page.get_by_role("button", name="登录") page.get_by_role("textbox", name="用户名")
5）组合、嵌套、多元素
page.locator("form >> input[name='user']") # 组合 page.locator(".list").first # 第一个 page.locator(".list").last # 最后一个 page.locator(".list").nth(2) # 第3个（0开始） page.locator(".item").count() # 数量
四、常用元素交互
1）点击
page.locator("button").click() page.locator("button").click(force=True) # 强制点击（不可见）
2）输入 / 清空
page.locator("#user").fill("test@example.com") # 清空+输入（推荐） page.locator("#user").type("slow", delay=100) # 模拟慢速输入 page.locator("#user").clear() # 清空
3）单选 / 复选 / 下拉
page.locator("#agree").check() # 勾选 page.locator("#agree").uncheck() # 取消 page.locator("select").select_option("value") # 下拉选值 page.locator("select").select_option(label="女") # 按文本选
4）键盘与按键
page.locator("#input").press("Enter") page.locator("#input").press("Control+A") # 组合键
5）文件上传
page.locator("input[type='file']").set_input_files("a.jpg")
6）拖拽
page.locator("#src").drag_to(page.locator("#dst"))
五、等待机制（内置智能等待，极少需要手动 sleep）
1）等待元素
page.locator(".ready").wait_for() # 等待出现 page.locator(".hide").wait_for(state="hidden") # 等待消失
2）等待页面 / 请求
page.wait_for_load_state("load") page.wait_for_load_state("networkidle") page.wait_for_url("**/success")
六、断言（推荐用 expect，自动等待）Playwright
from playwright.sync_api import expect# 元素文本/值 expect(page.locator("h1")).to_have_text("欢迎") expect(page.locator("input")).to_have_value("123")# 页面 expect(page).to_have_title("首页") expect(page).to_have_url("https://example.com")# 元素状态 expect(page.locator(".btn")).to_be_enabled() expect(page.locator(".alert")).to_be_visible() expect(page.locator("#agree")).to_be_checked()# 包含文本/数量 expect(page.locator(".msg")).to_contain_text("成功") expect(page.locator(".item")).to_have_count(5)
七、执行 JavaScript
# 1. 简单执行+返回值 title = page.evaluate("document.title") sum_val = page.evaluate("([a,b]) => a+b", [1,2])# 2. 元素上执行 page.locator("#box").evaluate("el => el.style.color='red'")# 3. 页面加载前注入脚本 page.add_init_script("Math.random = () => 0.1")
八、浏览器上下文与多页面
context = browser.new_context() # 独立上下文（cookie隔离） page = context.new_page()# 监听新页面 with context.expect_page() as new_info:page.click("a[target='_blank']") new_page = new_info.value new_page.wait_for_load_state()# 切换页面 context.pages[1].bring_to_front()
九、高频简写（快速写用例）
# 链式一气呵成 page.locator("#user").fill("admin") page.locator("#pwd").fill("123456") page.locator("text=登录").click() expect(page.locator("text=欢迎回来")).to_be_visible()