从零到一：手把手教你用Playwright+Pytest+Yaml+Allure搭建一个能跑起来的UI自动化框架（保姆级避坑指南）-平芜编程栈

从零到一：手把手教你用Playwright+Pytest+Yaml+Allure搭建一个能跑起来的UI自动化框架（保姆级避坑指南）

作为一名刚接触自动化测试的新手，第一次搭建UI自动化框架时难免会遇到各种"坑"：环境配置报错、依赖冲突、路径问题、报告生成失败...这些问题往往让人抓狂。本文将带你从零开始，一步步搭建一个完整的UI自动化测试框架，避开那些常见的"坑"，让你在一天内就能跑起第一个测试用例并生成漂亮的Allure报告。

1. 环境准备：避开安装过程中的那些"坑"

在开始编写代码之前，我们需要先配置好开发环境。对于新手来说，这一步往往是最容易出问题的。下面我会详细介绍每个组件的安装方法，并针对不同操作系统给出解决方案。

1.1 Python环境配置

首先确保你已经安装了Python（建议3.7+版本）。可以通过以下命令检查：

python --version

如果提示命令不存在，需要先安装Python。Windows用户可以从官网下载安装包，记得勾选"Add Python to PATH"选项。Mac用户可以使用Homebrew：

brew install python

1.2 安装必要的包

接下来安装项目所需的Python包。建议先创建一个虚拟环境：

python -m venv playwright-env source playwright-env/bin/activate # Linux/Mac playwright-env\Scripts\activate # Windows

然后安装核心依赖：

pip install playwright pytest pyyaml allure-pytest pytest-playwright

常见问题：

网络问题导致安装失败：可以尝试使用国内镜像源，如pip install -i https://pypi.tuna.tsinghua.edu.cn/simple package_name
权限问题：在命令前加上sudo（Mac/Linux）或以管理员身份运行CMD（Windows）

1.3 安装浏览器二进制文件

Playwright需要下载浏览器二进制文件：

python -m playwright install chromium

避坑指南：

如果下载速度慢，可以设置环境变量PLAYWRIGHT_DOWNLOAD_HOST为国内镜像
遇到权限问题，可以尝试sudo python -m playwright install chromium

1.4 Allure命令行工具配置

Allure需要单独安装命令行工具。下载地址：

官方：https://repo.maven.apache.org/maven2/io/qameta/allure/allure-commandline/
国内镜像：https://github.com/allure-framework/allure2/releases

下载后解压，并将bin目录添加到系统PATH环境变量中。验证安装：

allure --version

2. 项目结构设计：合理的分层让维护更轻松

一个良好的项目结构能让你的代码更易于维护和扩展。下面是我们推荐的目录结构：

project-root/ ├── common/ # 公共方法层 │ ├── action.py # 复杂操作封装 │ ├── attach.py # 结果处理 │ └── read_file.py # 文件读取 ├── testcase/ # 测试用例层 │ ├── conftest.py # pytest fixtures │ └── test_*.py # 测试用例文件 ├── data/ # 测试数据层 │ └── *.yaml # YAML数据文件 ├── reports/ # 测试报告（自动生成） ├── log/ # 日志和截图（自动生成） ├── pytest.ini # pytest配置 └── run.py # 运行入口

这种分层设计的优势在于：

可维护性：当需要修改某个功能时，可以快速定位到对应文件
可扩展性：新增功能或模块时不会影响现有代码
可读性：代码结构清晰，便于团队协作

3. 编写第一个测试用例：从百度搜索开始

让我们从最简单的百度搜索测试开始，逐步构建完整的测试流程。

3.1 准备测试数据

在data/base.yaml中定义测试数据：

test_pytest: goto: https://www.baidu.com/ fills: pytest path: ./log/screenshot/ fileName: test_pytest

3.2 创建公共方法

在common/action.py中封装常用操作：

def click_fill(page, locator, text): """点击输入框并输入文本""" page.locator(locator).click() page.locator(locator).fill(text)

在common/attach.py中处理测试结果：

import allure from playwright.sync_api import Page def readAttach(page: Page, paths, fileName): """截图并附加到Allure报告""" page.screenshot(path=f"{paths}{fileName}.png") with open(f"{paths}{fileName}.png", "rb") as file: allure.attach(file.read(), name=fileName, attachment_type=allure.attachment_type.PNG)

3.3 编写测试用例

在testcase/test_baidu.py中创建测试：

import allure import pytest from common.action import click_fill from common.attach import readAttach from common.read_file import read_yaml from playwright.sync_api import Page @allure.epic("百度搜索测试") @allure.title("搜索pytest") def test_pytest(page: Page): # 读取测试数据 test_data = read_yaml("/data/base.yaml")["test_pytest"] # 执行测试步骤 page.goto(test_data["goto"]) click_fill(page, "#kw", test_data["fills"]) page.get_by_role("button", name="百度一下").click() # 处理测试结果 readAttach(page, test_data["path"], test_data["fileName"])

3.4 配置pytest

在pytest.ini中配置运行参数：

[pytest] addopts = -vs --alluredir=./reports/tmp --clean-alluredir testpaths = ./testcase python_files = test_*.py python_classes = Test* python_functions = test_*

4. 运行测试并生成报告：让结果一目了然

4.1 运行测试

创建run.py作为运行入口：

import os import pytest if __name__ == "__main__": pytest.main() os.system("allure generate ./reports/tmp -o ./reports/html --clean") os.system("allure open ./reports/html")

运行测试：

python run.py

4.2 解读Allure报告

Allure报告会展示：

测试用例的执行情况
每个步骤的详细日志
自动截图的页面状态
测试通过率统计

常见问题解决：

报告无法生成：检查allure命令行工具是否安装正确
截图不显示：确认截图路径正确且有写入权限
报告样式异常：尝试清理缓存或重新生成报告

5. 进阶技巧：让框架更健壮

5.1 处理异步操作

Playwright支持异步操作，可以提升测试效率：

async def test_async(page): await page.goto("https://example.com") title = await page.title() assert "Example" in title

5.2 跨浏览器测试

可以在pytest参数中指定不同浏览器：

@pytest.mark.parametrize("browser_type", ["chromium", "firefox", "webkit"]) def test_multiple_browsers(browser_type, page): # 测试代码

5.3 使用Fixture管理资源

在conftest.py中定义全局fixture：

import pytest from playwright.sync_api import Playwright @pytest.fixture(scope="session") def browser(playwright: Playwright): browser = playwright.chromium.launch(headless=False) yield browser browser.close()

5.4 优化YAML数据管理

使用动态数据加载：

def load_test_data(file_path): with open(file_path, "r") as f: return yaml.safe_load(f)

6. 常见问题与解决方案

在实际项目中，你可能会遇到以下问题：

问题现象	可能原因	解决方案
`playwright install`失败	网络问题	使用国内镜像或手动下载
无法生成Allure报告	PATH未配置	检查allure是否在PATH中
截图失败	路径不存在	确保目录存在且有写入权限
元素找不到	页面加载慢	增加等待时间或使用`page.wait_for_selector`
跨平台问题	路径分隔符不同	使用`os.path.join`处理路径

7. 项目优化方向

当框架能够正常运行后，可以考虑以下优化：

日志系统：添加详细的运行日志，便于调试
异常处理：增强框架的容错能力
并发执行：使用pytest-xdist加速测试
CI/CD集成：与Jenkins或GitHub Actions集成
页面对象模型：引入PO模式提高可维护性

# 示例：简单的日志配置 import logging logging.basicConfig( level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s", handlers=[ logging.FileHandler("log/debug.log"), logging.StreamHandler() ] )

8. 真实项目中的经验分享

在实际使用中，我发现以下几个技巧特别有用：

使用page.pause()：在测试运行时插入暂停，方便调试
录制功能：Playwright的codegen可以录制操作生成代码
Trace Viewer：记录测试执行的详细轨迹
自定义报告：扩展Allure报告，添加更多有用信息
Mock接口：使用page.route拦截和修改网络请求

# 使用codegen录制测试 playwright codegen https://www.baidu.com

经过多次项目实践，这套框架已经能够满足大部分UI自动化测试需求。关键在于开始时要保持简单，然后根据实际需求逐步扩展功能。记住，一个能跑起来的简单框架，比一个设计复杂但无法运行的框架要有价值得多。

从零到一：手把手教你用Playwright+Pytest+Yaml+Allure搭建一个能跑起来的UI自动化框架（保姆级避坑指南）