一、文档概述
本文档针对Python+Playwright+Pytest+Allure UI自动化测试技术栈，提供全套落地使用方案，包含环境部署、框架整合、用例编写、断言封装、元素等待、截图日志、测试报告、项目规范及常见问题排查，适用于Web端自动化测试项目开发、维护及团队协作。
技术栈核心能力
Python：主流脚本编程语言，简洁高效，生态丰富
Playwright：微软开源自动化引擎，支持Chrome/Firefox/Safari/Edge，自动等待、无弹窗、兼容性强
Pytest：Python主流测试框架，支持用例管理、参数化、夹具、跳过、失败重跑
Allure：高颜值可视化测试报告，支持步骤分层、截图嵌入、用例标签、失败溯源
二、环境搭建（零基础部署）
2.1 基础环境要求
Python 版本：3.8 ~ 3.11（推荐3.10，兼容性最佳）
操作系统：Windows / MacOS / Linux 全平台支持
依赖工具：pip、Allure命令行工具
2.2 Python依赖库安装
新建项目，打开终端执行以下命令安装核心依赖：
Plain Text# 核心自动化、测试框架、报告插件pip install playwright pytest allure-pytest# 可选扩展：失败重跑、时间处理、数据读取pip install pytest-rerunfailures python-dotenv pyyaml
2.3 Playwright浏览器驱动安装
Playwright无需手动下载驱动，一键自动安装各浏览器内核：
Plain Textplaywright install
单独安装指定浏览器（按需选择）：
Plain Textplaywright install chromiumplaywright install firefoxplaywright install webkit
2.4 Allure命令行工具安装
Allure生成可视化报告需要系统级命令行工具，必须单独安装。
Windows安装
-
下载Allure压缩包：https://github.com/allure-framework/allure2/releases
-
解压后将 bin 目录配置到系统环境变量
-
终端验证：allure --version（输出版本号即成功）
MacOS安装
Plain Textbrew install allure
Linux安装
Plain Textsudo apt-add-repository ppa:qameta/alluresudo apt updatesudo apt install allure
三、项目标准目录结构
推荐企业级标准化目录，适配多模块、多页面、可维护性项目：
Plain Textauto_test_project/├── cases/ # 测试用例目录│ ├── test_login.py # 登录模块用例│ ├── test_index.py # 首页模块用例│ └── test_user.py # 用户模块用例├── common/ # 公共封装模块│ ├── base_page.py # 页面基础类（封装浏览器操作）│ └── conftest.py # Pytest全局夹具├── config/ # 配置文件│ └── config.py # 项目配置（浏览器、地址、超时时间）├── report/ # 测试报告目录│ ├── allure-results/ # 原始报告数据（自动生成）│ └── allure-html/ # 可视化报告（自动生成）├── pytest.ini # Pytest全局配置文件└── requirements.txt # 依赖版本记录
四、核心配置文件编写
4.1 pytest.ini 全局配置
项目根目录新建 pytest.ini，统一配置用例规则、日志、报告参数：
Plain Text[pytest]# 用例文件名匹配规则python_files = test_.py# 用例类名匹配规则python_classes = Test# 用例方法名匹配规则python_functions = test_*# 测试报告原始数据存储路径allure_dir = report/allure-results# 失败重跑次数reruns = 1# 重跑间隔时间（秒）reruns_delay = 2# 编码格式utf8 = true
4.2 config.py 项目配置
统一管理浏览器类型、超时时间、测试地址，便于环境切换：
Plain Text# config/config.pyclass Config: # 测试环境地址 BASE_URL = “https://xxx.test.com” # 元素超时等待时间（秒） TIMEOUT = 30 # 浏览器类型：chromium / firefox / webkit BROWSER = “chromium” # 是否无头模式（True无界面，False可视化界面） HEADLESS = False # 窗口大小 WINDOW_SIZE = (1920, 1080)
4.3 全局夹具 conftest.py
封装浏览器启动、关闭、页面实例化，全局所有用例自动调用，无需重复编写：
Plain Text# common/conftest.pyimport pytestfrom playwright.sync_api import sync_playwrightfrom config.config import Config@pytest.fixture(scope=“session”)def page(): # 启动Playwright with sync_playwright() as p: # 启动浏览器 browser = getattr(p, Config.BROWSER).launch( headless=Config.HEADLESS, slow_mo=500 # 操作延迟，调试用 ) # 创建上下文 context = browser.new_context( viewport={“width”: Config.WINDOW_SIZE[0], “height”: Config.WINDOW_SIZE[1]} ) # 新建页面 page = context.new_page() # 设置全局超时 page.set_default_timeout(Config.TIMEOUT * 1000) # 打开测试地址 page.goto(Config.BASE_URL) yield page # 用例执行完毕后关闭浏览器 context.close() browser.close()
五、Playwright核心操作封装
封装基础页面操作，统一操作方法，简化用例代码，base_page.py：
Plain Text# common/base_page.pyfrom playwright.sync_api import Pageclass BasePage: def init(self, page: Page): self.page = page # 点击元素 def click(self, locator): self.page.locator(locator).click() # 输入文本 def input_text(self, locator, text): self.page.locator(locator).fill(text) # 获取元素文本 def get_text(self, locator): return self.page.locator(locator).text_content().strip() # 判断元素是否可见 def is_visible(self, locator): return self.page.locator(locator).is_visible() # 强制等待 def wait(self, seconds): self.page.wait_for_timeout(seconds * 1000) # 截图（用于Allure报告） def save_screenshot(self, path): self.page.screenshot(path=path)
六、测试用例标准编写
6.1 基础用例模板
遵循Pytest规范，结合Allure步骤分层、标签、标题美化用例：
Plain Text# cases/test_login.pyimport allurefrom common.base_page import BasePage@allure.feature(“登录模块”) # 模块标签class TestLogin: @allure.story(“账号密码登录”) # 用例子模块 @allure.title(“正常账号登录成功校验”) # 用例标题 def test_login_success(self, page): # 初始化页面 base = BasePage(page) # 步骤1：输入用户名 with allure.step(“输入登录用户名”): base.input_text(“#username”, “test01”) # 步骤2：输入密码 with allure.step(“输入登录密码”): base.input_text(“#password”, “123456”) # 步骤3：点击登录 with allure.step(“点击登录按钮”): base.click(“#login-btn”) # 步骤4：断言登录成功 with allure.step(“校验登录结果”): assert base.is_visible(“.user-info”), “登录失败，未进入首页”
6.2 常用高级用法
6.2.1 用例参数化
Plain Textimport pytest@allure.story(“登录异常场景”)@pytest.mark.parametrize(“username,pwd,expect_tip”, [ (“”, “123456”, “用户名不能为空”), (“test01”, “”, “密码不能为空”), (“test01”, “111111”, “密码错误”)])def test_login_error(page, username, pwd, expect_tip): base = BasePage(page) base.input_text(“#username”, username) base.input_text(“#password”, pwd) base.click(“#login-btn”) assert base.get_text(“.tip-text”) == expect_tip
6.2.2 失败自动截图
修改conftest，用例失败自动截图嵌入Allure报告：
Plain Text# 新增到conftest.pyimport allure@pytest.fixture(autouse=True)def failure_screenshot(page, request): yield # 用例失败时截图 if request.node.rep_call.failed: allure.attach( page.screenshot(), name=“失败截图”, attachment_type=allure.attachment_type.PNG )
七、用例执行与Allure报告生成
7.1 执行命令
终端进入项目根目录，执行以下命令运行用例并生成报告原始数据：
Plain Text# 执行所有用例，生成allure原始数据pytest cases/ -s -v --alluredir=report/allure-results# 只执行单个用例文件pytest cases/test_login.py -s -v --alluredir=report/allure-results# 失败重跑执行pytest cases/ -s -v --reruns=1 --alluredir=report/allure-results
参数说明：
-s：打印控制台日志
-v：详细输出用例执行信息
–alluredir：指定报告原始数据存储路径
7.2 生成并打开可视化报告
Plain Text# 生成html报告并自动打开allure generate report/allure-results -o report/allure-html --cleanallure open report/allure-html
参数说明：
–clean：清空历史报告数据，避免数据叠加混乱
7.3 Allure报告核心功能
展示用例通过率、执行时长、用例总数
分层展示模块、子功能、测试步骤
失败用例自动展示报错日志、截图
支持用例标签、优先级、作者备注
八、Playwright核心特性详解
8.1 自动等待机制
Playwright默认智能等待元素可交互，无需手动写time.sleep，自动等待元素可见、可点击、可输入，大幅降低用例失败率。全局超时在config中统一配置。
8.2 强大的元素定位
支持多种定位方式，优先推荐语义化定位（稳定性最高）：
Plain Text# 1. 文本定位（推荐）page.locator(“text=登录”)# 2. 占位符定位page.locator(“[placeholder=‘请输入用户名’]”)# 3. id/class定位page.locator(“#username”)page.locator(“.login-btn”)# 4. 组合定位page.locator(“div.user input[name=‘pwd’]”)
8.3 常用高级操作
Plain Text# 下拉选择page.select_option(“#select”, value=“1”)# 鼠标悬浮page.hover(“.menu”)# 弹窗处理page.on(“dialog”, lambda dialog: dialog.accept())# 刷新页面page.reload()# 后退/前进page.go_back()page.go_forward()
九、项目最佳实践规范
用例分层：严格区分模块(feature)、子功能(story)、用例标题(title)，保证报告结构清晰
禁止硬编码：地址、账号、超时时间统一放入配置文件
少用强制等待：优先使用Playwright智能等待，仅调试使用sleep
用例独立：每个用例互不影响，支持单独执行、重复执行
失败留存证据：开启失败自动截图，快速定位问题
命名规范：文件、方法统一以test_开头，语义清晰，见名知意
十、常见问题与解决方案
10.1 浏览器启动失败
问题：playwright启动浏览器报错、找不到浏览器
解决：重新执行 playwright install 安装完整浏览器内核
10.2 Allure报告无数据/空白
问题：执行用例后allure-results为空，报告生成失败
解决：1. 必须携带 --alluredir 参数执行用例；2. 关闭Pytest缓存，删除__pycache__文件夹
10.3 元素定位超时
问题：元素找不到、超时报错
解决：1. 检查定位表达式是否准确；2. 适当调高全局超时时间；3. 排查页面是否存在iframe、弹窗遮挡
10.4 用例重跑不生效
解决：确认安装 pytest-rerunfailures，且pytest.ini配置无误，执行命令无参数冲突
十一、快速启动命令汇总
Plain Text# 1. 安装依赖pip install playwright pytest allure-pytest pytest-rerunfailuresplaywright install# 2. 执行用例并生成原始数据pytest cases/ -s -v --reruns=1 --alluredir=report/allure-results# 3. 生成并打开报告allure generate report/allure-results -o report/allure-html --cleanallure open report/allure-html
|（注：部分内容可能由 AI 生成）
