Selenium+Pytest+POM：构建稳定可维护的Web UI自动化测试框架实战

1. 项目概述：当OJ平台遇上UI自动化测试

最近在重构我们团队内部使用的在线判题系统（OJ-Club）时，我意识到一个长期被忽视的问题：前端页面的回归测试。每次后端接口或前端组件有改动，哪怕只是调整了一个按钮的颜色或者修改了某个输入框的验证逻辑，都需要测试同学手动把核心流程从头到尾点一遍。判题、提交、查看排名、管理题目……这些高频操作路径，重复执行不仅枯燥，而且随着功能迭代，测试用例越积越多，人工回归的成本和漏测风险都在指数级上升。是时候把Web UI自动化测试这套“组合拳”打起来了。

这个项目，我称之为“OJ-Club的Web UI自动化测试实战”，核心目标很明确：为OJ-Club这个典型的单页应用（SPA）搭建一套稳定、可维护、能快速反馈的UI自动化测试体系。它不是什么高深莫测的“测试开发平台”，而是一个从零开始、步步为营的实战过程。我会基于最主流的Selenium + Pytest技术栈，结合Page Object设计模式，带你走完从环境搭建、用例设计、脚本编写，到持续集成和稳定性提升的全链路。无论你是刚接触自动化测试的QA，还是需要为自研项目补充测试保障的开发者，这套方法都能直接拿来复用。毕竟，在追求快速迭代的今天，没有自动化测试兜底，上线心里总是不踏实的。

2. 技术选型与框架设计思路

为OJ-Club选择自动化测试方案，我主要考量了几个核心因素：技术栈匹配度、社区生态、可维护性以及团队学习成本。OJ-Club前端基于Vue.js，是一个典型的动态渲染的单页应用，这意味着页面元素经常异步加载和更新。

2.1 核心工具链敲定

首先，浏览器自动化工具是基石。Selenium WebDriver依然是这个领域的“定海神针”。它支持所有主流浏览器，API成熟稳定，社区资源极其丰富。虽然近年来有Cypress、Playwright等后起之秀，但Selenium的普适性和对复杂场景（如多窗口、文件上传）的处理能力，使其成为中大型项目、特别是需要兼容多浏览器场景下的稳妥选择。我们直接使用Python语言的Selenium绑定，因为Python在测试领域的生态和简洁语法优势明显。

测试框架方面，Pytest是当仁不让的首选。相比Python自带的unittest，Pytest的语法更简洁（无需继承类），夹具（fixture）机制强大且灵活，断言方式直观（直接用assert），报告生成也美观。更重要的是，它的插件生态可以让我们轻松实现并发测试、失败重试、钩子函数定制等高级功能，这些都是提升自动化测试效率的关键。

浏览器驱动管理，我推荐使用webdriver-manager这个Python库。它彻底解决了手动下载、匹配ChromeDriver/GeckoDriver版本并配置PATH的麻烦。只需一行webdriver-manager install，它就能自动检测本地浏览器版本并下载对应的驱动，让环境配置变得极其简单。

2.2 架构模式：为什么必须是Page Object Model (POM)

对于UI自动化测试，可维护性是比炫技更重要的指标。直接录制回放或者在线性脚本里硬编码元素定位，是项目走向混乱和脆弱的开始。Page Object Model (页面对象模型)是解决这一问题的黄金法则。

POM的核心思想是将页面对象和测试逻辑分离。每一个Web页面（或页面中的一个重要组件）对应一个类（Page Class）。这个类中封装了该页面的所有元素定位器（Locators）和可在这个页面上执行的基本操作（Action Methods），例如输入文本、点击按钮、获取文本等。而测试用例脚本（Test Case）则只包含业务逻辑和断言，通过调用页面对象的方法来完成操作。

这样做的好处是巨大的：

1. 高可维护性：当页面UI发生变化时，比如一个按钮的ID改了，你只需要在一个地方（对应的Page Class）修改元素定位器，所有用到这个按钮的测试用例都无需改动。
2. 高可读性：测试用例读起来就像业务文档，例如login_page.input_username("admin"); login_page.input_password("123456"); login_page.click_submit()，清晰明了。
3. 减少代码重复：公共的操作被封装在页面对象中，避免了在多个测试用例中重复编写相同的定位和操作代码。

对于OJ-Club，我会为登录页、题库列表页、题目详情页、代码提交页、个人中心页等核心页面分别建立对应的Page Class。

2.3 项目目录结构规划

一个清晰的项目结构是良好维护的开始。我的项目目录规划如下：

oj_ui_auto_test/ ├── conftest.py # Pytest全局配置、共享fixture ├── requirements.txt # 项目依赖包列表 ├── config/ │ └── settings.py # 全局配置（URL、超时时间、用户凭证等） ├── pages/ # 页面对象层 │ ├── __init__.py │ ├── base_page.py # 所有页面对象的基类 │ ├── login_page.py │ ├── problem_list_page.py │ └── ... ├── test_cases/ # 测试用例层 │ ├── __init__.py │ ├── test_login.py │ ├── test_problem_submit.py │ └── ... ├── test_data/ # 测试数据层（JSON/YAML/Excel） │ └── user_credentials.yaml ├── utils/ # 工具函数层 │ ├── __init__.py │ ├── logger.py # 日志记录工具 │ └── common_actions.py # 通用操作封装 └── reports/ # 测试报告输出目录（自动生成） └── allure-results/

注意：在base_page.py中，我会封装一些每个页面都可能用到的方法，比如等待元素出现、截图、滚动等。这是POM模式的一个进阶技巧，能进一步减少重复代码。

3. 核心实战：从登录到提交判题的完整用例实现

理论说再多，不如一行代码。我们以OJ-Club最核心的“用户登录 -> 浏览题目 -> 提交代码 -> 查看提交结果”这条主线为例，拆解如何用POM模式实现自动化。

3.1 基础页面类与元素定位策略

首先，在pages/base_page.py中创建所有页面类的基类。它的核心作用是初始化驱动（driver）和提供公共方法。

# pages/base_page.py from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC from selenium.common.exceptions import TimeoutException import logging class BasePage: def __init__(self, driver): self.driver = driver self.logger = logging.getLogger(__name__) self.wait = WebDriverWait(driver, 10) # 显式等待，超时10秒 def find_element(self, locator): """查找单个元素，加入显式等待""" try: element = self.wait.until(EC.presence_of_element_located(locator)) return element except TimeoutException: self.logger.error(f"元素定位超时: {locator}") raise def click_element(self, locator): """点击元素""" element = self.find_element(locator) element.click() def input_text(self, locator, text): """向输入框输入文本""" element = self.find_element(locator) element.clear() element.send_keys(text) def get_element_text(self, locator): """获取元素文本""" element = self.find_element(locator) return element.text # 可以继续添加更多通用方法，如截图、滚动等

接下来，实现第一个页面对象：登录页 (pages/login_page.py)。这里的关键是元素定位器。对于现代前端框架，优先选择那些相对稳定、语义化的属性。

# pages/login_page.py from selenium.webdriver.common.by import By from .base_page import BasePage class LoginPage(BasePage): # 1. 定义所有元素定位器（Locator Tuple） USERNAME_INPUT = (By.ID, 'username') # 假设前端给输入框设置了id PASSWORD_INPUT = (By.NAME, 'password') # 或者用name LOGIN_BUTTON = (By.CSS_SELECTOR, 'button[type="submit"]') # CSS选择器更灵活 ERROR_MESSAGE = (By.CLASS_NAME, 'el-message--error') # 错误提示框 # 2. 封装页面动作（Action Methods） def open_login_page(self, url): self.driver.get(url) return self def enter_username(self, username): self.input_text(self.USERNAME_INPUT, username) return self # 支持链式调用 def enter_password(self, password): self.input_text(self.PASSWORD_INPUT, password) return self def click_login(self): self.click_element(self.LOGIN_BUTTON) def get_error_message(self): """获取登录错误提示信息""" try: return self.get_element_text(self.ERROR_MESSAGE) except: return None # 没有错误信息时返回None # 3. 组合业务流方法（可选，但推荐） def login(self, username, password): """完整的登录流程""" self.enter_username(username) self.enter_password(password) self.click_login()

实操心得：定位器策略。优先顺序：ID > Name > CSS Selector > XPath。尽量避免使用绝对XPath（如/html/body/div[3]/div[1]/button），它极度脆弱。使用相对XPath（如//button[contains(text(), '登录')]）或CSS选择器。对于Vue/React组件，可以和前端约定，为关键测试元素添加固定的># conftest.py import pytest from selenium import webdriver from selenium.webdriver.chrome.service import Service from webdriver_manager.chrome import ChromeDriverManager from config.settings import BASE_URL @pytest.fixture(scope="session") def driver(): """创建并返回一个WebDriver实例，整个测试会话只启动一次浏览器""" # 使用webdriver-manager自动管理驱动 service = Service(ChromeDriverManager().install()) options = webdriver.ChromeOptions() options.add_argument('--headless') # 无头模式，适合CI环境 options.add_argument('--no-sandbox') options.add_argument('--disable-dev-shm-usage') driver = webdriver.Chrome(service=service, options=options) driver.implicitly_wait(5) # 隐式等待，辅助显式等待 driver.maximize_window() yield driver driver.quit() # 测试结束后退出浏览器 @pytest.fixture def login_page(driver): """提供登录页实例""" from pages.login_page import LoginPage return LoginPage(driver).open_login_page(BASE_URL)

现在，编写测试用例：

# test_cases/test_login_and_submit.py import pytest from pages.problem_list_page import ProblemListPage from pages.problem_detail_page import ProblemDetailPage from pages.submission_page import SubmissionPage class TestOJWorkflow: """测试OJ核心工作流""" def test_login_with_valid_credentials(self, login_page): """测试使用有效凭证登录""" # 链式调用，代码非常清晰 login_page.enter_username("test_user").enter_password("secure_pass123").click_login() # 断言：登录成功后，页面应跳转，URL包含'dashboard'或出现用户头像元素 # 这里需要另一个Page Object，比如DashboardPage # 我们先用一个简单的URL断言 assert "dashboard" in login_page.driver.current_url.lower() print("登录成功测试通过") @pytest.mark.dependency(depends=["TestOJWorkflow::test_login_with_valid_credentials"]) def test_browse_and_submit_problem(self, driver, login_page): """ 测试完整的浏览题目并提交代码流程。 依赖登录成功，使用pytest-dependency插件管理用例顺序（非必须，但更清晰）。 """ # 1. 先登录 login_page.login("test_user", "secure_pass123") # 2. 进入题库列表页 problem_list_page = ProblemListPage(driver) first_problem_link = problem_list_page.get_first_problem_link() problem_title = first_problem_link.text first_problem_link.click() # 3. 在题目详情页提交代码 problem_detail_page = ProblemDetailPage(driver) # 断言当前页面标题与点击的题目一致 assert problem_detail_page.get_problem_title() == problem_title # 输入代码（这里假设是一个简单的Hello World） test_code = """ def solve(): print("Hello OJ-Club!") """ problem_detail_page.input_code(test_code) problem_detail_page.select_language("Python 3") problem_detail_page.click_submit_button() # 4. 在提交结果页验证 submission_page = SubmissionPage(driver) # 等待判题结果出现，并断言状态为“Accepted”或类似成功状态 result_status = submission_page.wait_for_judge_result(timeout=30) # 判题可能需要时间 assert result_status == "Accepted", f"判题失败，状态为：{result_status}" print(f"题目'{problem_title}'提交并判题成功，状态：{result_status}")

3.3 处理动态加载与复杂交互

OJ-Club作为SPA，很多内容是通过Ajax动态加载的，比如提交后的判题状态轮询、题目列表的分页加载。这对自动化测试的稳定性提出了挑战。解决方案是显式等待（Explicit Wait）。

我们已经在BasePage的find_element方法中使用了显式等待。对于更复杂的场景，比如等待某个元素文本变成特定值（如判题状态从“Running”变为“Accepted”），需要定制等待条件。

# utils/common_actions.py 或 BasePage 的扩展 from selenium.webdriver.support import expected_conditions as EC def wait_for_text_to_be_present_in_element(driver, locator, text, timeout=30): """等待指定元素的文本包含特定内容""" wait = WebDriverWait(driver, timeout) try: wait.until(EC.text_to_be_present_in_element(locator, text)) return True except TimeoutException: return False # 在SubmissionPage中使用 class SubmissionPage(BasePage): RESULT_STATUS_SPAN = (By.ID, 'judge-result') def wait_for_specific_result(self, expected_text="Accepted", timeout=30): """等待判题结果出现特定文本""" locator = self.RESULT_STATUS_SPAN is_present = wait_for_text_to_be_present_in_element(self.driver, locator, expected_text, timeout) if is_present: return self.get_element_text(locator) else: raise TimeoutException(f"在{timeout}秒内未等到结果状态变为'{expected_text}'")

注意事项：等待策略。不要滥用time.sleep(10)这种固定休眠，它会让测试变得缓慢且不可靠。隐式等待（implicitly_wait）设一个全局较短时间（如5秒）作为后备。显式等待是主力，针对特定操作设置合理的超时。对于判题这种可能耗时较长的操作，超时可以设长一些（如30秒）。

4. 测试数据管理与参数化

硬编码的测试数据（如用户名、密码）是另一个维护痛点。我们将测试数据外部化。

4.1 使用YAML管理测试数据

创建test_data/user_credentials.yaml：

users: admin: username: "admin" password: "admin123" role: "admin" regular_user: username: "test_user" password: "secure_pass123" role: "user" invalid_user: username: "wrong_user" password: "wrong_pass"

在测试中读取：

# conftest.py 或用例中 import yaml import os def load_test_data(file_name): data_file_path = os.path.join(os.path.dirname(__file__), '..', 'test_data', file_name) with open(data_file_path, 'r', encoding='utf-8') as f: return yaml.safe_load(f) # 在测试用例中使用参数化 import pytest user_data = load_test_data('user_credentials.yaml')['users'] @pytest.mark.parametrize("user_key", ["regular_user", "invalid_user"]) def test_login_with_different_users(login_page, user_key): user = user_data[user_key] login_page.login(user['username'], user['password']) if user_key == "regular_user": assert "dashboard" in login_page.driver.current_url.lower() else: error_msg = login_page.get_error_message() assert error_msg is not None and "错误" in error_msg

4.2 通过Pytest Fixture传递数据

更优雅的方式是通过Fixture来提供测试数据：

# conftest.py @pytest.fixture(params=["regular_user", "invalid_user"]) def user_credential(request): data = load_test_data('user_credentials.yaml') return data['users'][request.param] # 测试用例 def test_login_parametrized_by_fixture(login_page, user_credential): login_page.login(user_credential['username'], user_credential['password']) # ... 根据user_credential中的role或预期结果进行断言

5. 提升稳定性与排查常见问题

UI自动化测试被称为“脆弱的测试”，因为它容易受前端变化、网络延迟、弹窗等因素影响。以下是提升稳定性和问题排查的实战技巧。

5.1 常见问题与解决方案速查表

问题现象	可能原因	解决方案与排查步骤
NoSuchElementException(元素找不到)	1. 页面未加载完成。 2. 元素定位器写错或已失效。 3. 元素在iframe或shadow DOM内。 4. 元素被动态生成，DOM结构已变。	1. 增加显式等待，等待元素出现、可点击或可见。 2. 使用浏览器开发者工具重新检查元素属性，更新定位器。优先用>ElementClickInterceptedException(元素点击被拦截)	1. 元素被其他元素（如弹窗、遮罩层）覆盖。 2. 元素在视窗外，需要滚动。 3. 元素状态不可点击（disabled）。	1. 先关闭或处理掉覆盖物。可加入等待，等覆盖物消失。 2. 使用driver.execute_script("arguments[0].scrollIntoView();", element)滚动到元素位置。 3. 检查元素disabled属性，或等待其变为可点击状态（EC.element_to_be_clickable）。
StaleElementReferenceException(元素引用过期)	1. 页面刷新或AJAX操作后，之前找到的元素引用失效。 2. DOM被重新渲染。	1. 这是POM要解决的核心问题之一。避免在变量中存储元素对象过久。每次操作前，通过Page Object的方法重新查找元素。 2. 在Page Class的方法内部进行查找和操作，不要将find_element返回的元素对象传出方法外长期保存。
测试在CI上失败，本地却成功	1. CI环境与本地环境差异（浏览器版本、分辨率、资源加载速度）。 2. 无头模式（Headless）下某些行为不同。 3. 并发执行导致资源竞争。	1. 确保CI环境使用与本地一致的浏览器版本（用webdriver-manager）。 2. 在无头模式下，可以添加--window-size=1920,1080参数，并考虑禁用GPU加速--disable-gpu。 3. 使用pytest-xdist进行并发测试时，确保测试用例是独立的，不共享状态。为每个用例创建独立的用户或数据。
测试执行速度慢	1. 过多的固定等待(time.sleep)。 2. 不必要的浏览器最大化、截图操作。 3. 用例顺序执行，未利用并发。	1.将所有sleep替换为显式等待。 2. 仅在失败时截图（通过pytest钩子函数实现）。 3. 使用pytest-xdist插件并行运行测试（pytest -n auto）。

5.2 关键稳定性增强技巧

1. 智能等待与重试机制：对于网络请求或异步操作，使用“轮询+超时”的等待策略。可以为某些不稳定操作封装一个带重试的方法。

   def click_with_retry(driver, locator, retries=3): for i in range(retries): try: element = WebDriverWait(driver, 10).until(EC.element_to_be_clickable(locator)) element.click() return True except (ElementClickInterceptedException, StaleElementReferenceException) as e: if i == retries - 1: raise e time.sleep(1) # 重试前短暂等待 return False

2. 失败自动截图：在conftest.py中设置自动截图钩子，当用例失败时，自动截取当前页面和浏览器日志，保存到报告目录，这是定位问题的“现场照片”。

   # conftest.py import allure from datetime import datetime @pytest.hookimpl(tryfirst=True, hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: driver = item.funcargs.get('driver') if driver: timestamp = datetime.now().strftime("%Y%m%d_%H%M%S") screenshot_path = f"./reports/screenshot_failure_{item.name}_{timestamp}.png" driver.save_screenshot(screenshot_path) allure.attach.file(screenshot_path, name="失败截图", attachment_type=allure.attachment_type.PNG)

3. 使用Allure生成精美报告：Pytest结合Allure框架可以生成非常直观的测试报告，包含用例层级、步骤、截图、错误日志等，极大方便结果分析和历史追溯。安装pytest-allure插件，运行后使用allure serve reports/allure-results查看报告。

6. 集成到CI/CD流程

自动化测试只有集成到持续集成（CI）流程中，才能最大化其价值。这里以GitHub Actions为例，展示如何将OJ-Club的UI自动化测试加入CI。

在项目根目录创建.github/workflows/ui-test.yml：

name: OJ-Club UI Automation Test on: push: branches: [ main, develop ] pull_request: branches: [ main ] 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 Chrome) run: | sudo apt-get update sudo apt-get install -y wget unzip libgconf-2-4 - name: Install Python dependencies run: | pip install --upgrade pip pip install -r requirements.txt - name: Run UI Tests with Pytest run: | # 无头模式下运行测试，并生成Allure结果 pytest test_cases/ -v --alluredir=reports/allure-results - name: Upload Allure Report (Optional) if: always() # 即使测试失败也上传报告 uses: actions/upload-artifact@v3 with: name: allure-report path: reports/allure-results

这个工作流会在每次推送到主分支或发起Pull Request时自动运行UI测试。关键在于：

1. 环境一致性：CI环境使用固定的Ubuntu版本和Python版本。
2. 无头模式：测试在无界面的Chrome（headless）中运行，节省资源且适配CI环境。
3. 结果收集：测试结果（包括Allure报告数据）被保存为制品，可供下载查看。

踩坑记录：CI环境下的浏览器问题。在CI的Linux无头环境中，Chrome可能需要额外的系统依赖（如libgconf-2-4）和特定的启动参数（--no-sandbox,--disable-dev-shm-usage）才能稳定运行。这些参数在上面的conftest.py的driverfixture中已经体现。

7. 维护与发展：让自动化测试资产持续增值

搭建只是开始，维护才是真正的挑战。为了让这套自动化测试框架长期健康运行，需要建立规范。

1. 代码审查：将Page Object和测试用例的代码纳入常规代码审查流程。关注定位器的稳定性、方法的可复用性、用例的独立性。
2. 定期运行与监控：除了CI触发，可以设置定时任务（如每天凌晨）运行核心冒烟测试用例，监控通过率。通过率下降往往是系统不稳定的早期信号。
3. 用例分层：将测试用例分为不同层级：
   • 冒烟测试（Smoke）：覆盖最核心的登录、浏览、提交主流程。执行快，用于快速验证基本功能。
   • 回归测试（Regression）：覆盖所有重要功能点的用例集合。在版本发布前执行。
   • 扩展测试（Extended）：包含边界值、异常场景等。可以按需执行。 使用Pytest的标记（mark）功能来分类，例如@pytest.mark.smoke。
4. 与手动测试协作：自动化测试不能完全替代手动测试，尤其是探索性测试和用户体验测试。自动化用于保障“已知”的正确性，手动测试用于发现“未知”的问题。两者互补。

为OJ-Club搭建UI自动化测试的过程，是一个将重复劳动转化为可重复利用资产的过程。初期投入确实存在，但一旦核心流程被自动化覆盖，它带来的回归效率提升、深夜发布信心和问题快速定位能力，会让所有投入都变得值得。这套以Selenium+Pytest+POM为基础的框架，其设计思想和实践模式具有普适性，完全可以迁移到其他Web项目的测试中。记住，好的自动化测试不是一蹴而就的，而是随着项目迭代不断演进和丰富的活文档。