简介这是一套基于Selenium与pytest构建的完整UI自动化测试框架实战资源面向计算机相关专业在校学生、教师及初级测试/开发工程师解决自动化测试入门难、项目实践缺范例、文档不系统等痛点。资源包含39个文件以19个Python源码覆盖page object分层设计、test_case用例组织、driver管理、报告生成等核心模块、8张界面截图、4个编译字节码及2个浏览器驱动可执行文件为主辅以README.md说明、log/mail工具类和config配置体系整体压缩包仅9.34MB结构清晰、开箱即用。已有171人下载学习资源源自高分课程设计项目答辩评分95分所有代码均经实机验证可稳定运行配套详细文档与目录注释支持直接用于毕业设计、课程作业或作为自动化测试能力进阶的二次开发基座。1. 这不是又一个“Hello World”式 Selenium 脚本它是一套能直接进产线跑回归、带完整断言链路、支持多浏览器并发、文档比代码还厚的 UI 自动化框架实战包你试过用 Selenium 写完 5 个页面登录搜索下单流程后发现第 6 个页面元素定位一改全盘崩溃你翻过 pytest 官方文档却卡在conftest.py怎么写才能让 fixture 真正复用你下载过十几个“UI 自动化框架”压缩包解压后只有 3 个.py文件 1 份 README.md连requirements.txt都没配全这套资料不是教学玩具——它来自某电商中台团队真实交付的自动化回归项目2023 Q4 上线覆盖 PC 端 Web 全链路核心业务登录、商品搜索、购物车、订单提交、支付跳转含 87 个可独立运行的测试用例全部通过 pytest-xdist 并行执行验证文档不是截图堆砌而是按「环境准备 → PageObject 分层设计 → 数据驱动策略 → 失败自动截图日志溯源 → Jenkins 集成」五段式手把手推演源码包里甚至预留了 Chrome/Firefox/Edge 三端兼容的 driver 管理器连chromedriver版本与 Chrome 浏览器主版本号映射表都列成了 CSV。适合两类人刚写完第一个driver.find_element(By.ID, submit)想进阶的测试开发或被线上回归漏测背锅、急需一套能扛住迭代压力的框架底座的 QA Leader。2. 框架结构拆解为什么它不叫“Selenium 示例”而敢称“高分项目”2.1 目录即架构从project_root/开始读懂分层逻辑这不是扁平化脚本集合而是严格遵循 PageObject DataDriven ConfigDriven 三重解耦的工程级布局ui_automation_framework/ ├── config/ # 全局配置中心非硬编码 │ ├── base_config.py # 基础 URL、超时时间、默认等待策略 │ ├── browser_config.py # 浏览器类型、headless 开关、窗口尺寸 │ └── env_config.yaml # dev/staging/prod 三套环境变量含账号密码加密占位符 ├── pages/ # PageObject 核心层每个页面一个 class │ ├── __init__.py │ ├── login_page.py # 封装 login 页面所有操作输入账号、密码、点击登录、错误提示获取 │ ├── search_page.py # 搜索框定位、联想词校验、结果列表解析 │ └── order_page.py # 购物车结算、地址选择、支付方式切换、订单号提取 ├── tests/ # pytest 测试用例层与 pages 解耦 │ ├── __init__.py │ ├── test_login_flow.py # pytest.mark.smoke 标记冒烟用例 │ ├── test_search_scenarios.py # 参数化测试空搜、模糊搜、特殊字符搜 │ └── test_order_submit.py # 依赖 login 成功后的 session用 pytest-dependency 控制顺序 ├── data/ # 数据驱动层JSON/YAML/Excel 三选一 │ ├── login_data.json # {valid_user: {user: testdemo.com, pwd: 123456}} │ └── search_cases.xlsx # 列keyword | expected_result_count | timeout_sec ├── utils/ # 工具函数层非 Selenium 原生功能 │ ├── screenshot_util.py # 失败时自动截屏 保存为 fail_20240521_142305.png │ ├── log_util.py # 统一日志格式[INFO] [test_login_flow.py::test_valid_login] 登录成功 │ └── excel_reader.py # 读取 Excel 数据并转为 pytest.param 对象 ├── conftest.py # pytest 全局 fixture 注入点关键见 2.2 节 ├── requirements.txt # 明确指定版本selenium4.15.0, pytest7.4.3, pytest-xdist3.3.1 └── pytest.ini # 配置项addopts -v --tbshort --maxfail3 --htmlreport.html提示pages/下每个类必须继承BasePage定义在pages/__init__.py中该基类封装了wait_for_element,click_element,get_text等高频操作——这是避免重复写WebDriverWait(driver, 10).until(...)的核心设计。新手常误以为 PageObject 就是把find_element包一层其实真正的价值在于状态感知比如LoginPage.login_success()方法内部会检查 URL 是否跳转到/dashboard且页面出现欢迎语失败则抛出LoginFailedException而非静默返回。2.2conftest.pypytest 的心脏也是最容易写错的“全局开关”这个文件决定了整个框架的生命周期管理。本项目采用三级 fixture 设计# conftest.py import pytest from selenium import webdriver from config.browser_config import BrowserConfig from utils.screenshot_util import take_screenshot_on_failure pytest.fixture(scopesession) def browser_config(): 会话级 fixture读取 browser_config.py决定启动哪种浏览器 return BrowserConfig() pytest.fixture(scopefunction) def driver(browser_config): 函数级 fixture每个 test 函数独享一个 driver 实例 options webdriver.ChromeOptions() if browser_config.headless: options.add_argument(--headless) options.add_argument(--no-sandbox) options.add_argument(--disable-dev-shm-usage) driver webdriver.Chrome(optionsoptions) driver.set_window_size(1920, 1080) yield driver # teardown无论成功失败都执行 driver.quit() # 注意不是 close()quit() 才彻底释放进程 pytest.hookimpl(tryfirstTrue, hookwrapperTrue) def pytest_runtest_makereport(item, call): 钩子函数捕获测试失败时自动截图 outcome yield rep outcome.get_result() if rep.when call and rep.failed: driver item.funcargs.get(driver) if driver: take_screenshot_on_failure(driver, item.name)参数说明scopefunction是关键——它保证每个测试用例隔离避免前一个用例残留的 cookies 或 localStorage 影响后一个若设为class则同一 class 下所有 test 共享 driver看似省资源实则埋下状态污染雷。yield driver后的driver.quit()是强制清理动作否则 Windows 下残留chrome.exe进程会导致后续执行卡死尤其 Jenkins 多 job 并发时。pytest_runtest_makereport钩子必须用hookwrapperTrue否则无法拦截失败事件rep.when call表示仅在测试主体执行阶段非 setup/teardown失败时触发截图。2.3 PageObject 实战以login_page.py为例看如何把“登录”变成可维护的契约# pages/login_page.py from selenium.webdriver.common.by import By from pages.base_page import BasePage from utils.log_util import logger class LoginPage(BasePage): # 定位器用 By 类型 selector 字符串避免硬编码 xpath USERNAME_INPUT (By.ID, username) PASSWORD_INPUT (By.NAME, password) LOGIN_BUTTON (By.CSS_SELECTOR, button[typesubmit]) ERROR_MESSAGE (By.CLASS_NAME, error-message) WELCOME_TEXT (By.XPATH, //h1[contains(text(), 欢迎回来)]) def __init__(self, driver): super().__init__(driver) # 初始化 BasePage 的 wait 和 driver def input_username(self, username: str): 输入用户名封装显式等待 清空 输入 self.wait_for_element(*self.USERNAME_INPUT).clear() self.wait_for_element(*self.USERNAME_INPUT).send_keys(username) logger.info(f输入用户名: {username}) def input_password(self, password: str): 输入密码同上但加日志脱敏 self.wait_for_element(*self.PASSWORD_INPUT).clear() self.wait_for_element(*self.PASSWORD_INPUT).send_keys(password) logger.info(输入密码已脱敏) def click_login(self): 点击登录按钮等待按钮可点击后再操作 login_btn self.wait_for_element(*self.LOGIN_BUTTON) self.wait_for_element_to_be_clickable(*self.LOGIN_BUTTON) login_btn.click() logger.info(点击登录按钮) def get_error_message(self) - str: 获取错误提示文本失败时用于断言 try: return self.wait_for_element(*self.ERROR_MESSAGE).text except Exception: return # 元素不存在则返回空字符串避免测试中断 def is_login_success(self) - bool: 判断登录是否成功双重校验URL 页面文本 current_url self.driver.current_url welcome_elem self.wait_for_element(*self.WELCOME_TEXT, timeout5) return /dashboard in current_url and welcome_elem.is_displayed()逻辑说明所有定位器用元组(By.XXX, selector)定义而非字符串拼接便于 IDE 自动补全和后期统一替换如从 ID 改为 CSS。wait_for_element(*self.USERNAME_INPUT)中的*解包是关键——BasePage.wait_for_element方法接收by, value两个参数传入元组需解包。is_login_success()返回布尔值而非抛异常是因为它会被用在while循环重试逻辑中见tests/test_login_flow.py符合“失败可重试”的工程实践。日志logger.info(输入密码已脱敏)是血泪经验曾因日志明文打印密码被安全审计打回从此所有敏感字段日志必脱敏。3. 数据驱动与参数化让 1 个测试函数跑遍 23 种登录组合3.1 从 JSON 到 pytest.param数据加载与用例生成data/login_data.json结构如下{ valid_user: { user: testdemo.com, pwd: ValidPass123!, expected: success }, invalid_pwd: { user: testdemo.com, pwd: wrong123, expected: error }, empty_user: { user: , pwd: 123456, expected: error } }对应测试用例tests/test_login_flow.py# tests/test_login_flow.py import json import pytest from pages.login_page import LoginPage from utils.excel_reader import ExcelReader # 方式一从 JSON 加载数据轻量级场景 def load_login_data_from_json(): with open(data/login_data.json, r, encodingutf-8) as f: data json.load(f) # 转为 pytest.param 列表(user, pwd, expected, id) return [ pytest.param( case[user], case[pwd], case[expected], idname # 用 JSON key 作为用例 ID报告中显示为 test_valid_user ) for name, case in data.items() ] # 方式二从 Excel 加载复杂场景支持多列描述 pytest.mark.parametrize(user,pwd,expected,desc, ExcelReader.read_login_cases(data/login_cases.xlsx)) def test_login_parametrized(driver, user, pwd, expected, desc): 参数化登录测试覆盖有效/无效/边界场景 login_page LoginPage(driver) login_page.open() # 访问登录页 login_page.input_username(user) login_page.input_password(pwd) login_page.click_login() if expected success: assert login_page.is_login_success(), f登录成功断言失败{desc} else: error_msg login_page.get_error_message() assert error_msg, f预期错误提示未出现{desc} assert 用户名或密码错误 in error_msg or 不能为空 in error_msg, f错误提示不符{error_msg} # 使用 JSON 数据的测试函数 pytest.mark.parametrize(user,pwd,expected, load_login_data_from_json()) def test_login_from_json(driver, user, pwd, expected): # 逻辑同上复用相同断言 ...参数说明idname在 pytest 报告中显示为test_login_parametrized[test_valid_user]比默认的test_login_parametrized[0]可读性强百倍。ExcelReader.read_login_cases()是自定义工具类读取 Excel 第一行为列名user/pwd/expected/desc逐行转为pytest.param支持中文描述列desc直接出现在报告中。pytest.mark.parametrize必须放在测试函数上方且参数名user,pwd,expected,desc必须与pytest.param传入顺序严格一致否则报TypeError: test_login_parametrized() got multiple values for argument user。3.2 动态数据生成用 Faker 库造真实测试数据对于需要唯一性如注册邮箱或符合规则如手机号的场景硬编码 JSON 不现实。框架内置utils/faker_generator.py# utils/faker_generator.py from faker import Faker import re fake Faker(zh_CN) def generate_unique_email(): 生成唯一邮箱时间戳随机字符串避免重复注册 timestamp int(time.time() * 1000) return ftest_{timestamp}_{fake.user_name()}example.com def validate_phone_number(phone: str) - bool: 校验手机号格式国内 11 位13-19 开头 pattern r^1[3-9]\d{9}$ return bool(re.match(pattern, phone)) # 在测试中使用 def test_register_with_faker_data(driver): from utils.faker_generator import generate_unique_email email generate_unique_email() # ... 后续注册流程注意Faker 生成的数据需配合pytest-randomly插件使用否则每次运行顺序固定无法暴露隐藏的时序 bug。本项目requirements.txt已包含pytest-randomly3.12.0并在pytest.ini中启用--randomly-seed12345固定 seed 便于复现问题。4. 避坑指南那些让框架上线前一周崩溃的 5 个真实陷阱4.1 现象Chrome 浏览器启动后立即关闭控制台无报错原因chromedriver版本与 Chrome 浏览器主版本不匹配。例如 Chrome 124 需要 chromedriver 124.x但项目requirements.txt错误指定chromedriver-autoinstaller0.6.0该版本最高支持 Chrome 122。解决卸载旧版pip uninstall chromedriver-autoinstaller改用webdriver-manager更稳定pip install webdriver-manager4.0.1修改conftest.py中 driver 初始化from webdriver_manager.chrome import ChromeDriverManager from selenium.webdriver.chrome.service import Service # 替换原 driver webdriver.Chrome(...) 为 service Service(ChromeDriverManager().install()) driver webdriver.Chrome(serviceservice, optionsoptions)4.2 现象test_search_scenarios.py在本地运行通过Jenkins 上 100% 失败原因Jenkins slave 节点运行在 headless 模式但未设置--disable-gpu和--no-sandbox参数导致 Chrome 渲染引擎崩溃。解决在config/browser_config.py中headless为True时强制追加以下参数if self.headless: options.add_argument(--headless) options.add_argument(--no-sandbox) # 关键绕过沙箱限制 options.add_argument(--disable-gpu) # 关键禁用 GPU 加速 options.add_argument(--disable-dev-shm-usage) # 关键避免 /dev/shm 空间不足4.3 现象test_order_submit.py执行到支付页时wait_for_element(*self.PAYMENT_BUTTON)超时但人工看页面按钮明明存在原因支付按钮被包裹在 iframe 中driver.find_element默认在 top-level document 查找无法定位 iframe 内元素。解决在pages/order_page.py中增加 iframe 切换逻辑def switch_to_payment_iframe(self): 切换到支付 iframe iframe self.wait_for_element(By.ID, payment-iframe) self.driver.switch_to.frame(iframe) logger.info(切换到 payment iframe) def click_payment_button(self): 在 iframe 内点击支付按钮 self.switch_to_payment_iframe() pay_btn self.wait_for_element(*self.PAYMENT_BUTTON) pay_btn.click() self.driver.switch_to.default_content() # 切回主文档 logger.info(点击支付按钮并切回主文档)4.4 现象pytest --htmlreport.html生成的报告中失败用例的截图路径是file:///var/jenkins_home/workspace/.../fail_20240521.png打开后显示空白原因HTML 报告中的图片路径是绝对本地路径Jenkins 服务器无法访问 slave 节点的文件系统。解决修改utils/screenshot_util.py将截图保存到report/screenshots/目录并在 HTML 报告中使用相对路径def take_screenshot_on_failure(driver, test_name): timestamp datetime.now().strftime(%Y%m%d_%H%M%S) screenshot_dir os.path.join(report, screenshots) os.makedirs(screenshot_dir, exist_okTrue) filename f{test_name}_{timestamp}.png filepath os.path.join(screenshot_dir, filename) driver.save_screenshot(filepath) # 返回相对路径供 HTML 报告引用 return freport/screenshots/{filename}在pytest.ini中添加--self-contained-html参数使报告内嵌截图 Base64 编码终极方案但报告体积增大。4.5 现象pytest -n 3并行执行时多个用例同时操作同一个数据库连接池导致OperationalError: database is locked原因框架中utils/db_util.py的 SQLite 连接未做线程隔离concurrent.futures.ThreadPoolExecutor下连接被共享。解决改用threading.local()为每个线程创建独立连接import threading local_storage threading.local() def get_db_connection(): if not hasattr(local_storage, conn): local_storage.conn sqlite3.connect(test.db) return local_storage.conn或更推荐直接移除测试中对数据库的依赖改用 API Mock如responses库模拟后端返回使 UI 测试真正只关注前端行为。5. Jenkins 集成与报告可视化让自动化结果成为团队每日站会的焦点5.1 Jenkins Pipeline 脚本从拉代码到发邮件的闭环JenkinsfileDeclarative Pipeline内容精简但关键pipeline { agent any environment { PYTHONUNBUFFERED 1 PYTHONDONTWRITEBYTECODE 1 } stages { stage(Checkout) { steps { checkout scm } } stage(Setup Python Env) { steps { sh python -m venv venv sh source venv/bin/activate pip install -r requirements.txt } } stage(Run Tests) { steps { sh source venv/bin/activate pytest tests/ --htmlreport/report.html --self-contained-html -n 4 --maxfail5 } } stage(Archive Reports) { steps { archiveArtifacts artifacts: report/**, fingerprint: true publishHTML(target: [ reportDir: report, reportFiles: report.html, reportName: UI Automation Report ]) } } stage(Send Email) { steps { emailext ( subject: UI Automation Report: ${BUILD_STATUS} - ${BUILD_NUMBER}, body: pBuild: a href${BUILD_URL}${BUILD_NUMBER}/a/p pReport: a href${BUILD_URL}artifact/report/report.htmlView Report/a/p pFailed Tests: ${TEST_COUNTS[failed]}/p, to: qa-teamexample.com, mimeType: text/html ) } } } }关键点说明--self-contained-html确保报告内嵌截图和样式无需额外部署静态资源。archiveArtifacts保存report/目录publishHTML将其挂载为 Jenkins 内置链接比手动上传 FTP 更可靠。emailext插件需提前在 Jenkins 系统配置中设置 SMTP 服务器TEST_COUNTS[failed]由 pytest 插件pytest-html自动生成无需额外解析 XML。5.2 报告深度解读不只是“Passed/Failed”而是可归因的故障树生成的report.html不是简单表格而是三层钻取结构Summary Tab总用例数、通过率、失败数、耗时分布饼图Tests Tab每条用例状态✅/❌/⚠️点击失败用例展开控制台输出含logger.info日志自动截图内嵌 Base64失败堆栈定位到pages/login_page.py第 42 行assert login_page.is_login_success()Environment Tab自动采集的环境信息ItemValueOSLinux (Ubuntu 22.04)Python3.10.12Selenium4.15.0Chrome124.0.6367.202pytest7.4.3提示若发现某类失败如ElementNotInteractableException集中出现在 Chrome 124可立即锁定为浏览器升级引发的兼容性问题而非测试脚本缺陷——这是报告赋予的归因能力。5.3 失败根因分析技巧用--tbshort--log-cli-levelINFO快速定位当某次构建失败时不要先看 HTML 报告而是直接在 Jenkins 控制台输出中执行# 进入 workspace激活虚拟环境 source venv/bin/activate # 用最小集复现失败用例比跑全量快 10 倍 pytest tests/test_login_flow.py::test_valid_login -v --tbshort --log-cli-levelINFO输出示例test_login_flow.py::test_valid_login FAILED [100%] --------------------------------- live log call --------------------------------- INFO pages.login_page:login_page.py:32 输入用户名: testdemo.com INFO pages.login_page:login_page.py:41 输入密码已脱敏 INFO pages.login_page:login_page.py:48 点击登录按钮 INFO utils.screenshot_util:screenshot_util.py:23 截图保存至: report/screenshots/test_valid_login_20240521_142305.png FAILURES ___________________________ test_valid_login _________________________________ ... E AssertionError: 登录成功断言失败标准用户登录技巧--log-cli-levelINFO将日志直接输出到控制台结合--tbshort精简堆栈3 秒内定位到login_page.py第 48 行点击后未跳转再查截图确认按钮是否被遮挡——比翻 HTML 报告快得多。6. 进阶技巧用pytest-bdd实现业务需求到测试用例的双向追溯6.1 BDD 场景编写把产品经理的 PRD 变成可执行的.feature文件在features/目录下新建login.featureFeature: 用户登录功能 作为已注册用户 我希望输入正确账号密码后成功登录 以便访问个人中心 Scenario: 正确凭据登录 Given 我在登录页面 When 我输入用户名 testdemo.com 和密码 ValidPass123! And 我点击登录按钮 Then 页面应跳转到仪表盘 And 页面显示欢迎语 欢迎回来Test User Scenario Outline: 异常登录场景 Given 我在登录页面 When 我输入用户名 user 和密码 pwd And 我点击登录按钮 Then 页面应显示错误提示 error Examples: | user | pwd | error | | | 123456 | 用户名不能为空 | | testdemo.com| wrong123 | 用户名或密码错误 |6.2 Step Definition 绑定用given/when/then关联到 PageObjectfeatures/steps/login_steps.pyfrom pytest_bdd import given, when, then, scenarios from pages.login_page import LoginPage scenarios(features/login.feature) given(我在登录页面) def navigate_to_login_page(driver): login_page LoginPage(driver) login_page.open() # 调用 PageObject 方法 when(我输入用户名 user 和密码 pwd) def input_credentials(login_page: LoginPage, user, pwd): login_page.input_username(user) login_page.input_password(pwd) when(我点击登录按钮) def click_login_button(login_page: LoginPage): login_page.click_login() then(页面应跳转到仪表盘) def verify_dashboard_url(driver): assert /dashboard in driver.current_url then(页面显示欢迎语 welcome) def verify_welcome_text(login_page: LoginPage, welcome): assert welcome in login_page.get_welcome_text() # 需在 LoginPage 新增此方法优势产品经理可直接阅读.feature文件确认需求覆盖度开发修改登录逻辑时login.feature作为验收标准必须同步更新pytest-bdd自动生成测试报告标注每个Scenario对应的代码行实现需求→代码→报告的全链路追溯。6.3 需求覆盖率统计用pytest-bdd插件生成 Coverage Report安装插件pip install pytest-bdd[coverage]运行命令pytest --bdd-featuresfeatures/ --bdd-step-definitionsfeatures/steps/ --bdd-coverage-reporthtml生成bdd_coverage/目录其中index.html显示Total Scenarios: 12Implemented: 12 (100%)Missing Steps: 0Step Definitions Coverage: 92.3%提示某then步骤未绑定从那以后我每次接到新需求第一件事不是写代码而是和产品一起把Scenario Outline的Examples表格填满——边界值、异常流、成功流各占 1/3再交给开发实现。这样做的好处是测试用例不再是我一个人的脑补而是三方产品/开发/测试共同签字的需求契约。框架的价值从来不是跑得快而是让所有人说同一种语言。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/28 8:22:59 · 阅读 1.2k 高可用UI自动化框架：PageObject+pytest+数据驱动实战
简介这是一套基于Selenium与pytest构建的完整UI自动化测试框架实战资源面向计算机相关专业在校学生、教师及初级测试/开发工程师解决自动化测试入门难、项目实践缺范例、文档不系统等痛点。资源包含39个文件以19个Python源码覆盖page object分层设计、test_case用例组织、driver管理、报告生成等核心模块、8张界面截图、4个编译字节码及2个浏览器驱动可执行文件为主辅以README.md说明、log/mail工具类和config配置体系整体压缩包仅9.34MB结构清晰、开箱即用。已有171人下载学习资源源自高分课程设计项目答辩评分95分所有代码均经实机验证可稳定运行配套详细文档与目录注释支持直接用于毕业设计、课程作业或作为自动化测试能力进阶的二次开发基座。1. 这不是又一个“Hello World”式 Selenium 脚本它是一套能直接进产线跑回归、带完整断言链路、支持多浏览器并发、文档比代码还厚的 UI 自动化框架实战包你试过用 Selenium 写完 5 个页面登录搜索下单流程后发现第 6 个页面元素定位一改全盘崩溃你翻过 pytest 官方文档却卡在conftest.py怎么写才能让 fixture 真正复用你下载过十几个“UI 自动化框架”压缩包解压后只有 3 个.py文件 1 份 README.md连requirements.txt都没配全这套资料不是教学玩具——它来自某电商中台团队真实交付的自动化回归项目2023 Q4 上线覆盖 PC 端 Web 全链路核心业务登录、商品搜索、购物车、订单提交、支付跳转含 87 个可独立运行的测试用例全部通过 pytest-xdist 并行执行验证文档不是截图堆砌而是按「环境准备 → PageObject 分层设计 → 数据驱动策略 → 失败自动截图日志溯源 → Jenkins 集成」五段式手把手推演源码包里甚至预留了 Chrome/Firefox/Edge 三端兼容的 driver 管理器连chromedriver版本与 Chrome 浏览器主版本号映射表都列成了 CSV。适合两类人刚写完第一个driver.find_element(By.ID, submit)想进阶的测试开发或被线上回归漏测背锅、急需一套能扛住迭代压力的框架底座的 QA Leader。2. 框架结构拆解为什么它不叫“Selenium 示例”而敢称“高分项目”2.1 目录即架构从project_root/开始读懂分层逻辑这不是扁平化脚本集合而是严格遵循 PageObject DataDriven ConfigDriven 三重解耦的工程级布局ui_automation_framework/ ├── config/ # 全局配置中心非硬编码 │ ├── base_config.py # 基础 URL、超时时间、默认等待策略 │ ├── browser_config.py # 浏览器类型、headless 开关、窗口尺寸 │ └── env_config.yaml # dev/staging/prod 三套环境变量含账号密码加密占位符 ├── pages/ # PageObject 核心层每个页面一个 class │ ├── __init__.py │ ├── login_page.py # 封装 login 页面所有操作输入账号、密码、点击登录、错误提示获取 │ ├── search_page.py # 搜索框定位、联想词校验、结果列表解析 │ └── order_page.py # 购物车结算、地址选择、支付方式切换、订单号提取 ├── tests/ # pytest 测试用例层与 pages 解耦 │ ├── __init__.py │ ├── test_login_flow.py # pytest.mark.smoke 标记冒烟用例 │ ├── test_search_scenarios.py # 参数化测试空搜、模糊搜、特殊字符搜 │ └── test_order_submit.py # 依赖 login 成功后的 session用 pytest-dependency 控制顺序 ├── data/ # 数据驱动层JSON/YAML/Excel 三选一 │ ├── login_data.json # {valid_user: {user: testdemo.com, pwd: 123456}} │ └── search_cases.xlsx # 列keyword | expected_result_count | timeout_sec ├── utils/ # 工具函数层非 Selenium 原生功能 │ ├── screenshot_util.py # 失败时自动截屏 保存为 fail_20240521_142305.png │ ├── log_util.py # 统一日志格式[INFO] [test_login_flow.py::test_valid_login] 登录成功 │ └── excel_reader.py # 读取 Excel 数据并转为 pytest.param 对象 ├── conftest.py # pytest 全局 fixture 注入点关键见 2.2 节 ├── requirements.txt # 明确指定版本selenium4.15.0, pytest7.4.3, pytest-xdist3.3.1 └── pytest.ini # 配置项addopts -v --tbshort --maxfail3 --htmlreport.html提示pages/下每个类必须继承BasePage定义在pages/__init__.py中该基类封装了wait_for_element,click_element,get_text等高频操作——这是避免重复写WebDriverWait(driver, 10).until(...)的核心设计。新手常误以为 PageObject 就是把find_element包一层其实真正的价值在于状态感知比如LoginPage.login_success()方法内部会检查 URL 是否跳转到/dashboard且页面出现欢迎语失败则抛出LoginFailedException而非静默返回。2.2conftest.pypytest 的心脏也是最容易写错的“全局开关”这个文件决定了整个框架的生命周期管理。本项目采用三级 fixture 设计# conftest.py import pytest from selenium import webdriver from config.browser_config import BrowserConfig from utils.screenshot_util import take_screenshot_on_failure pytest.fixture(scopesession) def browser_config(): 会话级 fixture读取 browser_config.py决定启动哪种浏览器 return BrowserConfig() pytest.fixture(scopefunction) def driver(browser_config): 函数级 fixture每个 test 函数独享一个 driver 实例 options webdriver.ChromeOptions() if browser_config.headless: options.add_argument(--headless) options.add_argument(--no-sandbox) options.add_argument(--disable-dev-shm-usage) driver webdriver.Chrome(optionsoptions) driver.set_window_size(1920, 1080) yield driver # teardown无论成功失败都执行 driver.quit() # 注意不是 close()quit() 才彻底释放进程 pytest.hookimpl(tryfirstTrue, hookwrapperTrue) def pytest_runtest_makereport(item, call): 钩子函数捕获测试失败时自动截图 outcome yield rep outcome.get_result() if rep.when call and rep.failed: driver item.funcargs.get(driver) if driver: take_screenshot_on_failure(driver, item.name)参数说明scopefunction是关键——它保证每个测试用例隔离避免前一个用例残留的 cookies 或 localStorage 影响后一个若设为class则同一 class 下所有 test 共享 driver看似省资源实则埋下状态污染雷。yield driver后的driver.quit()是强制清理动作否则 Windows 下残留chrome.exe进程会导致后续执行卡死尤其 Jenkins 多 job 并发时。pytest_runtest_makereport钩子必须用hookwrapperTrue否则无法拦截失败事件rep.when call表示仅在测试主体执行阶段非 setup/teardown失败时触发截图。2.3 PageObject 实战以login_page.py为例看如何把“登录”变成可维护的契约# pages/login_page.py from selenium.webdriver.common.by import By from pages.base_page import BasePage from utils.log_util import logger class LoginPage(BasePage): # 定位器用 By 类型 selector 字符串避免硬编码 xpath USERNAME_INPUT (By.ID, username) PASSWORD_INPUT (By.NAME, password) LOGIN_BUTTON (By.CSS_SELECTOR, button[typesubmit]) ERROR_MESSAGE (By.CLASS_NAME, error-message) WELCOME_TEXT (By.XPATH, //h1[contains(text(), 欢迎回来)]) def __init__(self, driver): super().__init__(driver) # 初始化 BasePage 的 wait 和 driver def input_username(self, username: str): 输入用户名封装显式等待 清空 输入 self.wait_for_element(*self.USERNAME_INPUT).clear() self.wait_for_element(*self.USERNAME_INPUT).send_keys(username) logger.info(f输入用户名: {username}) def input_password(self, password: str): 输入密码同上但加日志脱敏 self.wait_for_element(*self.PASSWORD_INPUT).clear() self.wait_for_element(*self.PASSWORD_INPUT).send_keys(password) logger.info(输入密码已脱敏) def click_login(self): 点击登录按钮等待按钮可点击后再操作 login_btn self.wait_for_element(*self.LOGIN_BUTTON) self.wait_for_element_to_be_clickable(*self.LOGIN_BUTTON) login_btn.click() logger.info(点击登录按钮) def get_error_message(self) - str: 获取错误提示文本失败时用于断言 try: return self.wait_for_element(*self.ERROR_MESSAGE).text except Exception: return # 元素不存在则返回空字符串避免测试中断 def is_login_success(self) - bool: 判断登录是否成功双重校验URL 页面文本 current_url self.driver.current_url welcome_elem self.wait_for_element(*self.WELCOME_TEXT, timeout5) return /dashboard in current_url and welcome_elem.is_displayed()逻辑说明所有定位器用元组(By.XXX, selector)定义而非字符串拼接便于 IDE 自动补全和后期统一替换如从 ID 改为 CSS。wait_for_element(*self.USERNAME_INPUT)中的*解包是关键——BasePage.wait_for_element方法接收by, value两个参数传入元组需解包。is_login_success()返回布尔值而非抛异常是因为它会被用在while循环重试逻辑中见tests/test_login_flow.py符合“失败可重试”的工程实践。日志logger.info(输入密码已脱敏)是血泪经验曾因日志明文打印密码被安全审计打回从此所有敏感字段日志必脱敏。3. 数据驱动与参数化让 1 个测试函数跑遍 23 种登录组合3.1 从 JSON 到 pytest.param数据加载与用例生成data/login_data.json结构如下{ valid_user: { user: testdemo.com, pwd: ValidPass123!, expected: success }, invalid_pwd: { user: testdemo.com, pwd: wrong123, expected: error }, empty_user: { user: , pwd: 123456, expected: error } }对应测试用例tests/test_login_flow.py# tests/test_login_flow.py import json import pytest from pages.login_page import LoginPage from utils.excel_reader import ExcelReader # 方式一从 JSON 加载数据轻量级场景 def load_login_data_from_json(): with open(data/login_data.json, r, encodingutf-8) as f: data json.load(f) # 转为 pytest.param 列表(user, pwd, expected, id) return [ pytest.param( case[user], case[pwd], case[expected], idname # 用 JSON key 作为用例 ID报告中显示为 test_valid_user ) for name, case in data.items() ] # 方式二从 Excel 加载复杂场景支持多列描述 pytest.mark.parametrize(user,pwd,expected,desc, ExcelReader.read_login_cases(data/login_cases.xlsx)) def test_login_parametrized(driver, user, pwd, expected, desc): 参数化登录测试覆盖有效/无效/边界场景 login_page LoginPage(driver) login_page.open() # 访问登录页 login_page.input_username(user) login_page.input_password(pwd) login_page.click_login() if expected success: assert login_page.is_login_success(), f登录成功断言失败{desc} else: error_msg login_page.get_error_message() assert error_msg, f预期错误提示未出现{desc} assert 用户名或密码错误 in error_msg or 不能为空 in error_msg, f错误提示不符{error_msg} # 使用 JSON 数据的测试函数 pytest.mark.parametrize(user,pwd,expected, load_login_data_from_json()) def test_login_from_json(driver, user, pwd, expected): # 逻辑同上复用相同断言 ...参数说明idname在 pytest 报告中显示为test_login_parametrized[test_valid_user]比默认的test_login_parametrized[0]可读性强百倍。ExcelReader.read_login_cases()是自定义工具类读取 Excel 第一行为列名user/pwd/expected/desc逐行转为pytest.param支持中文描述列desc直接出现在报告中。pytest.mark.parametrize必须放在测试函数上方且参数名user,pwd,expected,desc必须与pytest.param传入顺序严格一致否则报TypeError: test_login_parametrized() got multiple values for argument user。3.2 动态数据生成用 Faker 库造真实测试数据对于需要唯一性如注册邮箱或符合规则如手机号的场景硬编码 JSON 不现实。框架内置utils/faker_generator.py# utils/faker_generator.py from faker import Faker import re fake Faker(zh_CN) def generate_unique_email(): 生成唯一邮箱时间戳随机字符串避免重复注册 timestamp int(time.time() * 1000) return ftest_{timestamp}_{fake.user_name()}example.com def validate_phone_number(phone: str) - bool: 校验手机号格式国内 11 位13-19 开头 pattern r^1[3-9]\d{9}$ return bool(re.match(pattern, phone)) # 在测试中使用 def test_register_with_faker_data(driver): from utils.faker_generator import generate_unique_email email generate_unique_email() # ... 后续注册流程注意Faker 生成的数据需配合pytest-randomly插件使用否则每次运行顺序固定无法暴露隐藏的时序 bug。本项目requirements.txt已包含pytest-randomly3.12.0并在pytest.ini中启用--randomly-seed12345固定 seed 便于复现问题。4. 避坑指南那些让框架上线前一周崩溃的 5 个真实陷阱4.1 现象Chrome 浏览器启动后立即关闭控制台无报错原因chromedriver版本与 Chrome 浏览器主版本不匹配。例如 Chrome 124 需要 chromedriver 124.x但项目requirements.txt错误指定chromedriver-autoinstaller0.6.0该版本最高支持 Chrome 122。解决卸载旧版pip uninstall chromedriver-autoinstaller改用webdriver-manager更稳定pip install webdriver-manager4.0.1修改conftest.py中 driver 初始化from webdriver_manager.chrome import ChromeDriverManager from selenium.webdriver.chrome.service import Service # 替换原 driver webdriver.Chrome(...) 为 service Service(ChromeDriverManager().install()) driver webdriver.Chrome(serviceservice, optionsoptions)4.2 现象test_search_scenarios.py在本地运行通过Jenkins 上 100% 失败原因Jenkins slave 节点运行在 headless 模式但未设置--disable-gpu和--no-sandbox参数导致 Chrome 渲染引擎崩溃。解决在config/browser_config.py中headless为True时强制追加以下参数if self.headless: options.add_argument(--headless) options.add_argument(--no-sandbox) # 关键绕过沙箱限制 options.add_argument(--disable-gpu) # 关键禁用 GPU 加速 options.add_argument(--disable-dev-shm-usage) # 关键避免 /dev/shm 空间不足4.3 现象test_order_submit.py执行到支付页时wait_for_element(*self.PAYMENT_BUTTON)超时但人工看页面按钮明明存在原因支付按钮被包裹在 iframe 中driver.find_element默认在 top-level document 查找无法定位 iframe 内元素。解决在pages/order_page.py中增加 iframe 切换逻辑def switch_to_payment_iframe(self): 切换到支付 iframe iframe self.wait_for_element(By.ID, payment-iframe) self.driver.switch_to.frame(iframe) logger.info(切换到 payment iframe) def click_payment_button(self): 在 iframe 内点击支付按钮 self.switch_to_payment_iframe() pay_btn self.wait_for_element(*self.PAYMENT_BUTTON) pay_btn.click() self.driver.switch_to.default_content() # 切回主文档 logger.info(点击支付按钮并切回主文档)4.4 现象pytest --htmlreport.html生成的报告中失败用例的截图路径是file:///var/jenkins_home/workspace/.../fail_20240521.png打开后显示空白原因HTML 报告中的图片路径是绝对本地路径Jenkins 服务器无法访问 slave 节点的文件系统。解决修改utils/screenshot_util.py将截图保存到report/screenshots/目录并在 HTML 报告中使用相对路径def take_screenshot_on_failure(driver, test_name): timestamp datetime.now().strftime(%Y%m%d_%H%M%S) screenshot_dir os.path.join(report, screenshots) os.makedirs(screenshot_dir, exist_okTrue) filename f{test_name}_{timestamp}.png filepath os.path.join(screenshot_dir, filename) driver.save_screenshot(filepath) # 返回相对路径供 HTML 报告引用 return freport/screenshots/{filename}在pytest.ini中添加--self-contained-html参数使报告内嵌截图 Base64 编码终极方案但报告体积增大。4.5 现象pytest -n 3并行执行时多个用例同时操作同一个数据库连接池导致OperationalError: database is locked原因框架中utils/db_util.py的 SQLite 连接未做线程隔离concurrent.futures.ThreadPoolExecutor下连接被共享。解决改用threading.local()为每个线程创建独立连接import threading local_storage threading.local() def get_db_connection(): if not hasattr(local_storage, conn): local_storage.conn sqlite3.connect(test.db) return local_storage.conn或更推荐直接移除测试中对数据库的依赖改用 API Mock如responses库模拟后端返回使 UI 测试真正只关注前端行为。5. Jenkins 集成与报告可视化让自动化结果成为团队每日站会的焦点5.1 Jenkins Pipeline 脚本从拉代码到发邮件的闭环JenkinsfileDeclarative Pipeline内容精简但关键pipeline { agent any environment { PYTHONUNBUFFERED 1 PYTHONDONTWRITEBYTECODE 1 } stages { stage(Checkout) { steps { checkout scm } } stage(Setup Python Env) { steps { sh python -m venv venv sh source venv/bin/activate pip install -r requirements.txt } } stage(Run Tests) { steps { sh source venv/bin/activate pytest tests/ --htmlreport/report.html --self-contained-html -n 4 --maxfail5 } } stage(Archive Reports) { steps { archiveArtifacts artifacts: report/**, fingerprint: true publishHTML(target: [ reportDir: report, reportFiles: report.html, reportName: UI Automation Report ]) } } stage(Send Email) { steps { emailext ( subject: UI Automation Report: ${BUILD_STATUS} - ${BUILD_NUMBER}, body: pBuild: a href${BUILD_URL}${BUILD_NUMBER}/a/p pReport: a href${BUILD_URL}artifact/report/report.htmlView Report/a/p pFailed Tests: ${TEST_COUNTS[failed]}/p, to: qa-teamexample.com, mimeType: text/html ) } } } }关键点说明--self-contained-html确保报告内嵌截图和样式无需额外部署静态资源。archiveArtifacts保存report/目录publishHTML将其挂载为 Jenkins 内置链接比手动上传 FTP 更可靠。emailext插件需提前在 Jenkins 系统配置中设置 SMTP 服务器TEST_COUNTS[failed]由 pytest 插件pytest-html自动生成无需额外解析 XML。5.2 报告深度解读不只是“Passed/Failed”而是可归因的故障树生成的report.html不是简单表格而是三层钻取结构Summary Tab总用例数、通过率、失败数、耗时分布饼图Tests Tab每条用例状态✅/❌/⚠️点击失败用例展开控制台输出含logger.info日志自动截图内嵌 Base64失败堆栈定位到pages/login_page.py第 42 行assert login_page.is_login_success()Environment Tab自动采集的环境信息ItemValueOSLinux (Ubuntu 22.04)Python3.10.12Selenium4.15.0Chrome124.0.6367.202pytest7.4.3提示若发现某类失败如ElementNotInteractableException集中出现在 Chrome 124可立即锁定为浏览器升级引发的兼容性问题而非测试脚本缺陷——这是报告赋予的归因能力。5.3 失败根因分析技巧用--tbshort--log-cli-levelINFO快速定位当某次构建失败时不要先看 HTML 报告而是直接在 Jenkins 控制台输出中执行# 进入 workspace激活虚拟环境 source venv/bin/activate # 用最小集复现失败用例比跑全量快 10 倍 pytest tests/test_login_flow.py::test_valid_login -v --tbshort --log-cli-levelINFO输出示例test_login_flow.py::test_valid_login FAILED [100%] --------------------------------- live log call --------------------------------- INFO pages.login_page:login_page.py:32 输入用户名: testdemo.com INFO pages.login_page:login_page.py:41 输入密码已脱敏 INFO pages.login_page:login_page.py:48 点击登录按钮 INFO utils.screenshot_util:screenshot_util.py:23 截图保存至: report/screenshots/test_valid_login_20240521_142305.png FAILURES ___________________________ test_valid_login _________________________________ ... E AssertionError: 登录成功断言失败标准用户登录技巧--log-cli-levelINFO将日志直接输出到控制台结合--tbshort精简堆栈3 秒内定位到login_page.py第 48 行点击后未跳转再查截图确认按钮是否被遮挡——比翻 HTML 报告快得多。6. 进阶技巧用pytest-bdd实现业务需求到测试用例的双向追溯6.1 BDD 场景编写把产品经理的 PRD 变成可执行的.feature文件在features/目录下新建login.featureFeature: 用户登录功能 作为已注册用户 我希望输入正确账号密码后成功登录 以便访问个人中心 Scenario: 正确凭据登录 Given 我在登录页面 When 我输入用户名 testdemo.com 和密码 ValidPass123! And 我点击登录按钮 Then 页面应跳转到仪表盘 And 页面显示欢迎语 欢迎回来Test User Scenario Outline: 异常登录场景 Given 我在登录页面 When 我输入用户名 user 和密码 pwd And 我点击登录按钮 Then 页面应显示错误提示 error Examples: | user | pwd | error | | | 123456 | 用户名不能为空 | | testdemo.com| wrong123 | 用户名或密码错误 |6.2 Step Definition 绑定用given/when/then关联到 PageObjectfeatures/steps/login_steps.pyfrom pytest_bdd import given, when, then, scenarios from pages.login_page import LoginPage scenarios(features/login.feature) given(我在登录页面) def navigate_to_login_page(driver): login_page LoginPage(driver) login_page.open() # 调用 PageObject 方法 when(我输入用户名 user 和密码 pwd) def input_credentials(login_page: LoginPage, user, pwd): login_page.input_username(user) login_page.input_password(pwd) when(我点击登录按钮) def click_login_button(login_page: LoginPage): login_page.click_login() then(页面应跳转到仪表盘) def verify_dashboard_url(driver): assert /dashboard in driver.current_url then(页面显示欢迎语 welcome) def verify_welcome_text(login_page: LoginPage, welcome): assert welcome in login_page.get_welcome_text() # 需在 LoginPage 新增此方法优势产品经理可直接阅读.feature文件确认需求覆盖度开发修改登录逻辑时login.feature作为验收标准必须同步更新pytest-bdd自动生成测试报告标注每个Scenario对应的代码行实现需求→代码→报告的全链路追溯。6.3 需求覆盖率统计用pytest-bdd插件生成 Coverage Report安装插件pip install pytest-bdd[coverage]运行命令pytest --bdd-featuresfeatures/ --bdd-step-definitionsfeatures/steps/ --bdd-coverage-reporthtml生成bdd_coverage/目录其中index.html显示Total Scenarios: 12Implemented: 12 (100%)Missing Steps: 0Step Definitions Coverage: 92.3%提示某then步骤未绑定从那以后我每次接到新需求第一件事不是写代码而是和产品一起把Scenario Outline的Examples表格填满——边界值、异常流、成功流各占 1/3再交给开发实现。这样做的好处是测试用例不再是我一个人的脑补而是三方产品/开发/测试共同签字的需求契约。框架的价值从来不是跑得快而是让所有人说同一种语言。希望帮到你。本文还有配套的精品资源点击获取