1. 项目概述与核心价值最近在技术社区和招聘JD里“自动化测试”和“测试开发”这两个词出现的频率越来越高。很多刚入行的测试同学或者想从功能测试转型的朋友常常会问我一个很具体的问题“我知道PythonSelenium很火也想自己动手搭一个框架但面对一个空白项目第一步该从哪里开始是直接pip install selenium然后写个脚本吗” 这感觉就像你想盖一栋房子手里有砖头Python和水泥Selenium但不知道地基怎么打、图纸怎么画最后可能只能垒出一个摇摇欲坠的棚子。实际上从零开始设计一个自动化测试框架远不止是写几个能跑通的脚本。它更像是在搭建一个可持续运转的“测试工厂”。这个工厂需要有清晰的生产线测试流程、标准的零部件页面对象、数据、高效的质检员断言与报告以及灵活的调度系统用例管理与执行。盲目开始很容易陷入“脚本越写越乱、维护成本越来越高、最后推倒重来”的困境。这篇文章我就结合自己从零搭建过多个测试框架的经验拆解一下这个“从零到设计”的过程核心目标不是给你一个现成的框架代码而是给你一张清晰的“施工蓝图”和“避坑地图”让你知道每一步在做什么、为什么这么做以及可能会遇到哪些“坑”。2. 框架设计前的核心思路拆解2.1 明确目标你要解决什么问题在动手写第一行代码之前必须先想清楚框架要承载的使命。这决定了后续所有技术选型和架构设计的方向。通常一个自动化测试框架的目标可以归结为以下几类回归测试保障这是最常见的目标。每次发布新版本后需要快速、准确地执行大量已有的核心功能用例确保新代码没有破坏旧功能。为此框架需要高稳定性和高效的批量执行能力。冒烟测试/快速验证在每日构建或开发提交代码后快速执行一组最核心的流程验证系统基本可用。这要求框架执行速度要快用例集能够灵活组合和筛选。数据驱动测试针对同一业务流程需要使用多组不同的输入数据进行验证。框架需要能够方便地将测试数据与测试逻辑分离实现一套脚本覆盖多种场景。跨浏览器/跨环境兼容性测试确保Web应用在Chrome、Firefox、Edge等不同浏览器上表现一致。框架需要能方便地配置和切换不同的浏览器驱动及版本。注意不要贪心试图用一个框架解决所有问题。初期建议聚焦1-2个最紧迫的目标。例如先从“核心业务流程的回归测试”开始这样范围明确更容易快速出成果并建立信心。2.2 技术栈选型背后的逻辑标题已经锁定了“Python Selenium”这是一个非常经典且强大的组合。但为什么是它们我们简单拆解一下Python语法简洁学习曲线平缓拥有极其丰富的生态库如pytest,unittest,requests,openpyxl等非常适合测试这种需要快速实现、注重逻辑而非极致性能的场景。社区活跃遇到问题容易找到解决方案。Selenium它是Web自动化测试的“事实标准”。通过模拟真实用户操作浏览器能覆盖绝大部分前端交互测试。它的WebDriver协议是开放的得到了所有主流浏览器的官方支持兼容性和可持续性最好。但仅有它们俩还不够一个完整的框架还需要其他“配角”测试运行器pytestvsunittest。我强烈推荐pytest。原因在于它更灵活、功能更强大支持丰富的插件如生成HTML报告、控制用例执行顺序、分布式执行、更简洁的断言写法直接用assert、强大的Fixture机制用于测试前置和后置条件管理。unittest则更“学院派”风格固定。报告生成光测试不报告等于没测试。pytest-html、Allure是主流选择。pytest-html简单易用与pytest无缝集成。Allure则功能强大报告美观能展示用例层级、步骤详情、附件截图、日志但需要额外安装Java环境。根据团队需求选择。页面对象模型Page Object Model, POM这不是一个库而是一种设计模式。它的核心思想是将页面定位元素和页面操作方法封装成一个独立的类Page Object。测试脚本只调用这些方法不直接操作元素。这样做极大提高了代码的可维护性当页面UI变动时你只需要修改对应的Page Object类而不需要修改所有测试脚本。2.3 框架设计的基本原则在开始编码前心里要绷紧这几根弦它们是你做任何设计决策的准绳可维护性第一测试代码也是代码而且变更频率可能比业务代码还高。结构清晰、命名规范、避免重复是底线。POM模式就是为此而生。稳定性与容错UI自动化天生脆弱网络延迟、元素加载慢、弹窗干扰都会导致失败。框架必须内置等待机制显式等待、失败重试、自动截图等功能让用例不是“一碰就碎”。可读性与可协作性测试用例应该像文档一样能让其他同事甚至产品经理一眼看懂在测什么。这就要求用例步骤清晰、断言明确、数据与逻辑分离。易于集成框架应该能方便地集成到CI/CD流水线如Jenkins, GitLab CI中实现无人值守的自动化执行。3. 从零开始的详细目录结构与模块解析有了思路我们开始“打地基”——创建项目目录。一个结构清晰的项目根目录是框架可维护性的物理体现。下面是一个我常用的、经过实践检验的目录结构示例并解释每个文件夹的职责your_automation_framework/ │ ├── configs/ # 配置文件目录 │ ├── __init__.py │ ├── config.yaml (或 config.ini) # 主配置文件URL、超时时间、浏览器类型等 │ └── email_config.yaml # 邮件报告配置如果需要 │ ├── drivers/ # 浏览器驱动目录 │ ├── chromedriver (Linux/Mac) │ ├── chromedriver.exe (Windows) │ └── geckodriver (Firefox) │ ├── logs/ # 日志目录运行时自动生成 │ └── test_20231027.log │ ├── reports/ # 测试报告目录运行时自动生成 │ └── html_report_20231027.html │ ├── screenshots/ # 失败截图目录运行时自动生成 │ └── test_login_failed_202310271030.png │ ├── src/ # 框架核心源代码 │ ├── __init__.py │ ├── base/ # 基础层 │ │ ├── __init__.py │ │ ├── base_page.py # 所有Page Object的基类封装公共方法 │ │ └── webdriver_factory.py # 浏览器驱动工厂负责创建和销毁driver │ │ │ ├── pages/ # 页面对象层POM核心 │ │ ├── __init__.py │ │ ├── login_page.py # 登录页面 │ │ ├── home_page.py # 主页 │ │ └── ... (其他页面) │ │ │ ├── test_cases/ # 测试用例层 │ │ ├── __init__.py │ │ ├── conftest.py # pytest共享fixture配置 │ │ ├── test_login.py # 登录测试模块 │ │ └── ... (其他测试模块) │ │ │ ├── test_data/ # 测试数据层 │ │ ├── __init__.py │ │ ├── login_data.yaml (或 .json, .csv) # 登录测试数据 │ │ └── ... (其他数据文件) │ │ │ └── utils/ # 工具层 │ ├── __init__.py │ ├── logger.py # 日志记录工具 │ ├── file_reader.py # 文件读取工具读YAML, JSON, Excel │ └── common_actions.py # 通用操作封装如滚动、切换窗口 │ ├── requirements.txt # Python依赖包列表 └── README.md # 项目说明文档3.1 核心模块职责详解configs/存放所有配置文件。使用YAML或INI格式因为它们比Python脚本更易于阅读和修改非技术参数如URL、超时时间。通过一个配置管理类来统一读取避免在代码中硬编码。drivers/存放不同操作系统下的浏览器驱动。建议将驱动路径加入系统环境变量或者在代码中指定绝对路径。重要提示驱动版本必须与本地安装的浏览器版本匹配否则Selenium无法工作。可以编写一个初始化脚本自动检查并下载匹配的驱动。src/base/这是框架的“基石”。base_page.py所有具体页面类如LoginPage的父类。它里面应该封装所有页面对象共用的方法比如find_element增强查找内置显式等待、click、input_text、get_text、take_screenshot等。这样具体页面类只需关心自己特有的元素和操作公共逻辑都在基类里符合DRYDon‘t Repeat Yourself原则。webdriver_factory.py采用工厂模式来创建WebDriver实例。根据配置文件中的browser_typechrome, firefox, edge来实例化对应的驱动并统一设置选项如无头模式、窗口大小、禁用沙盒等。它还可以结合pytest的fixture确保每个测试用例结束后正确退出driver避免资源泄露。src/pages/POM模式的核心。每个页面一个Python文件每个文件里定义一个类。这个类包含元素定位器以元组形式存储如username_input (By.ID, “username”)。页面操作方法如login(username, password)方法内部调用从base_page继承来的公共方法操作上述元素。页面专属断言如check_login_success()用于验证是否成功跳转到目标页面。src/test_cases/存放真正的测试用例。用例文件以test_开头用例函数也以test_开头这是pytest的约定。用例函数应该非常简洁基本上就是调用不同Page对象的方法组成业务流然后进行断言。理想情况下一个测试函数不应该出现find_element、click这类底层Selenium API调用。src/test_data/存放外部测试数据。将数据从脚本中分离出来是数据驱动测试的关键。可以用YAML、JSON、CSV甚至Excel。YAML可读性好适合结构化数据CSV适合表格数据。编写一个数据读取工具在utils里在用例中加载使用。src/utils/工具箱。把常用的、与具体业务无关的功能封装在这里比如写日志、读取各种格式的文件、发送邮件、生成随机数据、处理日期等。4. 核心环节的逐步实现与编码实战4.1 第一步环境搭建与依赖管理首先创建一个干净的虚拟环境并安装核心依赖。这是保证项目环境隔离、可复现的第一步。# 1. 创建项目目录并进入 mkdir your_automation_framework cd your_automation_framework # 2. 创建虚拟环境Python 3.6 python -m venv venv # 3. 激活虚拟环境 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 4. 创建requirements.txt文件并写入核心依赖 # requirements.txt 内容示例 # selenium4.0.0 # pytest7.0.0 # pytest-html3.0.0 # pytest-rerunfailures10.0 # 失败重试插件 # PyYAML6.0 # 读写YAML配置文件 # allure-pytest2.9.0 # 如果使用Allure报告 # openpyxl3.0.0 # 如果读写Excel # 5. 安装依赖 pip install -r requirements.txt # 6. 根据config.yaml中配置的浏览器手动下载对应版本的驱动放到drivers/目录下。 # 或者可以使用webdriver-manager库自动管理驱动pip install webdriver-manager。4.2 第二步编写基础层Base代码这是框架最关键的抽象层。我们先实现webdriver_factory.py。# src/base/webdriver_factory.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 import os class WebDriverFactory: WebDriver工厂类负责创建和配置浏览器实例 def __init__(self, browserchrome, headlessFalse): self.browser browser.lower() self.headless headless def create_driver(self): 根据配置创建并返回WebDriver实例 driver None if self.browser chrome: options webdriver.ChromeOptions() if self.headless: options.add_argument(--headlessnew) # Selenium 4.11 推荐写法 options.add_argument(--no-sandbox) options.add_argument(--disable-dev-shm-usage) options.add_argument(--window-size1920,1080) # 禁用“Chrome正受到自动测试软件控制”的提示 options.add_experimental_option(excludeSwitches, [enable-automation]) options.add_experimental_option(useAutomationExtension, False) # 方式一使用webdriver-manager自动管理驱动推荐避免版本问题 service ChromeService(ChromeDriverManager().install()) driver webdriver.Chrome(serviceservice, optionsoptions) # 方式二使用本地drivers目录下的驱动 # driver_path os.path.join(os.path.dirname(__file__), ../../drivers/chromedriver) # service ChromeService(executable_pathdriver_path) # driver webdriver.Chrome(serviceservice, optionsoptions) elif self.browser firefox: options webdriver.FirefoxOptions() if self.headless: options.add_argument(--headless) # ... 其他Firefox配置 service FirefoxService(GeckoDriverManager().install()) driver webdriver.Firefox(serviceservice, optionsoptions) else: raise ValueError(fUnsupported browser: {self.browser}) # 设置全局隐式等待备用主要用显式等待 driver.implicitly_wait(10) # 最大化窗口非无头模式时 if not self.headless: driver.maximize_window() return driver接下来实现base_page.py。这里封装了最重要的“智能等待”和元素操作。# src/base/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 import logging import os class BasePage: 所有Page Object的基类 def __init__(self, driver): self.driver driver self.logger logging.getLogger(__name__) self.timeout 30 # 显式等待超时时间 def find_element(self, locator, timeoutNone): 查找单个元素内置显式等待。 :param locator: 定位器元组如 (By.ID, username) :param timeout: 等待超时时间默认使用类属性timeout :return: WebElement对象 wait_time timeout or self.timeout try: # 等待元素可见且可交互 element WebDriverWait(self.driver, wait_time).until( EC.visibility_of_element_located(locator) ) self.logger.debug(f成功定位到元素: {locator}) return element except TimeoutException: self.logger.error(f定位元素超时: {locator}) # 失败时自动截图便于排查 self._take_screenshot(element_not_found) raise def click(self, locator, timeoutNone): 点击元素 element self.find_element(locator, timeout) try: element.click() self.logger.info(f点击元素: {locator}) except Exception as e: self.logger.error(f点击元素失败 {locator}: {e}) raise def input_text(self, locator, text, timeoutNone): 向输入框输入文本先清空原有内容 element self.find_element(locator, timeout) try: element.clear() element.send_keys(text) self.logger.info(f在元素 {locator} 中输入文本: {text}) except Exception as e: self.logger.error(f输入文本失败 {locator}: {e}) raise def get_text(self, locator, timeoutNone): 获取元素的文本内容 element self.find_element(locator, timeout) try: text element.text self.logger.info(f获取元素 {locator} 的文本: {text}) return text except Exception as e: self.logger.error(f获取文本失败 {locator}: {e}) raise def _take_screenshot(self, name): 内部方法截图并保存到screenshots目录 screenshots_dir os.path.join(os.path.dirname(__file__), ../../screenshots) os.makedirs(screenshots_dir, exist_okTrue) from datetime import datetime timestamp datetime.now().strftime(%Y%m%d_%H%M%S) filename f{name}_{timestamp}.png filepath os.path.join(screenshots_dir, filename) self.driver.save_screenshot(filepath) self.logger.info(f截图已保存至: {filepath}) return filepath4.3 第三步实现页面对象层POM以登录页面为例展示如何将页面封装成类。# src/pages/login_page.py from selenium.webdriver.common.by import By from src.base.base_page import BasePage class LoginPage(BasePage): 登录页面对象模型 # 页面元素定位器 USERNAME_INPUT (By.ID, username) PASSWORD_INPUT (By.ID, password) LOGIN_BUTTON (By.XPATH, //button[typesubmit]) ERROR_MESSAGE (By.CLASS_NAME, alert-error) SUCCESS_INDICATOR (By.ID, welcome-message) # 登录成功后的页面元素 def __init__(self, driver): super().__init__(driver) # 可以在这里添加页面特定的初始化比如访问登录页URL # self.driver.get(https://example.com/login) def login(self, username, password): 登录操作输入用户名、密码并点击登录 self.logger.info(f尝试登录用户名: {username}) self.input_text(self.USERNAME_INPUT, username) self.input_text(self.PASSWORD_INPUT, password) self.click(self.LOGIN_BUTTON) def get_error_message(self): 获取登录失败后的错误提示信息 try: # 错误信息可能不会立即出现稍作等待 return self.get_text(self.ERROR_MESSAGE, timeout5) except Exception: return None def is_login_successful(self): 判断是否登录成功通过检查成功后的页面元素是否存在 try: # 等待成功元素出现 self.find_element(self.SUCCESS_INDICATOR, timeout10) return True except TimeoutException: return False4.4 第四步编写测试用例与pytest Fixture使用pytest来组织用例。首先创建共享的fixture用于管理driver的生命周期。# src/test_cases/conftest.py import pytest from src.base.webdriver_factory import WebDriverFactory pytest.fixture(scopefunction) # 每个测试函数执行一次 def driver(request): 提供WebDriver实例的fixture # 可以从命令行参数或配置文件读取浏览器类型 browser request.config.getoption(--browser) or chrome headless request.config.getoption(--headless) or False factory WebDriverFactory(browserbrowser, headlessheadless) driver_instance factory.create_driver() # 测试函数执行前可以在这里做一些全局设置比如访问首页 # driver_instance.get(https://example.com) yield driver_instance # 将driver传递给测试函数 # 测试函数执行后无论成功失败都退出浏览器 driver_instance.quit() # 添加命令行选项 def pytest_addoption(parser): parser.addoption(--browser, actionstore, defaultchrome, help指定浏览器: chrome 或 firefox) parser.addoption(--headless, actionstore_true, defaultFalse, help是否启用无头模式)然后编写一个具体的测试用例文件。# src/test_cases/test_login.py import pytest import allure from src.pages.login_page import LoginPage # 假设我们有一个数据读取工具 from src.utils.file_reader import read_yaml # 从YAML文件读取测试数据 test_data read_yaml(src/test_data/login_data.yaml) class TestLogin: 登录功能测试集 allure.story(用户登录功能) allure.title(使用有效凭证登录成功) pytest.mark.parametrize(data, test_data[valid_credentials]) def test_login_success(self, driver, data): 测试正常登录流程 with allure.step(1. 打开登录页面): driver.get(https://example.com/login) login_page LoginPage(driver) with allure.step(f2. 输入用户名: {data[username]} 和密码): login_page.login(data[username], data[password]) with allure.step(3. 验证登录成功): assert login_page.is_login_successful() is True, 登录成功后未跳转到正确页面 # 可以进一步断言页面上的欢迎信息 welcome_text login_page.get_text(login_page.SUCCESS_INDICATOR) assert data[username] in welcome_text, f欢迎信息中未包含用户名 {data[username]} allure.story(用户登录功能) allure.title(使用无效密码登录失败) def test_login_failure_wrong_password(self, driver): 测试密码错误登录失败 login_page LoginPage(driver) driver.get(https://example.com/login) login_page.login(correct_user, wrong_password) # 验证出现了错误提示 error_msg login_page.get_error_message() assert error_msg is not None, 密码错误时未显示错误提示 assert 密码错误 in error_msg or invalid in error_msg.lower(), f错误提示信息不符: {error_msg} allure.story(用户登录功能) allure.title(用户名为空时登录失败) def test_login_failure_empty_username(self, driver): 测试用户名为空时的客户端验证 login_page LoginPage(driver) driver.get(https://example.com/login) # 不输入用户名直接输入密码并点击登录 login_page.input_text(login_page.PASSWORD_INPUT, somepassword) login_page.click(login_page.LOGIN_BUTTON) # 这里假设前端有JS验证可能会在输入框附近显示提示 # 我们需要定位那个提示元素。为了示例我们假设提示是通过title属性或相邻span显示 # 实际项目中需要根据页面具体实现来定位和断言 # 例如error_span login_page.find_element((By.XPATH, //input[idusername]/following-sibling::span[classerror])) # assert error_span.text 用户名不能为空 # 本例中我们简单检查页面URL未变化未提交 assert login in driver.current_url, 用户名为空时页面不应跳转对应的测试数据文件login_data.yaml# src/test_data/login_data.yaml valid_credentials: - username: admin password: admin123 expected_welcome: Welcome, admin - username: test_user password: Test123 expected_welcome: Welcome, test_user invalid_credentials: - username: locked_user password: anypassword expected_error: 用户已被锁定4.5 第五步配置与执行创建主配置文件config.yaml# configs/config.yaml base: url: https://example.com timeout: 30 browser: name: chrome headless: false implicit_wait: 10 paths: drivers: ./drivers screenshots: ./screenshots reports: ./reports logs: ./logs test: retry_times: 2 # 失败重试次数 max_failures: 5 # 最多允许失败数最后通过命令行执行测试并生成报告# 激活虚拟环境后在项目根目录执行 # 1. 运行所有测试生成pytest-html报告 pytest src/test_cases/ -v --htmlreports/report.html --self-contained-html # 2. 运行指定标记的测试如冒烟测试 pytest src/test_cases/ -m smoke -v # 3. 运行测试并失败重试2次 pytest src/test_cases/ --reruns 2 --reruns-delay 1 -v # 4. 使用Allure报告需要先安装Allure命令行工具 pytest src/test_cases/ --alluredir./reports/allure_results allure serve ./reports/allure_results # 生成并打开本地报告5. 常见问题、排查技巧与避坑指南实录在实际搭建和运行过程中你一定会遇到各种各样的问题。下面是我踩过的一些“坑”以及解决方法。5.1 元素定位失败自动化测试的头号杀手问题现象NoSuchElementException,ElementNotVisibleException,StaleElementReferenceException。根本原因与解决方案等待不充分页面或元素尚未加载完成就进行操作。解决方案永远优先使用显式等待WebDriverWait就像我们在BasePage.find_element里做的那样。隐式等待implicitly_wait是全局的、被动的对于动态加载的元素往往不可靠。显式等待可以针对特定条件如元素可见、可点击、存在进行等待。技巧为不同的操作设置合理的超时时间。对于主要操作可以用默认的30秒对于判断元素是否消失如下拉框关闭可以设置较短的超时如5秒。定位器不稳定使用了容易变化的ID、Class或XPath。解决方案优先级ID name CSS Selector XPath。ID通常是唯一且最稳定的。避免绝对XPath绝对XPath以/html/body/div[1]/...开头极其脆弱页面结构微调就会失效。使用相对XPath如//button[idsubmit]或CSS Selector。与开发约定在项目初期可以和前端开发沟通为关键测试元素添加稳定的>
