1. 项目概述从零到一构建一个可维护的UI自动化框架如果你已经用Selenium写过几个简单的脚本比如登录一个网站、点击几个按钮你可能会发现当脚本数量一多或者测试场景稍微复杂一点代码就会变得一团糟。重复的定位器、散落在各处的硬编码数据、脆弱的等待逻辑还有每次运行都要重新配置浏览器驱动——这些琐事会迅速消耗你的热情。这时候你就需要一个框架。这个“webUI自动化之基本框架搭建”项目就是来解决这些痛点的。它不是要教你写一个driver.find_element而是要带你搭建一个结构清晰、易于维护、能够支撑真实项目迭代的自动化工程骨架。我们将基于Python和Selenium融入Page Object ModelPOM设计模式并整合日志、配置管理、数据驱动等工程化实践。无论你是想提升个人项目的代码质量还是为团队自动化测试铺路这套从实践中总结出的框架搭建思路都能让你告别脚本的“草台班子”走向工程化的“正规军”。2. 核心设计思路为什么是POM与分层架构在开始敲代码之前搞清楚“为什么”比知道“怎么做”更重要。一个健壮的自动化框架其核心价值在于提升脚本的可维护性、可读性和复用性。直接录制或线性编写的脚本之所以脆弱是因为它将页面元素定位、业务操作和测试数据/断言高度耦合在一起。页面UI一变你得在所有脚本里搜索并修改对应的定位器这无疑是场灾难。2.1 采用Page Object Model (POM) 模式POM是目前UI自动化领域公认的最佳实践。它的核心思想是将测试脚本和页面对象分离。每一个网页或一个网页的某个重要部分被抽象成一个“页面对象类”。这个类只做两件事封装元素定位器所有这个页面的按钮、输入框、链接的定位方式如XPath, CSS Selector都作为这个类的属性。封装页面操作所有在这个页面上可以进行的操作如输入用户名、点击登录、获取提示信息都作为这个类的方法。这样做的好处是显而易见的。当登录按钮的ID从loginBtn变成了submitLogin你只需要在一个地方登录页面对象类修改这个定位器所有调用登录操作的测试脚本都无需改动。测试脚本从此变得非常清爽它只关心业务流“打开登录页 - 输入凭证 - 点击登录 - 验证跳转”至于怎么找到输入框、怎么点击那是页面对象的事。2.2 设计分层架构仅有POM还不够我们需要一个清晰的分层结构来管理不同职责的代码。我推荐的基础三层架构如下基础层 (Base Layer)这是框架的基石。主要包括WebDriver的初始化与销毁单例模式管理避免重复创建。对Selenium原生API的二次封装比如封装更智能的等待、更安全的点击、通用的滚动查找等。这层目的是向上提供稳定、增强的浏览器操作接口。日志记录器的初始化确保所有操作都有迹可循。页面对象层 (Page Object Layer)基于POM模式这一层由一个个页面类组成。它们继承自基础层提供的“基础页面类”从而获得那些封装好的增强方法。这一层是框架的核心资产对应着被测系统的各个界面。测试用例层 (Test Case Layer)这是编写具体测试场景的地方。测试用例调用页面对象层的方法组织业务逻辑并加入断言进行验证。这一层应该尽量“薄”只包含测试逻辑和数据。此外我们还需要两个重要的支撑模块数据层 (Data Layer)用于管理测试数据如账号、密码、商品信息通常使用JSON、YAML、Excel或数据库。实现数据与脚本的分离。工具层 (Utils Layer)存放通用工具函数如读取配置文件、生成随机数据、发送测试报告邮件、处理图像验证码如果需要等。这样的分层让每一层职责单一耦合度低无论是后续添加新页面、修改定位器还是更换数据源都变得轻而易举。3. 环境准备与核心组件配置理论清晰了我们开始动手搭建。一个可靠的环境是成功的第一步。3.1 Python与依赖库安装首先确保你安装了Python建议3.8及以上版本。然后我们通过pip安装核心依赖。我强烈建议使用虚拟环境如venv来隔离项目依赖。# 创建并激活虚拟环境以Windows为例 python -m venv venv venv\Scripts\activate # 安装核心库 pip install selenium # 安装WebDriver管理器它可以帮助我们自动下载和管理浏览器驱动省去手动配置的麻烦 pip install webdriver-manager # 安装用于数据处理的库例如读取Excel测试数据 pip install openpyxl pandas # 安装用于日志和配置文件的库 pip install PyYAMLwebdriver-manager是一个神器。以前我们需要根据浏览器版本去官网下载对应版本的chromedriver.exe或geckodriver.exe并配置PATH。现在只需要几行代码它就能自动处理这一切极大降低了环境配置的复杂度。3.2 项目目录结构规划在代码编辑器中如VSCode、PyCharm创建一个新的项目文件夹并规划如下目录结构。一个清晰的结构是框架可维护性的物理体现。your_auto_framework/ │ ├── configs/ # 配置文件目录 │ ├── config.yaml # 主配置文件数据库、URL、日志级别等 │ └── elements.yaml # 可选将元素定位信息统一管理 │ ├── data/ # 测试数据目录 │ ├── test_data.xlsx # Excel测试数据 │ └── user_data.json # JSON测试数据 │ ├── logs/ # 日志文件目录程序运行时自动生成 │ ├── page_objects/ # 页面对象层 │ ├── __init__.py │ ├── base_page.py # 基础页面类 │ ├── login_page.py # 登录页面类 │ ├── home_page.py # 主页类 │ └── ... # 其他页面类 │ ├── test_cases/ # 测试用例层 │ ├── __init__.py │ ├── conftest.py # Pytest的共享夹具配置如driver初始化 │ ├── test_login.py # 登录测试用例 │ └── ... # 其他测试用例 │ ├── utils/ # 工具层 │ ├── __init__.py │ ├── logger.py # 日志记录器模块 │ ├── config_reader.py # 配置文件读取模块 │ └── common_actions.py # 通用操作封装 │ ├── reports/ # 测试报告目录可搭配Allure、HTMLTestRunner生成 │ └── requirements.txt # 项目依赖清单注意__init__.py文件的作用是让Python将其所在的目录视为一个包Package从而允许我们使用from page_objects import LoginPage这样的导入语句。即使它是空的也必须存在。4. 基础层搭建驱动、日志与通用操作封装这是最底层也是决定框架稳定性的关键层。4.1 单例模式管理WebDriver在utils目录下创建或直接在根目录创建一个driver_manager.py。我们使用单例模式确保在整个测试过程中只有一个WebDriver实例被创建和复用。# utils/driver_manager.py from selenium import webdriver from selenium.webdriver.chrome.service import Service as ChromeService from webdriver_manager.chrome import ChromeDriverManager from webdriver_manager.firefox import GeckoDriverManager import threading class DriverManager: _instance None _lock threading.Lock() driver None def __new__(cls): with cls._lock: if cls._instance is None: cls._instance super(DriverManager, cls).__new__(cls) return cls._instance def get_driver(self, browser_typechrome): if self.driver is None: if browser_type.lower() chrome: # 使用webdriver-manager自动管理驱动 service ChromeService(ChromeDriverManager().install()) options webdriver.ChromeOptions() # 添加常用选项 options.add_argument(--ignore-certificate-errors) options.add_argument(--disable-gpu) # 可设置为无头模式用于CI/CD环境 # options.add_argument(--headless) self.driver webdriver.Chrome(serviceservice, optionsoptions) elif browser_type.lower() firefox: service webdriver.FirefoxService(GeckoDriverManager().install()) self.driver webdriver.Firefox(serviceservice) else: raise ValueError(fUnsupported browser: {browser_type}) self.driver.implicitly_wait(10) # 设置隐式等待 self.driver.maximize_window() return self.driver def quit_driver(self): if self.driver: self.driver.quit() self.driver None # 全局访问点 driver_manager DriverManager()为什么这么设计单例模式避免了在多个测试用例中重复创建Driver节省资源也保证了浏览器上下文的一致性。通过webdriver-manager我们彻底摆脱了手动下载和配置驱动的繁琐。4.2 封装增强的通用操作与等待Selenium的原生方法有时不够健壮。我们在page_objects/base_page.py中创建一个基础页面类对所有页面对象类提供增强支持。# page_objects/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 utils.driver_manager import driver_manager import logging class BasePage: def __init__(self): self.driver driver_manager.get_driver() self.logger logging.getLogger(__name__) self.wait WebDriverWait(self.driver, timeout10, poll_frequency0.5) def find_element(self, locator): 查找单个元素加入显式等待 try: element self.wait.until(EC.presence_of_element_located(locator)) self.logger.info(f成功定位到元素: {locator}) return element except TimeoutException: self.logger.error(f定位元素超时: {locator}) raise def click_element(self, locator): 点击元素解决元素不可点击或遮挡问题 element self.find_element(locator) try: # 先滚动到元素可见区域 self.driver.execute_script(arguments[0].scrollIntoView({block: center});, element) # 等待元素可点击 clickable_element self.wait.until(EC.element_to_be_clickable(locator)) clickable_element.click() self.logger.info(f成功点击元素: {locator}) except Exception as e: self.logger.error(f点击元素失败 {locator}: {e}) # 可以尝试JavaScript直接点击作为备选方案 self.driver.execute_script(arguments[0].click();, element) def input_text(self, locator, text): 向输入框输入文本先清空原有内容 element self.find_element(locator) element.clear() element.send_keys(text) self.logger.info(f在元素 {locator} 中输入文本: {text}) def get_element_text(self, locator): 获取元素文本处理StaleElement异常 for i in range(3): # 重试机制 try: element self.find_element(locator) return element.text except StaleElementReferenceException: self.logger.warning(f元素 {locator} 状态过时第{i1}次重试...) continue raise StaleElementReferenceException(f无法获取元素 {locator} 的稳定文本) def is_element_visible(self, locator, timeout5): 判断元素是否在指定时间内可见 try: WebDriverWait(self.driver, timeout).until(EC.visibility_of_element_located(locator)) return True except TimeoutException: return False核心要点智能等待使用WebDriverWait配合expected_conditions进行显式等待这是解决因网络或JS加载导致元素找不到问题的最有效方法。隐式等待implicitly_wait作为全局兜底显式等待用于关键操作。操作增强click_element方法不仅等待可点击还先滚动到视图中心并提供了JS点击的备选方案极大提高了点击成功率。异常处理与重试在get_element_text中加入了针对StaleElementReferenceException元素状态过时的重试机制这是UI自动化中常见的“坑”。日志集成每个关键操作都记录日志方便调试和问题回溯。4.3 配置日志系统在utils/logger.py中配置一个灵活的日志系统。# utils/logger.py import logging import os from datetime import datetime def setup_logger(name__name__, log_levellogging.INFO): # 创建logger logger logging.getLogger(name) logger.setLevel(log_level) # 避免重复添加handler if logger.handlers: return logger # 创建控制台handler并设置级别 console_handler logging.StreamHandler() console_handler.setLevel(log_level) # 创建文件handler log_dir logs os.makedirs(log_dir, exist_okTrue) log_file os.path.join(log_dir, fautotest_{datetime.now().strftime(%Y%m%d)}.log) file_handler logging.FileHandler(log_file, encodingutf-8) file_handler.setLevel(logging.DEBUG) # 文件日志记录更详细 # 创建formatter并添加到handler formatter logging.Formatter(%(asctime)s - %(name)s - %(levelname)s - %(message)s) console_handler.setFormatter(formatter) file_handler.setFormatter(formatter) # 将handler添加到logger logger.addHandler(console_handler) logger.addHandler(file_handler) return logger # 在base_page.py中可以直接导入使用 # from utils.logger import setup_logger # self.logger setup_logger()5. 页面对象层实现以登录页面为例现在我们用POM模式来实现一个具体的页面。假设我们有一个简单的登录页面包含用户名输入框、密码输入框和登录按钮。首先在configs目录下创建一个config.yaml管理URL和浏览器类型。# configs/config.yaml base_url: https://www.example.com browser: chrome timeout: 10然后创建utils/config_reader.py来读取配置。# utils/config_reader.py import yaml import os def read_config(config_nameconfig.yaml): config_path os.path.join(os.path.dirname(__file__), .., configs, config_name) with open(config_path, r, encodingutf-8) as f: config yaml.safe_load(f) return config接下来创建登录页面对象类。我们将元素定位器定义为类属性清晰明了。# page_objects/login_page.py from selenium.webdriver.common.by import By from page_objects.base_page import BasePage from utils.config_reader import read_config class LoginPage(BasePage): # 1. 定义页面元素定位器元组形式便于维护 USERNAME_INPUT (By.ID, username) PASSWORD_INPUT (By.ID, password) LOGIN_BUTTON (By.XPATH, //button[typesubmit]) ERROR_MESSAGE (By.CLASS_NAME, alert-error) # 2. 页面URL可从配置读取 def __init__(self): super().__init__() config read_config() self.url config[base_url] /login # 假设登录页路径为 /login # 3. 页面操作方法 def open(self): 打开登录页面 self.driver.get(self.url) self.logger.info(f打开登录页面: {self.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) # 点击后通常页面会跳转可以返回下一个页面的对象这里先返回自身 # 实际项目中可以返回 HomePage 对象 from page_objects.home_page import HomePage return HomePage() def get_error_message(self): 获取错误提示信息登录失败时 if self.is_element_visible(self.ERROR_MESSAGE): return self.get_element_text(self.ERROR_MESSAGE) return None # 4. 完整的业务场景封装可选但推荐 def login(self, username, password): 完整的登录流程 self.open() self.enter_username(username) self.enter_password(password) return self.click_login()设计解析定位器集中管理所有元素定位器都在类顶部定义一目了然修改极其方便。方法返回自身或下一页像enter_username返回self支持链式调用如page.enter_username(...).enter_password(...).click_login()代码更流畅。click_login方法返回下一个页面的对象符合操作流。业务场景封装login方法封装了最常见的登录场景测试用例中一行代码即可完成登录极大简化了用例编写。6. 测试用例层与数据驱动实践有了稳定的页面对象编写测试用例就变成了组装乐高积木。我们使用pytest作为测试框架它比unittest更简洁强大。6.1 编写第一个测试用例在test_cases目录下创建test_login.py。# test_cases/test_login.py import pytest from page_objects.login_page import LoginPage from utils.logger import setup_logger logger setup_logger() class TestLogin: 登录功能测试类 pytest.fixture(autouseTrue) def setup_teardown(self): 每个测试方法前后执行用于初始化和清理示例 logger.info( 开始执行测试用例 ) yield # 这里可以做一些清理工作比如截图如果失败 logger.info( 测试用例执行结束 ) def test_login_success(self): 测试登录成功 login_page LoginPage() # 使用页面对象封装的业务方法 home_page login_page.login(usernamevalid_user, passwordvalid_pass) # 断言验证是否成功跳转到首页假设首页有欢迎语元素 # 这里需要你根据实际首页实现 HomePage 类和其验证方法 # assert home_page.is_welcome_message_displayed() # 我们先简单断言URL变化或页面标题 assert dashboard in login_page.driver.current_url.lower() logger.info(登录成功测试通过) def test_login_failure_with_wrong_password(self): 测试密码错误登录失败 login_page LoginPage() login_page.open() login_page.enter_username(valid_user) login_page.enter_password(wrong_pass) login_page.click_login() # 点击后仍停留在登录页 error_msg login_page.get_error_message() # 断言错误信息符合预期 assert error_msg is not None assert 密码错误 in error_msg or invalid in error_msg.lower() logger.info(密码错误登录失败测试通过)6.2 实现数据驱动测试硬编码的测试数据不利于维护和扩展。数据驱动测试DDT将测试数据从脚本中分离。我们可以使用pytest的pytest.mark.parametrize装饰器配合从外部文件如JSON, Excel读取的数据。首先在data/user_data.json中准备测试数据。// data/user_data.json [ { test_case: login_success, username: standard_user, password: secret_sauce, expected: success }, { test_case: login_locked_user, username: locked_out_user, password: secret_sauce, expected: error, error_msg_contains: locked out }, { test_case: login_wrong_password, username: standard_user, password: wrong, expected: error, error_msg_contains: do not match } ]然后创建一个数据读取工具utils/data_loader.py。# utils/data_loader.py import json import os import pandas as pd def load_json_data(file_name): file_path os.path.join(os.path.dirname(__file__), .., data, file_name) with open(file_path, r, encodingutf-8) as f: data json.load(f) return data def load_excel_data(file_name, sheet_name0): file_path os.path.join(os.path.dirname(__file__), .., data, file_name) df pd.read_excel(file_path, sheet_namesheet_name) # 将DataFrame转换为字典列表方便参数化 return df.to_dict(records)最后改造测试用例使用参数化驱动。# test_cases/test_login_ddt.py import pytest from page_objects.login_page import LoginPage from utils.data_loader import load_json_data # 从JSON文件加载测试数据 test_data load_json_data(user_data.json) class TestLoginDataDriven: 数据驱动登录测试 pytest.mark.parametrize(data, test_data, ids[item[test_case] for item in test_data]) def test_login_with_data(self, data): 使用参数化运行多组登录数据 login_page LoginPage() username data[username] password data[password] expected data[expected] login_page.open() login_page.enter_username(username) login_page.enter_password(password) login_page.click_login() if expected success: # 验证登录成功 assert inventory in login_page.driver.current_url.lower() # 假设成功跳转到商品列表页 elif expected error: # 验证登录失败并检查错误信息 error_msg login_page.get_error_message() assert error_msg is not None if error_msg_contains in data: assert data[error_msg_contains].lower() in error_msg.lower()运行测试在项目根目录下执行命令pytest test_cases/test_login_ddt.py -v。-v参数显示详细信息你会看到pytest为每一组数据生成并运行一个独立的测试用例报告清晰。7. 常见问题排查与实战技巧框架搭建和脚本编写过程中你会遇到各种各样的问题。这里记录一些高频“坑点”和解决技巧。7.1 元素定位失败问题排查表问题现象可能原因排查步骤与解决方案NoSuchElementException1. 定位器写错了。2. 页面尚未加载完成。3. 元素在iframe或shadow DOM内。4. 元素是动态生成的。1.检查定位器在浏览器开发者工具中CtrlF用XPath/CSS验证。2.增加等待使用WebDriverWait和EC.presence_of_element_located或EC.visibility_of_element_located。3.切换上下文使用driver.switch_to.frame()切入iframe对于Shadow DOM需通过JavaScript路径访问。4.使用更稳定的定位器优先使用ID、Name其次CSS Selector尽量避免绝对XPath。ElementNotInteractableException1. 元素被遮挡弹窗、其他元素。2. 元素不可见display:none或visibility:hidden。3. 元素未处于可交互状态如disabled。1.等待与滚动使用EC.element_to_be_clickable并先滚动到元素位置见BasePage.click_element。2.检查元素状态确保元素可见且启用。3.JS点击作为最后手段使用driver.execute_script(arguments[0].click();, element)。StaleElementReferenceException之前找到的元素因为页面刷新、AJAX更新或DOM重排而“过期”了。重新查找元素在操作元素前重新定位。可以在封装的方法中加入重试机制如我们BasePage.get_element_text所做。脚本在本地运行成功在服务器/CI上失败1. 浏览器版本/驱动版本不匹配。2. 无头模式或分辨率差异导致元素不可见。3. 环境网络或资源加载慢。1.使用webdriver-manager确保驱动自动匹配。2.配置无头模式选项添加--window-size1920,1080等参数。3.增加全局超时时间适当增加隐式等待和显式等待的超时参数。7.2 提升脚本稳定性的高级技巧使用相对定位和CSS SelectorXPath虽然强大但性能较差且易受页面结构微小变动影响。优先使用ID、Name其次使用CSS Selector。CSS Selector在大多数现代浏览器中解析速度更快。# 优于//div[idcontainer]/div[3]/button[2] SUBMIT_BTN (By.CSS_SELECTOR, #container div.button-group button.btn-primary)实现智能等待与重试机制对于某些不稳定操作如文件上传成功提示可以封装一个带重试的等待函数。def wait_for_condition_with_retry(self, condition_func, max_retries3, delay1): for i in range(max_retries): try: if condition_func(): return True except Exception: pass time.sleep(delay) return False页面加载状态判断对于单页应用SPA页面“加载完成”不等于“数据渲染完成”。可以通过等待特定元素出现、或检查JavaScript的document.readyState结合自定义条件来判断。def wait_for_page_loaded(self, timeout30): # 等待基础DOM就绪 WebDriverWait(self.driver, timeout).until( lambda d: d.execute_script(return document.readyState) complete ) # 额外等待关键组件出现 WebDriverWait(self.driver, timeout).until( EC.presence_of_element_located(self.PAGE_LOADED_INDICATOR) )测试失败自动截图在pytest的conftest.py中配置自动截图钩子这在CI/CD中排查问题非常有用。# test_cases/conftest.py import pytest from utils.driver_manager import driver_manager import os from datetime import datetime pytest.hookimpl(tryfirstTrue, hookwrapperTrue) def pytest_runtest_makereport(item, call): outcome yield rep outcome.get_result() if rep.when call and rep.failed: # 测试失败时截图 driver driver_manager.driver if driver: screenshot_dir reports/screenshots os.makedirs(screenshot_dir, exist_okTrue) timestamp datetime.now().strftime(%Y%m%d_%H%M%S) screenshot_path os.path.join(screenshot_dir, f{item.name}_{timestamp}.png) driver.save_screenshot(screenshot_path) print(f\n测试失败截图已保存至: {screenshot_path})7.3 框架的扩展方向这个基础框架已经具备了支撑中小型项目的核心能力。你可以根据实际需求进行扩展测试报告集成Allure或pytest-html生成美观的HTML测试报告。并发执行使用pytest-xdist插件实现测试用例并行运行大幅缩短执行时间。API与UI混合测试在utils层引入requests库对于某些前置条件如准备测试数据或后置验证直接调用API效率更高。持续集成将框架接入Jenkins、GitLab CI或GitHub Actions实现自动化触发、执行和报告通知。移动端与跨浏览器基础层可以扩展以支持Appium移动端或同时初始化多种浏览器驱动进行跨浏览器测试。搭建框架的过程是一个不断抽象、封装和优化的过程。最初的版本可能简陋但随着项目推进和问题积累你会不断回头重构和完善它。记住框架的目的是服务于高效、稳定的自动化测试而不是追求技术的复杂度。从这个小而美的框架开始逐步迭代让它成长为最适合你项目的那把“瑞士军刀”。
