从 0 到 1 搭建企业级 UI 自动化测试框架 | Selenium+Pytest+Allure 完整落地指南

目录

一、先看全貌：项目整体架构与目录结构

目录结构与职责详解

核心设计思想：三层解耦架构

二、基石搭建：通用元素操作封装（operateElement.py）

核心代码完整解析

封装的 3 个核心价值

三、核心分层：Page+Business 解耦设计

1. Page 层：页面元素统一管理

2. Business 层：业务逻辑封装

四、用例落地：数据驱动的测试用例编写（test_login.py）

配套的测试数据文件（data/login.yml）

用例编写的核心亮点

五、报告进阶：企业级 Allure 报告定制（testRunner.py）

核心代码完整解析

报告定制的核心亮点（新手必学的进阶技巧）

六、环境搭建：跟着做就能跑

1. 基础环境准备

第一步 我们首先要安装 Python（3.8 及以上版本 Python官网）接下来是安装步骤：

​Python官网​编辑

2. 安装 Python 依赖包

3. 项目文件搭建

4. 一键执行

七、运行效果：高颜值 Allure 报告展示

1. 报告总览页

2. 用例详情页

3. 功能模块统计

八、框架核心优势与进阶拓展方向

这套框架的核心优势

进阶拓展方向（学完基础可以继续升级）

结尾总结

你是不是还在写零散重复的 Selenium 脚本？页面元素一改，要翻遍所有用例改定位？用例执行失败，连个现场截图都没有？测试报告丑到没法同步给团队？

这篇文章，带你完整拆解一套可直接落地的企业级 UI 自动化框架，基于 Selenium+Pytest+Allure 技术栈，从分层设计、代码封装、用例编写到高颜值报告生成，全流程保姆级拆解，新手也能跟着写、跟着跑、直接用在工作中！

一、先看全貌：项目整体架构与目录结构

一套好的自动化框架，核心是解耦、易维护、高复用，我们这套框架完全遵循经典的 PO（Page Object）设计模式，把页面元素、业务逻辑、测试用例完全拆分，先看整体的目录结构：

目录结构与职责详解

每一个文件夹都有明确的职责，彻底告别 “一个脚本写到底” 的混乱模式：

表格

核心设计思想：三层解耦架构

测试用例层（test_case）→ 业务逻辑层（business）→ 页面元素层（page）
↓ ↓
↘ 通用操作封装层（operateElement） ↙

这套架构的核心优势就是：页面元素变了，只改 page 层；业务流程变了，只改 business 层；新增测试场景，只在 data 加数据或 test_case 加用例，各司其职，维护成本降到最低。

二、基石搭建：通用元素操作封装（operateElement.py）

新手写 Selenium 脚本最常见的问题：到处写time.sleep()硬等待、元素定位频繁超时、异常了没有现场、代码重复率极高。我们先把所有基础操作做统一封装，这是整个框架的基石，一次封装，全框架复用。

核心代码完整解析

import time
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as ec
from selenium.webdriver.support.ui import WebDriverWait
import allure

class OperateElement:
def __init__(self, driver):
# 初始化传入浏览器驱动，所有操作共用一个driver实例
self.driver = driver

def click(self, locator):
"""封装点击操作：显式等待+异常捕获+自动截图+Allure步骤"""
with allure.step('点击元素'):
try:
# 显式等待10秒，直到元素可点击，再执行点击，告别硬等待
WebDriverWait(self.driver, 10).until(ec.element_to_be_clickable((By.XPATH, locator))).click()
except:
# 异常时自动截图，写入Allure报告，方便定位问题
allure.attach(self.driver.get_screenshot_as_png(),name='点击元素失败',attachment_type=allure.attachment_type.PNG)
# 重试一次，提升用例稳定性
WebDriverWait(self.driver, 10).until(ec.element_to_be_clickable((By.XPATH, locator))).click()

def send_keys(self, locator, text):
"""封装输入操作：显式等待+异常捕获+自动截图+Allure步骤"""
with allure.step('输入内容'):
try:
WebDriverWait(self.driver, 10).until(ec.element_to_be_clickable((By.XPATH, locator))).send_keys(text)
except:
allure.attach(self.driver.get_screenshot_as_png(),name='输入内容失败',attachment_type=allure.attachment_type.PNG)
assert False

def get_text(self, locator):
"""封装获取文本操作：显式等待+异常捕获+自动截图"""
with allure.step('获取文本'):
try:
return WebDriverWait(self.driver, 10).until(ec.presence_of_element_located((By.XPATH, locator))).text
except:
allure.attach(self.driver.get_screenshot_as_png(),name='获取文本失败',attachment_type=allure.attachment_type.PNG)
return WebDriverWait(self.driver, 10).until(ec.presence_of_element_located((By.XPATH, locator))).text

def clear(self, locator):
"""封装清空输入框操作"""
with allure.step('清除文本'):
try:
WebDriverWait(self.driver, 10).until(ec.presence_of_element_located((By.XPATH, locator))).clear()
except:
allure.attach(self.driver.get_screenshot_as_png(),name='清除文本失败',attachment_type=allure.attachment_type.PNG)
WebDriverWait(self.driver, 10).until(ec.presence_of_element_located((By.XPATH, locator))).clear()

def assert_text(self, xpath, text):
"""封装文本断言操作：自带步骤+截图+清晰的断言报错信息"""
time.sleep(1)
with allure.step(f'验证元素包含文本[{text}]'):
try:
element_text = self.get_text(xpath)
assert text in element_text, f"文本断言失败！预期包含：'{text}'，实际文本：'{element_text}'"
except Exception as e:
allure.attach(self.driver.get_screenshot_as_png(),name='断言文本失败',attachment_type=allure.attachment_type.PNG)
raise

封装的 3 个核心价值

三、核心分层：Page+Business 解耦设计

PO 模式的核心，就是把 “页面有什么” 和 “用页面做什么” 分开，我们通过 Page 层和 Business 层，彻底实现元素、操作、业务的解耦。

1. Page 层：页面元素统一管理

Page 层只做一件事：管理对应页面的所有元素定位表达式，不写任何业务逻辑、不做任何操作。根据项目代码，我们补全登录页的 Page 层示例，你可以直接参考：

# page/login_page.py
class LoginPage:
# 登录页的所有元素定位，统一管理
login = '//div[text()="账号密码登录"]' # 账号密码登录tab
username = (By.XPATH, '//input[@placeholder="请输入手机号"]') # 手机号输入框
password = (By.XPATH, '//input[@placeholder="请输入密码"]') # 密码输入框
button = (By.XPATH, '//button[text()="登录"]') # 登录按钮
asr01 = (By.XPATH, '//div[contains(@class,"user-info")]') # 登录成功后的用户信息元素
asr03 = (By.XPATH, '//div[@class="form-item-error"]') # 表单校验错误提示元素

✅ 最佳实践：

• 每个页面对应一个 Page 类，元素命名见名知意，不用写注释也能看懂
• 元素定位统一用元组格式（By.XX, 定位表达式），后续调用直接解包，简洁高效
• 哪怕元素定位改了，只需要改这一行代码，所有用到这个元素的地方全部自动生效

2. Business 层：业务逻辑封装

Business 层是连接 Page 层和用例层的桥梁，它把多个页面操作，封装成一个完整的业务动作，比如 “登录” 这个动作，需要点击 tab、输入账号、输入密码、点击登录，我们把它封装成一个方法，用例层直接一行调用即可。

核心代码解析：

# business/loginBusiness.py
from page.login_page import LoginPage
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait

class LoginBusiness:
@classmethod
def loginBusiness(self, driver, name, password):
"""封装完整的登录业务流程：切换登录方式→输入账号→输入密码→点击登录"""
# 等待账号密码登录tab可见，点击切换
WebDriverWait(driver,10).until(EC.visibility_of_element_located((By.XPATH,LoginPage.login))).click()
# 输入账号密码
driver.find_element(*LoginPage.username).send_keys(name)
driver.find_element(*LoginPage.password).send_keys(password)
# 点击登录按钮
driver.find_element(*LoginPage.button).click()

✅ 设计价值：

• 业务流程和测试用例彻底解耦：比如后续登录流程加了验证码、加了勾选协议，只需要修改这个 loginBusiness 方法，所有调用它的测试用例完全不用改。
• 用例层代码极简：用例不用关心登录要点击什么、输入什么，只需要传账号密码，调用这一个方法就完成登录，用例可读性拉满。
• 业务复用：后续其他模块的用例需要前置登录，直接调用这个方法即可，不用重复写登录步骤。

四、用例落地：数据驱动的测试用例编写（test_login.py）

有了前面的分层封装，测试用例的编写就变得极其简单，我们只需要关注测试场景、测试数据、断言验证，其他的都交给封装好的方法。

我们以登录模块的测试用例为例，逐行解析企业级用例的编写规范：

# test_case/test_login.py
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait
from page.login_page import LoginPage
from business.loginBusiness import LoginBusiness
import pytest, time, yaml, allure,page
from selenium.webdriver.chrome.options import Options

# Allure报告的模块标签，报告里会按模块分类
@allure.feature('登录模块')
class TestLogin:
def setup_method(self):
"""用例前置固件：每个用例执行前，都会执行这里的代码"""
# 配置Chrome无头模式，服务器执行也能正常跑，不用打开浏览器窗口
chrome_options = Options()
chrome_options.add_argument('–headless')
# 初始化浏览器驱动
self.driver = webdriver.Chrome(options=chrome_options)
# 打开被测地址
self.driver.get('输入测试网址')
time.sleep(3)

# 数据驱动：用yaml文件管理测试数据，一条数据对应一条用例，批量执行
@pytest.mark.parametrize("type,phone,pwd,esc", yaml.safe_load(open('./data/login.yml', encoding='utf-8'))['login'])
def test_login(self, type, phone, pwd, esc):
"""登录模块全场景测试用例：正向登录、账号错误、密码错误、格式校验等"""
with allure.step('登录测试'):
ti=time.strftime('%Y%m%d%H%M%S')
try:
# 直接调用封装好的登录业务方法，一行完成登录操作
LoginBusiness.loginBusiness(self.driver, phone, pwd)
time.sleep(1)
# 根据用例类型，获取不同的实际结果
if type == 1:
# 正向用例：登录成功，获取首页用户信息
time.sleep(3)
asr = self.driver.find_element(*LoginPage.asr01).text
elif type == 2:
# 反向用例：获取页面顶部的toast提示
asr = WebDriverWait(self.driver, 10).until(
EC.presence_of_element_located((By.XPATH, '//div[@class="ant-message-notice-content"]'))).text
elif type == 3:
# 反向用例：获取表单校验的错误提示
asr = self.driver.find_element(*LoginPage.asr03).text
else:
# 其他异常场景，统一获取toast提示
asr = WebDriverWait(self.driver, 10).until(
EC.presence_of_element_located((By.XPATH, '//div[@class="ant-message-notice-content"]'))).text
except:
# 操作异常时，自动截图写入报告，标记用例失败
allure.attach(self.driver.get_screenshot_as_png(), name='操作或定位异常',attachment_type=allure.attachment_type.PNG)
assert False

with allure.step('断言验证'):
try:
# 断言：预期结果包含在实际结果中
assert esc in asr
except:
# 断言失败，自动截图保存本地+写入报告，标记失败
self.driver.save_screenshot(f'{page.url}/断言失败{ti}.png')
allure.attach(self.driver.get_screenshot_as_png(), name='断言失败',attachment_type=allure.attachment_type.PNG)
assert False

with allure.step('执行完成截图'):
# 无论成功失败，都把最终页面截图写入报告，方便追溯
allure.attach(self.driver.get_screenshot_as_png(), name='执行结果截图',attachment_type=allure.attachment_type.PNG)

def teardown_method(self):
"""用例后置固件：每个用例执行完，都会执行这里的代码"""
# 关闭浏览器，释放资源
self.driver.quit()

配套的测试数据文件（data/login.yml）

数据驱动的核心，就是把测试数据和代码分开，新增测试场景，只需要在 yaml 里加一行数据，不用改任何代码，示例如下：

# data/login.yml
login:
# 正向用例：正确的账号密码，预期登录成功
– type: 1
phone: "138xxxx8888"
pwd: "正确密码123"
esc: "欢迎您"
# 反向用例：密码错误，预期提示账号或密码错误
– type: 2
phone: "138xxxx8888"
pwd: "错误密码"
esc: "用户名或密码错误"
# 反向用例：手机号格式错误，预期表单提示
– type: 3
phone: "123"
pwd: "123456"
esc: "请输入正确的手机号"
# 反向用例：账号不存在，预期提示
– type: 2
phone: "13900000000"
pwd: "123456"
esc: "账号不存在"

用例编写的核心亮点

五、报告进阶：企业级 Allure 报告定制（testRunner.py）

很多人写自动化，报告就只是简单的allure generate生成一个默认报告，既没有环境信息，也没有历史趋势，标题还是默认的，根本没法给领导、给团队看。我们这套执行脚本，直接把 Allure 报告拉到企业级标准，一键执行，直接生成高颜值、信息全、可追溯的测试报告。

核心代码完整解析

# testRunner.py 框架执行入口，直接运行这个文件，就能一键执行用例+生成报告
import json
import time
import pytest
import os
import datetime
import shutil
from pathlib import Path
import platform

def generate_timestamp():
"""生成时间戳，用于区分每次执行的原始数据"""
return datetime.datetime.now().strftime("%Y%m%d_%H%M%S")

def create_environment_file(raw_dir):
"""创建环境信息文件，在Allure报告里展示测试环境信息"""
env_file = raw_dir / "environment.properties"
# 动态生成环境信息，可根据自己的项目修改
env_content = f"""projectName=SwarmBIM协同系统
pythonVersion=3.8.5
allureVersion=2.11.0
baseUrl=https://single.swarm-bim.com/login?appId=85319726
executionTime={time.strftime("%Y-%m-%d %H:%M:%S")}
author=测试开发团队
osName={platform.system()}
osVersion={platform.release()}
browserName=Chrome
browserVersion=87.0.4280.88
browserSize=1920×1080
"""
# 用UTF-8编码，解决中文乱码问题
with env_file.open('w', encoding='utf-8-sig') as f:
f.write(env_content)

def run_tests():
timestamp = generate_timestamp()
# 目录定义：历史数据目录、本次原始结果目录、最终HTML报告目录
history_dir = Path("reports/allure-history/history") # 独立存储历史趋势数据
raw_dir = Path(f"reports/raw_{timestamp}") # 本次执行的原始数据，带时间戳防止覆盖
html_dir = Path("reports/html") # 最终HTML报告，固定路径，方便查看

# 自动创建目录，不存在就新建
raw_dir.mkdir(parents=True, exist_ok=True)
history_dir.mkdir(parents=True, exist_ok=True)

# 把上一次的历史数据，复制到本次执行目录，实现报告保留历史趋势
if history_dir.exists():
shutil.copytree(
history_dir,
raw_dir / "history",
dirs_exist_ok=True
)

# 执行pytest测试用例，生成Allure原始数据
pytest_args = [
'test_case', # 要执行的用例目录
f'–alluredir={raw_dir}', # 指定原始数据输出目录
'–clean-alluredir' # 清空本次目录的旧数据
]
exit_code = pytest.main(pytest_args)

# 写入环境信息文件
create_environment_file(raw_dir)

# 生成HTML报告，–clean清空旧报告
os.system(f'allure generate {raw_dir} -o {html_dir} –clean')

# 把本次生成的最新历史数据，保存到独立目录，供下次执行使用
if (html_dir / 'history').exists():
shutil.copytree(
html_dir / 'history',
history_dir,
dirs_exist_ok=True
)

# 自定义报告浏览器标题，告别默认的Allure Report
with open(f"{html_dir}/index.html", "r+", encoding="utf-8") as f:
content = f.read().replace(
'<title>Allure Report</title>',
'<title>SIM协同系统自动化测试报告</title>'
)
f.seek(0)
f.write(content)
f.truncate()

# 自定义报告里的大标题，更符合企业项目需求
summary_path = html_dir / "widgets/summary.json"
data = json.loads(summary_path.read_text())
data['reportName'] = 'SIM协同系统 自动化测试报告'
summary_path.write_text(json.dumps(data))

# 自动打开生成好的测试报告
os.system(f"allure open {html_dir}")
return html_dir / "index.html"

if __name__ == "__main__":
report_path = run_tests()
print(f"报告生成路径：{report_path}")

报告定制的核心亮点（新手必学的进阶技巧）

六、环境搭建：跟着做就能跑

看完了框架设计和代码，你肯定想自己跑起来试试，这里给你完整的环境搭建步骤，一步都不落下：

1. 基础环境准备

第一步 我们首先要安装 Python（3.8 及以上版本 Python官网）接下来是安装步骤：

​

第二步 我们接下来在安装谷歌浏览器（谷歌浏览器官网）

第三步 我们接下来安装 ChromeDriver（与 Chrome 浏览器版本匹配  ChromeDriver下载网站 访问华为云镜像）

第四步 接下来我们安装 Allure 命令行工具（需先安装 Java 8+ 环境 ）

步骤1 安装 Java 8 及以上版本【JDK官网】

步骤 4.2 安装 Allure 命令行工具

1.步骤 1：访问官方下载页面

操作：打开Allure框架在GitHub的官方发布页面
https://github.com/allure-framework/allure2/releases。

说明：此页面列出了所有历史版本和最新版本。您提供的链接内容显示，最新的版本为 2.37.0 （发布日期为2026年2月20日），向下滚动可找到更多旧版本，如 2.36.0 、 2.35.1 等。

步骤 2：下载对应系统的压缩包

操作：在发布页面中找到您需要的版本（通常选择最新的稳定版本，例如  2.37.0 ），然后向下滚动到“Assets”折叠区域并展开。

选择文件：根据您的操作系统，下载对应的压缩包：

Windows 系统：选择  allure-2.27.0.zip （版本号以实际最新版为准）。

说明：如果GitHub页面加载缓慢或无法访问，可以参考之前提到的国内镜像加速方案。

步骤 3：解压与配置系统环境变量

此步骤的目的是让系统在任何路径下都能识别 allure 命令。

3.1 解压：将下载的压缩包解压到一个无中文、无空格的目录。例如：

`D:\\tools\\allure-2.27.0` （Windows）

3.2 配置环境变量（Windows示例）：

右键点击“此电脑”或“计算机”，选择“属性”。

点击“高级系统设置” -> “环境变量”。

在“系统变量”区域，找到并选中变量名为  Path  的变量，点击“编辑”。

在弹出的窗口中，点击“新建”，然后将Allure的 bin 目录的完整路径添加进去。例如： D:\\tools\\allure-2.27.0\\bin 。

依次点击所有弹出窗口的“确定”以保存设置。

2. 安装 Python 依赖包

直接在 cmd 里执行以下命令，一键安装所有需要的库：

pip install selenium pytest allure-pytest pyyaml

3. 项目文件搭建

按照我们上面的目录结构，创建对应的文件夹和 py 文件，把上面的代码复制进去，补充好自己的元素定位、测试地址、测试数据。

4. 一键执行

直接运行testRunner.py文件，就能自动执行用例，执行完成后会自动打开测试报告，你就能看到高颜值的自动化测试报告了！

七、运行效果：高颜值 Allure 报告展示

这是这套框架最终生成的报告效果，也是最能打动团队、打动领导的部分，每一个用例的执行过程、截图、断言信息，都清晰可见。

1. 报告总览页

这里能看到本次执行的用例总数、通过率、失败 / 跳过数量、执行时长，还有我们自定义的报告名称、环境信息，以及历史执行趋势图。

2. 用例详情页

点击对应的测试模块、测试用例，能看到用例的完整执行步骤，每一步的操作、截图、断言结果都清晰展示，失败的用例能直接看到异常截图和报错信息，定位问题效率拉满。

3. 功能模块统计

能看到每个模块的用例执行情况，哪些模块通过率高，哪些模块有问题，一目了然，非常适合做测试汇报。

八、框架核心优势与进阶拓展方向

这套框架的核心优势

进阶拓展方向（学完基础可以继续升级）

结尾总结

UI 自动化测试的核心，从来不是 “能点击、能输入” 的脚本，而是可维护、可扩展、稳定、高效的框架。这套基于 Selenium+Pytest+Allure 的 PO 分层框架，解决了自动化测试 90% 的痛点，从元素封装、分层解耦，到数据驱动、报告定制，全流程都是企业级的最佳实践。

哪怕你是自动化新手，跟着这篇文章，也能一步步搭建起自己的自动化框架，把重复的手工回归工作交给机器，把自己的时间放到更有价值的测试设计、场景覆盖上。

如果这篇文章对你有帮助，欢迎点赞收藏，有任何问题，都可以在评论区留言，我会一一解答～