1. 项目概述为什么我们需要一个“框架”而不仅仅是脚本如果你已经用Selenium写过几个自动化测试脚本可能会发现一个现象刚开始写一两个页面操作的脚本时感觉挺顺手代码也不复杂。但随着测试用例数量增加到几十个、上百个项目里开始出现大量重复的代码——比如每个脚本开头都要初始化浏览器驱动、结尾都要关闭浏览器定位元素失败时错误信息千奇百怪排查起来像大海捞针测试数据散落在各个脚本里改一个参数要翻好几个文件。这时候你就会意识到一堆零散的脚本和一个真正的“自动化测试框架”之间隔着一条鸿沟。我见过太多团队在这个阶段陷入困境。他们最初的“自动化测试”就是一堆Python文件每个文件里塞满了driver.find_element和time.sleep。当业务迭代页面元素频繁变动时维护成本呈指数级上升最终导致自动化项目被废弃大家又回到了手动测试的老路。所以今天我想分享的不是又一个“Selenium入门教程”而是如何从零开始搭建一个健壮、可维护、易扩展的自动化测试框架。这个框架能让你团队里的中级甚至初级测试工程师都能高效地编写和执行自动化用例真正把自动化用起来而不是当成一个摆设。这个框架的核心价值在于“标准化”和“解耦”。它通过分层设计比如将页面操作、测试用例、测试数据、测试报告分离让代码结构清晰通过封装公共操作如元素查找、异常处理、日志记录减少重复代码通过引入成熟的测试运行器如pytest和报告工具提升执行效率和结果可读性。最终目标是当你需要测试一个新的功能模块时大部分基础工作框架已经帮你做好了你只需要关注最核心的业务逻辑测试本身。2. 框架核心架构设计与选型考量一个典型的、工业级的Selenium自动化测试框架不会把所有代码都堆在一个文件里。我推荐采用“四层架构”的设计思想这在我经历过的多个中大型项目中都被验证是行之有效的。这四层从上到下分别是测试用例层、测试步骤层、页面对象层、基础工具层。2.1 分层架构解析每一层负责什么基础工具层是整个框架的基石。它位于最底层不关心任何业务逻辑只提供最通用的技术服务。这一层主要包括浏览器驱动管理负责WebDriver的初始化、配置如无头模式、窗口大小、禁用GPU和退出。一个好的驱动管理器应该能支持多浏览器Chrome, Firefox, Edge并方便地切换。元素定位封装对Selenium原生的find_element方法进行二次封装。原生的方法在元素找不到时只会抛出NoSuchElementException信息量很少。我们的封装应该加入显式等待、更友好的错误日志比如输出当前页面URL、页面源码片段、以及自动重试机制。日志记录模块使用Python标准的logging模块进行配置在关键操作如点击、输入、断言时记录信息、警告和错误。日志应同时输出到控制台和文件方便实时查看和事后追溯。配置文件读取使用configparser或yaml模块来管理全局配置如被测系统URL、数据库连接信息、超时时间、截图保存路径等。避免将硬编码写在脚本中。页面对象层是Selenium框架设计的精髓即Page Object Model。它的核心思想是将一个Web页面抽象成一个Python类页面上的元素就是这个类的属性页面上的操作如登录、搜索就是这个类的方法。这样做的好处是当页面UI发生变化时你只需要修改这个页面类中的元素定位器所有用到这个页面的测试用例都无需改动极大降低了维护成本。测试步骤层有时也叫“业务流层”。一个完整的用户操作比如“下单购物”通常涉及多个页面的连续操作。这一层将多个页面对象的方法组合起来形成一个高层的、可复用的业务步骤。例如一个login_and_checkout函数内部会依次调用LoginPage.login()、HomePage.search_product()、ProductPage.add_to_cart()和CartPage.checkout()。测试用例层直接调用这些业务步骤使得用例代码非常简洁更像是在描述测试场景。测试用例层是最顶层这里使用像pytest这样的测试框架来组织和运行用例。每个测试用例都是一个以test_开头的函数内部调用测试步骤层提供的函数并使用assert语句进行验证。这一层应该只包含测试逻辑和断言不出现任何Selenium API的直接调用。2.2 关键工具选型为什么是它们编程语言Python。这是目前自动化测试领域最主流的选择。语法简洁学习曲线平缓拥有极其丰富的测试生态库pytest, unittest, Allure。对于测试团队来说Python的易读易写特性能降低协作成本。当然如果你团队主力是JavaTestNGSelenuim也是成熟方案但本文以Python体系展开。测试运行器pytest。它远比Python自带的unittest强大和灵活。支持丰富的插件如并行执行pytest-xdist、失败重跑pytest-rerunfailures、灵活的用例标记和筛选、以及强大的夹具系统。它的断言是原生的assert语句写起来更自然。pytest已经成为Python测试的事实标准。报告生成器Allure。这是打造“专业”测试报告的不二之选。它生成的HTML报告美观、交互性强能清晰展示测试套件层级、用例状态、步骤详情、附件截图、日志。与pytest通过allure-pytest插件可以无缝集成。虽然需要额外安装Java环境但其带来的价值远超这点麻烦。数据驱动pytest的pytest.mark.parametrize装饰器。对于需要多组数据验证的用例如登录功能测试不同的用户名密码组合使用参数化可以避免写多个重复的测试函数让用例更清晰。复杂的数据也可以从JSON、YAML或Excel文件中读取。持续集成Jenkins。框架搭建好后最终要接入CI/CD流水线。Jenkins可以定时或触发式地执行你的测试套件并将Allure报告发布出来供团队查看。在Jenkins job中配置Python环境、安装依赖、执行pytest命令并收集结果是标准流程。注意不要一开始就追求大而全的框架。建议采用“演进式”搭建。先实现基础工具层和页面对象层跑通一两个核心流程的测试。然后再逐步引入pytest、Allure、数据驱动和CI。这样每步都能看到成效团队也更容易接受。3. 从零开始搭建框架一步步实现理论讲完了我们动手搭建。假设我们的项目叫auto_test_framework目录结构规划如下auto_test_framework/ ├── configs/ # 配置文件目录 │ └── config.ini ├── logs/ # 日志文件目录自动生成 ├── reports/ # 测试报告目录自动生成 │ ├── allure-results/ │ └── html/ ├── screenshots/ # 失败截图目录自动生成 ├── common/ # 基础工具层 │ ├── __init__.py │ ├── base_driver.py # 驱动管理 │ ├── base_page.py # 页面基类 │ ├── logger.py # 日志模块 │ └── utils.py # 其他工具函数 ├── page_objects/ # 页面对象层 │ ├── __init__.py │ ├── login_page.py │ └── home_page.py ├── test_cases/ # 测试用例层 │ ├── __init__.py │ └── test_login.py ├── conftest.py # pytest全局夹具 └── requirements.txt # 项目依赖3.1 第一步初始化项目与依赖管理在项目根目录下创建requirements.txt文件这是Python项目的依赖清单。# requirements.txt selenium4.15.0 pytest7.4.4 pytest-html4.1.1 allure-pytest2.13.2 pytest-rerunfailures12.0 pytest-xdist3.5.0 webdriver-manager4.0.1 PyYAML6.0.1使用pip install -r requirements.txt一键安装所有依赖。这里重点说两个webdriver-manager这是一个神器。传统方式需要手动下载不同版本的浏览器驱动chromedriver, geckodriver并配置PATH。这个库可以自动检测你本地安装的浏览器版本并下载匹配的驱动彻底解决了驱动版本不匹配的噩梦。pytest-rerunfailures和pytest-xdist前者用于失败用例重试对于UI自动化这种受网络、环境波动影响较大的测试非常有用后者用于多进程并行执行大幅缩短测试总耗时。3.2 第二步构建基础工具层这是最核心也最体现功力的部分。我们先实现common/logger.py一个线程安全的日志模块。# common/logger.py import logging import os from logging.handlers import RotatingFileHandler from datetime import datetime class Logger: _instance None _lock threading.Lock() def __new__(cls): # 实现单例模式确保全局只有一个logger实例 if cls._instance is None: with cls._lock: if cls._instance is None: cls._instance super().__new__(cls) cls._instance._init_logger() return cls._instance def _init_logger(self): self.logger logging.getLogger(auto_test) self.logger.setLevel(logging.DEBUG) # 设置最低级别 # 避免重复添加handler if self.logger.handlers: return # 1. 控制台处理器 ch logging.StreamHandler() ch.setLevel(logging.INFO) console_fmt logging.Formatter(%(asctime)s - %(levelname)s - %(message)s) ch.setFormatter(console_fmt) self.logger.addHandler(ch) # 2. 文件处理器按日期和大小滚动 log_dir os.path.join(os.path.dirname(os.path.dirname(__file__)), logs) os.makedirs(log_dir, exist_okTrue) log_file os.path.join(log_dir, ftest_{datetime.now().strftime(%Y%m%d)}.log) fh RotatingFileHandler(log_file, maxBytes10*1024*1024, backupCount5) # 每个文件10M保留5个 fh.setLevel(logging.DEBUG) file_fmt logging.Formatter(%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s) fh.setFormatter(file_fmt) self.logger.addHandler(fh) def get_logger(self): return self.logger # 提供一个便捷的全局访问点 log Logger().get_logger()接下来是重头戏common/base_driver.py负责WebDriver的生命周期管理。# common/base_driver.py from selenium import webdriver from selenium.webdriver.chrome.service import Service as ChromeService from selenium.webdriver.firefox.service import Service as FirefoxService from webdriver_manager.chrome import ChromeDriverManager from webdriver_manager.firefox import GeckoDriverManager from common.logger import log import threading class DriverManager: # 使用threading.local()为每个线程创建独立的driver实例支持并行测试 _local threading.local() classmethod def get_driver(cls, browserchrome, headlessFalse): 获取WebDriver实例 if not hasattr(cls._local, driver) or cls._local.driver is None: cls._local.driver cls._create_driver(browser, headless) log.info(f初始化 {browser} 浏览器驱动无头模式{headless}) return cls._local.driver classmethod def _create_driver(cls, browser, headless): driver None try: if browser.lower() chrome: options webdriver.ChromeOptions() if headless: options.add_argument(--headlessnew) # Chrome 112 推荐使用new options.add_argument(--no-sandbox) options.add_argument(--disable-dev-shm-usage) options.add_argument(--disable-gpu) options.add_argument(--window-size1920,1080) # 使用webdriver-manager自动管理驱动 service ChromeService(ChromeDriverManager().install()) driver webdriver.Chrome(serviceservice, optionsoptions) elif browser.lower() firefox: options webdriver.FirefoxOptions() if headless: options.add_argument(--headless) # Firefox的webdriver-manager使用方式略有不同 service FirefoxService(GeckoDriverManager().install()) driver webdriver.Firefox(serviceservice, optionsoptions) else: raise ValueError(f不支持的浏览器类型: {browser}) # 全局隐式等待非必需推荐用显式等待 driver.implicitly_wait(10) # 页面加载超时设置 driver.set_page_load_timeout(30) driver.set_script_timeout(30) return driver except Exception as e: log.error(f创建{browser}驱动失败: {e}) raise classmethod def quit_driver(cls): 退出并清理WebDriver if hasattr(cls._local, driver) and cls._local.driver: try: cls._local.driver.quit() log.info(浏览器驱动已退出) except Exception as e: log.error(f退出浏览器驱动时发生错误: {e}) finally: cls._local.driver None然后是页面对象的基类common/base_page.py它封装了最常用的元素操作并融入了显式等待和日志。# common/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, StaleElementReferenceException from common.logger import log import time class BasePage: def __init__(self, driver): self.driver driver self.wait WebDriverWait(self.driver, timeout10, poll_frequency0.5) def find_element(self, locator, timeoutNone): 查找单个元素支持显式等待 :param locator: 元组如 (By.ID, username) :param timeout: 自定义超时时间 :return: WebElement 对象 wait_obj self.wait if timeout is None else WebDriverWait(self.driver, timeout) try: log.debug(f正在查找元素: {locator}) element wait_obj.until(EC.presence_of_element_located(locator)) # 额外等待一下元素可交互非必须但更稳健 wait_obj.until(EC.visibility_of(element)) return element except TimeoutException: log.error(f元素查找超时: {locator}。当前URL: {self.driver.current_url}) # 失败时自动截图 self._take_screenshot(element_not_found) raise def click(self, locator, timeoutNone): 点击元素增加重试机制应对StaleElementReferenceException retries 2 for attempt in range(retries): try: element self.find_element(locator, timeout) element.click() log.info(f点击元素: {locator}) break except StaleElementReferenceException: if attempt retries - 1: log.warning(f元素状态过期第{attempt1}次重试...) time.sleep(0.5) else: log.error(f点击元素失败重试{retries}次后仍状态过期: {locator}) self._take_screenshot(click_stale_element) raise def input_text(self, locator, text, clear_firstTrue, timeoutNone): 向输入框输入文本 element self.find_element(locator, timeout) if clear_first: element.clear() element.send_keys(text) log.info(f向元素 {locator} 输入文本: {text}) def get_text(self, locator, timeoutNone): 获取元素的文本内容 element self.find_element(locator, timeout) text element.text log.debug(f获取元素 {locator} 的文本: {text}) return text def _take_screenshot(self, name): 内部方法截图并保存 screenshot_dir os.path.join(os.path.dirname(os.path.dirname(__file__)), screenshots) os.makedirs(screenshot_dir, exist_okTrue) timestamp time.strftime(%Y%m%d_%H%M%S) file_path os.path.join(screenshot_dir, f{name}_{timestamp}.png) self.driver.save_screenshot(file_path) log.info(f截图已保存至: {file_path}) return file_path3.3 第三步实现页面对象层以登录页面为例。假设我们有一个简单的登录页用户名输入框ID是username密码输入框ID是password登录按钮ID是submit。# page_objects/login_page.py from selenium.webdriver.common.by import By from common.base_page import BasePage class LoginPage(BasePage): # 1. 定义页面元素定位器核心 # 所有元素定位信息集中在这里UI一变只改这里。 USERNAME_INPUT (By.ID, username) PASSWORD_INPUT (By.ID, password) SUBMIT_BUTTON (By.ID, submit) ERROR_MSG_SPAN (By.CLASS_NAME, error-message) # 2. 页面操作方法 def login(self, username, password): 登录操作 self.input_text(self.USERNAME_INPUT, username) self.input_text(self.PASSWORD_INPUT, password) self.click(self.SUBMIT_BUTTON) log.info(f执行登录操作用户名: {username}) def get_error_message(self): 获取登录错误提示信息 try: # 错误信息可能不会立即出现给点等待时间 msg self.get_text(self.ERROR_MSG_SPAN, timeout5) return msg except TimeoutException: return None # 没有错误信息可能登录成功3.4 第四步编写测试用例并与pytest集成首先在项目根目录创建conftest.py这是pytest的本地插件文件用于定义全局的夹具。# conftest.py import pytest from common.base_driver import DriverManager from common.logger import log pytest.fixture(scopefunction) # 每个测试函数执行一次 def driver(): 提供WebDriver夹具 _driver DriverManager.get_driver(browserchrome, headlessTrue) # 默认用无头Chrome yield _driver # 测试函数执行完毕后清理退出浏览器 DriverManager.quit_driver() pytest.fixture(scopefunction) def login_page(driver): 提供登录页面对象夹具 from page_objects.login_page import LoginPage # 假设登录页面的URL是固定的可以先导航过去 driver.get(https://your-test-site.com/login) return LoginPage(driver) pytest.hookimpl(tryfirstTrue, hookwrapperTrue) def pytest_runtest_makereport(item, call): 钩子函数在测试执行后获取结果并为失败用例截图 outcome yield rep outcome.get_result() # 只关注测试用例setup/call/teardown的call阶段且是失败的情况 if rep.when call and rep.failed: driver_fixture item.funcargs.get(driver) if driver_fixture: try: screenshot_path driver_fixture.save_screenshot(failure.png) # 简单示例实际应用更复杂的路径 log.error(f测试失败截图已保存。) # 可以将截图路径附加到Allure报告中 if hasattr(rep, extra): import allure allure.attach.file(screenshot_path, name失败截图, attachment_typeallure.attachment_type.PNG) except Exception as e: log.error(f截图失败: {e})现在可以编写真正的测试用例了。# test_cases/test_login.py import pytest from common.logger import log class TestLogin: 登录功能测试类 # 使用参数化进行数据驱动测试 pytest.mark.parametrize(username, password, expected, [ (correct_user, correct_pwd, success), # 正确登录 (wrong_user, correct_pwd, invalid_username), # 用户名错误 (correct_user, , password_required), # 密码为空 ]) def test_login_with_different_inputs(self, login_page, username, password, expected): 测试不同输入组合下的登录行为 log.info(f执行测试用例: username{username}, password{password}, 期望结果{expected}) login_page.login(username, password) if expected success: # 验证登录成功例如检查是否跳转到首页或出现欢迎语 # 这里假设登录成功后页面标题会变 assert login_page.driver.title 首页 - 我的网站, 登录成功后未跳转到首页 else: # 验证登录失败并出现对应的错误信息 error_msg login_page.get_error_message() assert error_msg is not None, 登录失败时未显示错误信息 # 可以根据expected判断具体的错误信息内容这里简化处理 assert 错误 in error_msg or 无效 in error_msg def test_login_with_remember_me(self, login_page): 测试‘记住我’功能假设页面上有复选框 # 先找到“记住我”复选框并点击 # remember_checkbox (By.ID, remember) # login_page.click(remember_checkbox) # 然后执行登录 # login_page.login(user, pwd) # 重新打开浏览器访问登录页检查用户名是否自动填充此功能实现较复杂需操作cookies或localStorage # 此处仅作为场景示例 log.info(测试‘记住我’功能示例) assert True # 占位断言3.5 第五步执行测试并生成报告在项目根目录下可以通过命令行执行测试并生成报告。1. 使用pytest运行测试并生成简单的HTML报告pytest test_cases/ -v --htmlreports/html/report.html --self-contained-html-v显示详细输出--html生成HTML报告--self-contained-html将CSS等内联生成单个文件。2. 使用Allure生成更强大的报告首先需要安装Allure命令行工具需Java环境。然后运行# 第一步运行测试并生成Allure结果数据 pytest test_cases/ -v --alluredirreports/allure-results # 第二步根据结果数据生成HTML报告 allure generate reports/allure-results -o reports/allure-html --clean # 第三步打开报告本地查看 allure open reports/allure-htmlAllure报告会清晰展示测试套件、通过率、耗时、每个测试用例的步骤详情、日志和附件如我们的失败截图非常专业。4. 高级技巧与实战避坑指南框架搭起来只是第一步想让它稳定可靠地运行在CI/CD流水线中还需要很多“踩过坑”才知道的经验。4.1 元素定位的稳定性之道UI自动化最大的敌人就是“元素定位失败”。除了使用BasePage里封装的显式等待还有以下技巧优先使用ID和Name它们通常是唯一且稳定的。但前端框架如React, Vue自动生成的ID可能每次运行都变要小心。慎用XPath和CSS Selector它们很强大但也脆弱。避免使用绝对路径如/html/body/div[3]/div[2]/span尽量使用相对路径和属性组合。例如//button[contains(class, submit-btn) and text()登录]比//*[idapp]/div/button要好。应对动态元素对于class里带随机字符串或ID动态生成的情况使用contains,starts-with等XPath函数进行模糊匹配。或者与开发约定为关键测试元素添加固定的>pytest test_cases/ -n 4 # 使用4个worker并行执行UI测试受环境波动影响大偶尔失败可能是网络卡顿、资源加载慢导致的。使用pytest-rerunfailures可以自动重试失败的用例。pytest test_cases/ --reruns 3 --reruns-delay 2 # 失败后重试3次每次间隔2秒也可以在conftest.py或pytest.ini配置文件中全局设置这些选项。4.5 框架配置化将浏览器类型、是否无头、基础URL、超时时间等都放到配置文件中。例如使用config.ini# configs/config.ini [Browser] name chrome headless true window_size 1920,1080 implicit_wait 10 page_load_timeout 30 [Environment] base_url https://your-test-site.com login_url %(base_url)s/login [Report] allure_results_dir reports/allure-results allure_report_dir reports/allure-html screenshot_on_failure true然后创建一个配置读取的工具类。5. 常见问题排查与效能提升即使框架搭建得再完善在实际运行中还是会遇到各种问题。这里记录一些高频问题的排查思路。5.1 典型问题速查表问题现象可能原因排查步骤与解决方案NoSuchElementException1. 元素定位器写错了。2. 页面尚未加载完成。3. 元素在iframe或shadow DOM内。4. 元素是动态生成的需要等待。1. 在浏览器开发者工具中验证定位器。2. 添加显式等待presence_of_element_located或visibility_of_element_located。3. 检查并切换到正确的iframe。对于Shadow DOM使用driver.execute_script穿透。4. 使用等待条件如element_to_be_clickable。ElementClickInterceptedException1. 元素被其他元素如弹窗、遮罩层遮挡。2. 元素不在可视区域内。1. 先关闭或处理遮挡物。2. 使用driver.execute_script(arguments[0].scrollIntoView();, element)滚动到元素位置。3. 尝试使用JavaScript直接点击driver.execute_script(arguments[0].click();, element)。StaleElementReferenceException之前找到的元素因为页面刷新或DOM更新而“过期”了。1.最佳实践采用“实时查找”模式即每次操作前都重新查找元素我们的BasePage方法已封装此逻辑。2. 在发生此异常时进行重试我们的click方法已实现。测试在CI服务器上失败本地却成功1. CI环境与本地环境差异浏览器版本、屏幕分辨率、网络。2. 时间不同步导致Cookie/token过期。3. CI环境资源不足运行缓慢。1. 统一环境使用Docker容器固化测试环境浏览器驱动版本。2. 在CI脚本中增加环境检查和时间同步。3. 增加等待时间和失败重试机制。使用无头模式并禁用GPU加速。测试执行速度慢1. 使用了过多的固定等待(time.sleep)。2. 没有使用并行测试。3. 每次用例都重启浏览器。1. 全面替换为显式等待。2. 使用pytest-xdist并行执行。3. 考虑使用pytest的scopesession夹具一个会话只启动一次浏览器需注意用例间的隔离与清理。5.2 效能提升点用例设计原则保持用例独立性。每个用例都应该能单独运行且不依赖其他用例的状态。这意味着每个用例开始前可能需要“前置条件”如登录结束后需要“后置清理”如退出登录、清理测试数据。这可以通过pytest的setup_method和teardown_method或更灵活的夹具系统来实现。选择性地运行用例使用pytest的标记功能。给冒烟测试用例打上pytest.mark.smoke给某个模块的用例打上pytest.mark.login。然后可以通过pytest -m smoke只运行冒烟测试或者pytest -m not slow排除标记为slow的用例。持续集成流水线将你的测试框架集成到Jenkins、GitLab CI或GitHub Actions中。关键步骤包括拉取代码 - 安装依赖pip install -r requirements.txt - 执行测试pytest ... - 收集结果和报告 - 归档报告并发送通知如邮件、钉钉/飞书机器人。这样就能实现代码提交后自动回归测试及时发现问题。搭建一个成熟的Selenium自动化测试框架初期投入确实不小但一旦步入正轨它带来的回归测试效率提升、人力释放和质量保障的稳定性价值是巨大的。记住框架是为你服务的工具不要被框架束缚。在实际项目中根据团队规模和项目特点对上述架构做适当的裁剪和调整找到最适合你们的那把“瑞士军刀”。