基于Playwright+Pytest+Allure的数据驱动UI自动化测试框架搭建实战

1. 项目概述与核心价值

最近在团队里推动UI自动化测试，发现很多同学虽然会用一些工具，但离搭建一个稳定、可维护、能真正在团队里跑起来的自动化测试框架，总差那么一口气。要么是脚本写得太“面条”，一个用例改参数要翻半天；要么是报告生成得乱七八糟，出了问题定位像大海捞针；再或者就是配置管理一塌糊涂，换个环境就得重写一遍脚本。这让我想起了几年前自己踩过的那些坑，所以决定把沉淀下来的一套方案拿出来聊聊，核心就是用 Playwright + Pytest + Allure 这三驾马车，再配上 Yaml 做数据驱动，从零开始搭一个能扛事的UI自动化测试框架。

这个组合不是拍脑袋想出来的，是经过多个项目实战检验过的。Playwright 负责搞定浏览器交互，速度快、稳定性好，而且对现代Web技术的支持非常到位；Pytest 作为测试组织者，提供了强大的夹具（fixture）机制和参数化能力，让测试用例写得既清晰又灵活；Allure 则负责把测试结果变成一份人人爱看的可视化报告，问题一目了然。而 Yaml，就是串联起整个框架的“数据总线”，把测试数据、环境配置、元素定位信息从硬编码的脚本里抽离出来，实现真正的数据驱动。接下来，我就手把手带你走一遍完整的搭建过程，从环境准备到第一个脚本运行，再到生成一份漂亮的Allure报告，每个细节都会讲到，并且会重点解释“为什么这么做”，以及我踩过的那些坑。

2. 环境准备与核心工具链解析

工欲善其事，必先利其器。在开始写第一行测试代码之前，我们需要先把整个工具链搭建好。这个环节看似基础，但很多后续的诡异问题，根源都出在这里。

2.1 Python环境与包管理

首先，确保你有一个干净的Python环境。我强烈建议使用venv或conda创建独立的虚拟环境，避免包版本冲突。这里以venv为例：

# 创建虚拟环境，命名为 `playwright-auto-env` python -m venv playwright-auto-env # 激活虚拟环境 # Windows playwright-auto-env\Scripts\activate # macOS/Linux source playwright-auto-env/bin/activate

激活后，你的命令行提示符前应该会出现环境名。接下来安装核心依赖。我们使用pip进行安装，但这里有个关键点：Playwright 的安装分为两部分。一部分是Python语言绑定库playwright，另一部分是它需要调用的实际浏览器引擎。很多人只装了前者，跑起来就报错。

# 安装核心测试框架和Playwright Python包 pip install pytest playwright allure-pytest pytest-html pytest-xdist # 安装Playwright所需的浏览器（Chromium, Firefox, WebKit） playwright install

执行playwright install会下载浏览器二进制文件到本地缓存，这个过程可能需要一些时间，取决于你的网络。这里有个小技巧：如果你只需要测试Chromium，可以运行playwright install chromium来只安装它，加快速度。但为了兼容性测试，我通常建议把三个都装上。

注意：allure-pytest这个包是连接Pytest和Allure报告生成器的桥梁，必不可少。pytest-html可以生成一个基础的HTML报告作为备选，pytest-xdist用于后续的分布式测试，提升执行速度，我们先装上以备后用。

2.2 项目目录结构设计

一个清晰的项目结构是维护性的基石。不要把所有文件都扔在一个文件夹里。我推荐的结构如下：

playwright_auto_project/ ├── configs/ # 配置文件目录 │ ├── test_env.yaml # 测试环境配置（URL， 账号等） │ └── elements.yaml # 页面元素定位信息 ├── test_data/ # 测试数据目录 │ ├── login_data.yaml # 登录相关测试数据 │ └── search_data.yaml # 搜索相关测试数据 ├── pages/ # 页面对象模型（Page Object）目录 │ ├── base_page.py # 基础页面类 │ ├── login_page.py # 登录页面类 │ └── home_page.py # 主页类 ├── tests/ # 测试用例目录 │ ├── conftest.py # Pytest共享夹具配置 │ ├── test_login.py # 登录测试用例 │ └── test_search.py # 搜索测试用例 ├── fixtures/ # 自定义Pytest夹具目录（可选） ├── reports/ # 测试报告输出目录 │ ├── allure-results/ # Allure原始结果数据 │ └── html/ # 最终生成的HTML报告 ├── utils/ # 工具函数目录 │ └── data_loader.py # Yaml数据加载器 └── requirements.txt # 项目依赖列表

这个结构将配置、数据、页面对象、测试用例、工具和报告清晰地分离开。conftest.py是Pytest的魔力所在，里面定义的夹具（fixture）可以被该目录及其子目录下的所有测试文件自动发现和使用。utils/data_loader.py是我们封装Yaml读取逻辑的地方，实现一次编写，到处使用。

2.3 Yaml配置基础与数据驱动理念

为什么选择Yaml而不是JSON或Excel？Yaml的语法对人类更友好，写起来像写配置清单，支持注释，结构清晰。在自动化测试中，我们主要用它存储两类信息：

1. 静态配置：如不同环境的URL、超时时间、全局等待策略。
2. 测试数据：如登录用的用户名密码组合、搜索关键词、商品ID等。

数据驱动的核心思想是将测试数据与测试逻辑分离。你的测试脚本（test_login.py）里不应该出现username = “admin”这样的硬编码。取而代之的是从Yaml文件中读取数据。这样做的好处巨大：

• 可维护性：当测试数据需要变更时，只需修改Yaml文件，无需触动测试脚本。
• 可读性：测试用例看起来更像是在描述业务场景（“用无效密码登录应失败”），而不是一堆赋值语句。
• 易于扩展：要增加一组测试数据，只需在Yaml列表里加一项，Pytest的参数化功能可以自动为你生成多条测试用例。

让我们先创建一个最简单的Yaml配置文件configs/test_env.yaml：

# 测试环境配置 environments: staging: # 预发布环境 base_url: “https://staging.example.com” api_url: “https://api.staging.example.com” timeout: 30000 # 毫秒 production: # 生产环境（慎用！） base_url: “https://www.example.com” api_url: “https://api.example.com” timeout: 45000 # 默认使用的环境 default: staging # 浏览器配置 browser: headless: true # 是否无头模式运行，调试时可设为false slow_mo: 50 # 每个操作延迟50毫秒，方便观察 viewport: { width: 1920, height: 1080 }

再创建一个测试数据文件test_data/login_data.yaml：

# 登录功能测试数据 login_cases: - case_id: “TC_LOGIN_001” description: “使用正确用户名和密码登录成功” username: “standard_user” password: “secret_sauce” expected: “success” # 期望结果标识 tags: [“smoke”, “regression”] - case_id: “TC_LOGIN_002” description: “使用错误密码登录失败” username: “standard_user” password: “wrong_password” expected: “error_message” error_msg: “Username and password do not match” # 预期的错误信息 tags: [“regression”] - case_id: “TC_LOGIN_003” description: “用户名为空登录失败” username: “” password: “secret_sauce” expected: “error_message” error_msg: “Username is required” tags: [“regression”]

可以看到，每个测试用例都是一个字典，包含了用例ID、描述、输入数据和期望结果。tags字段非常有用，后续我们可以用Pytest的-m选项只运行标记为smoke（冒烟测试）的用例。

3. 核心模块搭建：从数据加载到页面对象

有了清晰的结构和Yaml数据，接下来我们就要用代码把它们“粘合”起来，构建框架的核心模块。

3.1 实现通用Yaml数据加载器

我们首先在utils/data_loader.py中创建一个工具类，负责读取和解析Yaml文件。这里我们会用到Python的yaml和os模块。

import yaml import os from pathlib import Path class YamlLoader: “”“通用Yaml配置文件加载器。”“” def __init__(self, base_dir: str = None): “”” 初始化加载器。 :param base_dir: 配置文件的基准目录，默认为项目根目录下的`configs`或`test_data`。 “”” if base_dir: self.base_dir = Path(base_dir) else: # 默认认为此工具类位于项目根目录的utils下，向上两级找到根目录 self.base_dir = Path(__file__).parent.parent def load_config(self, file_name: str, sub_dir: str = “configs”) -> dict: “”” 加载配置文件。 :param file_name: 文件名，如 ‘test_env.yaml‘ :param sub_dir: 子目录名，默认为‘configs‘ :return: 配置字典 “”” file_path = self.base_dir / sub_dir / file_name if not file_path.exists(): raise FileNotFoundError(f“配置文件不存在: {file_path}”) with open(file_path, ‘r‘, encoding=‘utf-8‘) as f: try: data = yaml.safe_load(f) # 使用safe_load避免安全风险 return data if data else {} except yaml.YAMLError as e: raise ValueError(f“解析Yaml文件失败 {file_path}: {e}”) def load_test_data(self, file_name: str) -> list: “”” 加载测试数据文件。约定测试数据文件的主键下是一个列表。 :param file_name: 文件名，如 ‘login_data.yaml‘ :return: 测试数据列表 “”” data = self.load_config(file_name, sub_dir=“test_data”) # 假设Yaml文件的第一个键就是数据列表的键，如 ‘login_cases‘ if data and isinstance(data, dict): first_key = next(iter(data)) return data.get(first_key, []) return [] # 创建一个全局实例方便使用 yaml_loader = YamlLoader()

这个加载器做了几件关键事：

1. 路径解析：能智能地根据当前文件位置找到配置目录。
2. 安全加载：使用yaml.safe_load()而不是load()，防止加载不安全的Yaml内容。
3. 错误处理：文件不存在或格式错误时会抛出明确的异常。
4. 便捷访问：为配置和测试数据提供了专用的加载方法。

实操心得：在团队协作中，经常有人把Yaml文件编码搞错，导致中文乱码。强制指定encoding=‘utf-8‘能避免99%的这类问题。另外，yaml.safe_load是必须的，尤其是在CI/CD环境中，你永远不知道别人提交的Yaml里会不会有奇怪的构造。

3.2 构建健壮的页面对象模型（Page Object）

页面对象模型是UI自动化的最佳实践之一。它的核心思想是将一个页面的元素定位和操作封装成一个类，测试脚本只与这个类的接口交互，不与具体的page.locator(“#username”)这样的底层代码耦合。这极大提升了脚本的可维护性。

我们先在pages/base_page.py中创建一个所有页面类的基类：

from playwright.sync_api import Page, expect class BasePage: “”“所有页面对象的基类，封装通用操作。”“” def __init__(self, page: Page): self.page = page self.timeout = 30000 # 默认超时时间 def navigate(self, url: str): “”“导航到指定URL。”“” self.page.goto(url) # 可以在这里添加一些通用的等待条件，比如等待某个核心元素出现 def get_element(self, selector: str): “”“获取元素定位器，是后续所有操作的基础。”“” return self.page.locator(selector) def click(self, selector: str): “”“点击元素。”“” element = self.get_element(selector) element.click() def fill(self, selector: str, text: str): “”“向输入框填充文本。”“” element = self.get_element(selector) element.fill(text) def get_text(self, selector: str) -> str: “”“获取元素的文本内容。”“” element = self.get_element(selector) return element.text_content() def wait_for_selector(self, selector: str, state: str = “visible”, timeout: int = None): “”“等待元素达到特定状态。”“” timeout = timeout or self.timeout self.page.wait_for_selector(selector, state=state, timeout=timeout) def take_screenshot(self, name: str): “”“截取当前页面截图，用于报告或调试。”“” # 生成带时间戳的文件名，避免覆盖 import datetime timestamp = datetime.datetime.now().strftime(“%Y%m%d_%H%M%S”) screenshot_path = f“./reports/screenshots/{name}_{timestamp}.png” self.page.screenshot(path=screenshot_path, full_page=True) return screenshot_path # 返回路径，可供Allure附件使用

基类提供了最通用的方法。接下来，我们基于一个假设的登录页面，创建具体的页面类pages/login_page.py。关键来了：我们将从Yaml文件加载元素定位信息，而不是硬编码在代码里。

首先，创建configs/elements.yaml：

# 页面元素定位配置 login_page: username_input: “input#user-name” password_input: “input#password” login_button: “input#login-button” error_message: “.error-message-container h3” home_page: title: “.title” menu_button: “#react-burger-menu-btn”

然后，实现LoginPage类：

from pages.base_page import BasePage from utils.data_loader import yaml_loader class LoginPage(BasePage): “”“登录页面对象。”“” def __init__(self, page): super().__init__(page) # 从Yaml加载本页面的元素定位器 self._elements = self._load_elements() def _load_elements(self) -> dict: “”“私有方法，加载元素定位配置。”“” elements_config = yaml_loader.load_config(“elements.yaml”) return elements_config.get(“login_page”, {}) @property def username_input(self): return self._elements.get(“username_input”) @property def password_input(self): return self._elements.get(“password_input”) @property def login_button(self): return self._elements.get(“login_button”) @property def error_message(self): return self._elements.get(“error_message”) # 页面操作封装 def login(self, username: str, password: str): “”“执行登录操作。”“” self.fill(self.username_input, username) self.fill(self.password_input, password) self.click(self.login_button) def get_error_message(self) -> str: “”“获取登录错误信息。”“” return self.get_text(self.error_message)

这样做的好处非常明显：

• 集中管理：所有元素的CSS选择器、XPath等都放在一个Yaml文件里。如果前端修改了ID或类名，你只需要更新这个Yaml文件，所有用到该元素的页面类和测试用例都会自动生效。
• 代码清晰：页面类里只有业务逻辑（login方法），没有杂乱的定位字符串。
• 易于维护：新同事上手，看Yaml文件就能快速了解页面有哪些关键元素。

3.3 设计Pytest夹具（Fixture）体系

夹具是Pytest的灵魂，它提供了强大的setup（准备）和teardown（清理）机制，以及依赖注入功能。我们将把浏览器初始化、页面对象创建、测试数据注入等都在tests/conftest.py中定义为夹具。

import pytest from playwright.sync_api import Page, BrowserContext, Browser from utils.data_loader import yaml_loader from pages.login_page import LoginPage from pages.home_page import HomePage # 加载环境配置 env_config = yaml_loader.load_config(“test_env.yaml”) current_env = env_config.get(“default”, “staging”) env_settings = env_config[“environments”][current_env] @pytest.fixture(scope=“session”) def browser_context_args(browser_context_args): “”“全局浏览器上下文参数，如视窗大小、忽略HTTPS错误等。”“” return { **browser_context_args, “viewport”: env_config.get(“browser”, {}).get(“viewport”, {“width”: 1920, “height”: 1080}), “ignore_https_errors”: True, # 对于测试环境自签名证书很有用 } @pytest.fixture(scope=“function”) # 每个测试函数一个独立的Page def page(browser: Browser, browser_context_args) -> Page: “”“最重要的夹具：提供一个干净的Page对象。”“” context: BrowserContext = browser.new_context(**browser_context_args) # 可以在这里设置全局的等待超时 context.set_default_timeout(env_settings.get(“timeout”, 30000)) page = context.new_page() yield page # 测试结束后，关闭上下文和页面 page.close() context.close() @pytest.fixture def login_page(page: Page) -> LoginPage: “”“提供登录页面对象。”“” return LoginPage(page) @pytest.fixture def home_page(page: Page) -> HomePage: “”“提供主页页面对象。”“” return HomePage(page) @pytest.fixture def base_url() -> str: “”“提供当前环境的基础URL。”“” return env_settings[“base_url”] # 参数化数据夹具：动态加载Yaml中的测试数据 def pytest_generate_tests(metafunc): “”“这是Pytest的一个钩子函数，用于动态参数化。”“” # 如果测试函数需要 ‘login_data‘ 参数 if “login_data” in metafunc.fixturenames: # 从Yaml加载所有登录测试用例 all_login_cases = yaml_loader.load_test_data(“login_data.yaml”) # 将数据传递给测试函数，Pytest会为每条数据生成一个独立的测试用例 metafunc.parametrize(“login_data”, all_login_cases, ids=[case[“case_id”] for case in all_login_cases])

这个conftest.py是框架的“控制中心”：

• page夹具：这是核心。它确保每个测试用例都从一个全新的浏览器上下文和页面开始，完全隔离，避免了用例间的状态污染。yield之前是setup，之后是teardown。
• login_page/home_page夹具：将页面对象作为夹具注入，测试用例可以直接使用。
• base_url夹具：提供环境配置。
• pytest_generate_tests钩子：这是实现数据驱动的关键魔法。它自动发现哪些测试函数需要login_data参数，然后从Yaml文件加载所有测试用例，并用@pytest.mark.parametrize的等效方式动态地为测试函数参数化。ids参数让生成的每条用例在报告里都有一个清晰的名字（如TC_LOGIN_001）。

4. 编写与运行数据驱动的测试用例

现在，万事俱备，只欠东风。我们来编写第一个数据驱动的测试用例。

4.1 编写登录测试用例

在tests/test_login.py中，我们编写测试函数。注意，这个函数会接收来自pytest_generate_tests钩子注入的login_data参数。

import allure import pytest @allure.feature(“登录功能”) @allure.story(“用户登录验证”) class TestLogin: @allure.title(“{login_data[description]}”) # 使用动态数据作为测试用例标题 @allure.severity(allure.severity_level.CRITICAL) # 定义严重级别 def test_user_login(self, login_page, base_url, login_data): “”” 数据驱动的登录测试。 :param login_page: 由夹具注入的LoginPage对象 :param base_url: 由夹具注入的基础URL :param login_data: 由pytest_generate_tests动态注入的单个测试用例数据（字典） “”” # 1. 导航到登录页 login_url = f“{base_url}” login_page.navigate(login_url) # 2. 执行登录操作 username = login_data[“username”] password = login_data[“password”] login_page.login(username, password) # 3. 根据期望结果进行断言 expected_result = login_data[“expected”] if expected_result == “success”: # 期望登录成功，应跳转到主页，验证主页标题等元素 # 这里假设登录成功后页面标题包含 ‘Products‘ with allure.step(“验证登录成功，跳转至主页”): # 注意：这里需要等待页面跳转，可以使用wait_for_url或等待主页元素 # 为了示例，我们简单等待并检查URL变化 login_page.page.wait_for_url(“**/inventory.html”) # 假设跳转后的URL模式 assert “inventory” in login_page.page.url # 更佳实践：创建HomePage对象并验证其上的元素 # home_page = HomePage(login_page.page) # assert home_page.is_title_visible() allure.attach(login_page.page.screenshot(), name=“登录成功页面”, attachment_type=allure.attachment_type.PNG) elif expected_result == “error_message”: # 期望登录失败，出现错误提示 with allure.step(“验证登录失败，显示错误信息”): # 等待错误信息出现 login_page.wait_for_selector(login_page.error_message, state=“visible”, timeout=5000) actual_error_msg = login_page.get_error_message() expected_error_msg = login_data.get(“error_msg”, “”) assert expected_error_msg in actual_error_msg, f“错误信息不匹配。期望包含 ‘{expected_error_msg}‘， 实际为 ‘{actual_error_msg}‘” allure.attach(login_page.page.screenshot(), name=“登录失败页面”, attachment_type=allure.attachment_type.PNG) else: pytest.fail(f“测试用例中定义的期望结果 ‘{expected_result}‘ 无法处理”)

这个测试用例清晰地展示了数据驱动的威力：

1. 用例与数据分离：测试逻辑 (test_user_login) 是固定的，但测试数据 (login_data) 是外部注入的。Yaml文件里定义的3条用例，Pytest会自动运行3次这个函数。
2. 清晰的断言：根据expected字段的值，走不同的验证分支。
3. Allure集成：使用了@allure装饰器来丰富报告内容。@allure.title让报告中的用例标题直接显示Yaml里的描述，一目了然。allure.step将操作步骤在报告中展示出来。allure.attach在断言失败或关键步骤时自动截图并附加到报告中，这对于调试UI问题至关重要。

4.2 运行测试并生成报告

现在，让我们运行测试并生成Allure报告。首先，在项目根目录下运行测试：

# 运行所有测试 pytest tests/ -v # 只运行标记为smoke的测试 pytest tests/ -v -m smoke # 运行特定的测试文件 pytest tests/test_login.py -v # 如果测试失败，显示详细的局部变量信息 pytest tests/ -v --tb=short

运行后，Pytest会输出结果。但我们要的是Allure报告。Allure报告生成分为两步：

第一步：运行测试并收集结果数据在运行Pytest时，需要添加--alluredir参数来指定一个目录，存放Allure所需的原始结果文件（JSON格式）。

pytest tests/ -v --alluredir=./reports/allure-results

第二步：生成HTML报告使用Allure命令行工具，将上一步收集的原始数据转换成漂亮的HTML报告。

# 生成报告到 ./reports/html 目录 allure generate ./reports/allure-results -o ./reports/html --clean # 打开报告（会自动启动默认浏览器） allure open ./reports/html

避坑指南：

1. allure命令找不到？你需要安装Allure命令行工具。它不是Python包，需要单独安装。可以去Allure官网下载，或者通过包管理器安装（如Mac的brew install allure）。
2. 报告是空的？确保运行Pytest时使用了--alluredir参数，并且路径正确。同时检查conftest.py和测试用例中是否正确引入了allure-pytest并使用了相关装饰器。
3. 截图没有附加？确保在测试用例中调用了allure.attach，并且传递的截图数据是字节流。上面例子中page.screenshot()返回的是字节流，可以直接使用。如果先保存为文件，则需要用open(file, ‘rb‘)读取。

生成的Allure报告会包含概览、用例列表、图表分析（如通过率、严重级别分布）、时间线等。点击单个用例，可以看到我们定义的步骤、附件（截图），以及详细的日志，这对于失败分析来说体验远超传统的控制台输出。

5. 高级配置、优化与持续集成

基础框架搭好了，但要用于实际项目，尤其是团队协作和CI/CD流水线，还需要一些优化和高级配置。

5.1 使用Pytest.ini进行全局配置

在项目根目录创建pytest.ini文件，可以统一管理Pytest的各种配置。

[pytest] # 指定测试文件的位置和命名规则 testpaths = tests python_files = test_*.py python_classes = Test* python_functions = test_* # 添加命令行默认选项 addopts = -v --strict-markers --tb=short --alluredir=./reports/allure-results # 自定义标记，防止拼写错误 markers = smoke: 冒烟测试用例 regression: 回归测试用例 slow: 运行缓慢的测试用例

有了这个文件，你只需要运行pytest，它就会自动应用addopts里的所有选项（如详细输出、严格标记、简短回溯、指定Allure结果目录）。

5.2 并发测试与重试机制

UI测试往往比较慢。我们可以利用pytest-xdist插件进行并发测试，以及pytest-rerunfailures插件对失败用例进行重试（对于UI自动化，因网络或渲染导致的偶发失败很常见）。

# 安装重试插件 pip install pytest-rerunfailures # 修改pytest.ini的addopts addopts = -v --strict-markers --tb=short --alluredir=./reports/allure-results -n auto --reruns 2 --reruns-delay 1

• -n auto：让pytest-xdist自动根据CPU核心数启动worker进程，并行运行测试。
• --reruns 2：对失败的测试用例重试2次。
• --reruns-delay 1：每次重试前等待1秒。

注意事项：并发测试时，必须确保测试用例之间是完全独立的，不能有状态依赖。我们的page夹具是function作用域的，每个用例都有独立的浏览器上下文，这很好。但如果用例依赖相同的后端测试数据（如都操作同一个测试账号），就需要在数据准备层面做隔离，或者使用@pytest.mark.flaky标记来处理。

5.3 集成到CI/CD（以GitHub Actions为例）

自动化测试只有集成到CI/CD中，每次代码提交或定时触发，才能真正发挥作用。以下是一个简单的GitHub Actions工作流配置.github/workflows/ui-test.yml：

name: UI Automation Tests on: push: branches: [ main, develop ] pull_request: branches: [ main ] schedule: - cron: ‘0 2 * * *‘ # 每天凌晨2点运行 jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v4 with: python-version: ‘3.9‘ - name: Install system dependencies for Playwright run: | sudo apt-get update sudo apt-get install -y libwoff1 libopus0 libwebpdemux2 libenchant-2-2 libgudev-1.0-0 libsecret-1-0 libhyphen0 libgles2 libxcomposite1 libatk1.0-0 libatk-bridge2.0-0 libepoxy0 libgtk-3-0 libharfbuzz-0b libxkbcommon0 - name: Install Python dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt playwright install --with-deps chromium # CI环境中通常只安装Chromium - name: Install Allure CLI run: | sudo wget https://github.com/allure-framework/allure2/releases/download/2.24.0/allure-2.24.0.tgz sudo tar -zxvf allure-2.24.0.tgz -C /opt/ sudo ln -s /opt/allure-2.24.0/bin/allure /usr/bin/allure - name: Run tests with Allure run: | pytest --alluredir=./reports/allure-results - name: Generate Allure Report run: | allure generate ./reports/allure-results -o ./reports/html --clean - name: Upload Allure Report as Artifact uses: actions/upload-artifact@v3 if: always() # 即使测试失败也上传报告 with: name: allure-report path: ./reports/html/

这个工作流做了以下几件事：

1. 在Ubuntu最新版环境中运行。
2. 安装Playwright所需的系统依赖（这一步很关键，在无GUI的服务器上运行浏览器需要这些库）。
3. 安装Python依赖和Chromium浏览器。
4. 安装Allure命令行工具。
5. 运行测试并生成Allure原始数据。
6. 生成HTML报告。
7. 将生成的HTML报告打包成工件（Artifact），你可以在GitHub Actions的界面上下载查看。

6. 常见问题排查与实战技巧

即使框架搭建得再完美，在实际运行中还是会遇到各种问题。这里记录一些我踩过的坑和解决方案。

6.1 元素定位失败：等待与重试策略

这是UI自动化中最常见的问题。页面还没加载完，脚本就去点击按钮，当然会失败。

解决方案：

1. 使用Playwright内置的自动等待：Playwright的click,fill等操作本身就有等待元素可用的逻辑。但有时这还不够。
2. 显式等待：使用page.wait_for_selector(selector, state=“visible“, timeout=10000)。在我们的BasePage里已经封装了。
3. 更智能的等待：等待某个条件成立，比如URL变化、某个文本出现。

   # 等待页面导航完成 page.wait_for_url(“**/dashboard“) # 等待某个文本出现 page.get_by_text(“操作成功”).wait_for(state=“visible”)

4. 重试机制：对于某些特别不稳定的操作，可以写一个简单的重试装饰器。

   import time from functools import wraps def retry_on_failure(max_attempts=3, delay=1): def decorator(func): @wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_attempts): try: return func(*args, **kwargs) except Exception as e: if attempt == max_attempts - 1: raise print(f”{func.__name__} 第{attempt+1}次尝试失败: {e}， {delay}秒后重试...“) time.sleep(delay) return None return wrapper return decorator # 在页面方法中使用 class SomePage(BasePage): @retry_on_failure(max_attempts=2, delay=2) def click_unstable_button(self): self.click(“button#unstable”)

6.2 测试数据管理：环境隔离与数据准备

测试数据不能混用。开发、测试、预生产环境的数据可能完全不同。

解决方案：

1. 环境隔离的Yaml配置：我们已经有test_env.yaml来管理不同环境的URL。同样，可以为不同环境准备不同的测试数据文件，如test_data/login_data_staging.yaml和test_data/login_data_prod.yaml。通过环境变量来决定加载哪一个。
2. 数据工厂与清理：对于创建数据的测试（如注册新用户），一定要在测试结束后清理数据，避免污染后续测试。可以在夹具的teardown阶段调用清理API或执行数据库删除操作。

   @pytest.fixture def temporary_user(page, base_url): “”“创建一个临时用户，测试后删除。”“” user_data = {“username”: f”test_{random.randint(1000,9999)}“, “email”: …} # 调用API创建用户 user_id = create_user_via_api(user_data) yield user_data # 将用户数据提供给测试用例使用 # 测试结束后，清理用户 delete_user_via_api(user_id)

6.3 Allure报告优化：添加环境信息和分类

默认的Allure报告缺少环境信息。我们可以在运行测试前，生成一个environment.properties文件，Allure会把它展示在报告里。

# 可以在conftest.py的session级夹具中，或pytest的configure钩子中生成 def pytest_configure(config): “”“Pytest配置钩子，在测试开始前执行。”“” import os allure_dir = config.getoption(“--alluredir”) if allure_dir: env_file = os.path.join(allure_dir, “environment.properties”) with open(env_file, ‘w‘) as f: f.write(f”Browser=Chromium\n") f.write(f”Environment={current_env}\n") f.write(f”BaseURL={env_settings[‘base_url‘]}\n") f.write(f”Python={sys.version}\n") f.write(f”Playwright={playwright.__version__}\n") f.write(f”Pytest={pytest.__version__}\n")

此外，可以利用Allure的标签（@allure.tag）和层（@allure.epic,@allure.feature,@allure.story）对测试用例进行更细致的分类，在报告中进行筛选和查看。

搭建这样一个数据驱动的UI自动化测试框架，初期投入确实比录个脚本回放要大。但当你面对成百上千个测试用例，需要频繁维护、需要清晰报告、需要集成到CI/CD时，这个框架带来的秩序、可维护性和效率提升是巨大的。它迫使你思考测试的结构、数据和逻辑的分离，最终写出的是健壮、可靠、易于协作的自动化资产，而不仅仅是一堆脆弱的脚本。