软件测试自动化框架设计：接口与UI自动化分层落地的完整实践指南

简介：一套基于 Python + unittest 构建的软件测试自动化框架，同时覆盖 Web UI 自动化与接口自动化，面向中高级测试开发工程师。框架采用 PO 模式与数据驱动思想：通过 Selenium 驱动浏览器完成页面对象封装，通过 Requests 实现接口请求与断言，并预留移动端自动化扩展点，适合作为团队统一测试基座或个人学习实例。资源共 62 个文件，压缩包 78KB，以 Python 源码（py/pyc）为主体，另有 XML、INI 配置文件、Excel 测试数据、HTML 测试报告及 TXT 依赖说明，目录按 Page、TestCase、API、公共组件等模块分层，便于按需裁剪复用。核心价值在于提供从页面操作、接口封装到日志、邮件、数据比对、配置读取的完整链路，测试脚本与数据分离，可直接替换业务参数投入实际项目。目前已有 4942 人学习下载，适合希望系统掌握框架设计、减少重复开发的测试团队参考。

1. 软件测试自动化框架，到底在解决什么：先分清两层再动手

软件测试自动化框架，是团队从“手工点点点”走向“回归靠机器”时绕不开的一层地基。它要解决的两件事，恰好就是标题里写明的：Web UI自动化和接口自动化。但这两个东西的难度、稳定性和适用场景完全是两个量级——接口自动化跑得再快，也替代不了UI层对真实链路的验证；UI自动化做得再炫，也掩盖不了它天生脆弱的本质。

所以我建议先把框架拆成两层来看：一层是“对业务规则的校验”，数据、状态、逻辑大部分靠接口层搞定；另一层是“对用户可见行为的验证”，页面渲染、交互、异常提示这些只能靠UI层覆盖。框架设计的第一步不是选工具，而是想清楚这两层分别承担什么职责、各自在什么时机跑、失败时谁能更快定位问题。

这篇文章会从接口自动化讲起，因为它成本最低、收益最直接，然后展开Web UI自动化的选型与稳定性设计，最后给出一个两层统一的框架落地路径。适合正在从手工测试转向自动化、或者脚本写了一大堆却越来越难维护的团队。

2. 接口自动化先行：用 pytest + requests 把用例组织成可复用框架

2.1 为什么先做接口层：投入产出比最高的切入点

接口自动化几乎是所有自动化改造里最先落地的部分。原因不复杂：接口足够稳定，业务逻辑在这里暴露得最充分，而且执行速度快、环境依赖少，跑一次全量用例通常几分钟就完。这个阶段的产出不仅是一个测试脚本集，更是一套对业务数据流和状态流转的完整描述。

常见的实现方案是围绕两个库搭建：pytest作为用例组织和执行引擎，requests负责发送HTTP请求。pytest的优势不在于它比unittest多多少功能，而在于它的fixture机制和插件生态，天然适合做数据共享、环境切换和报告输出。requests就不用多说了，几乎所有Python体系的接口测试项目都以它为基础。

我一般落地的时候会把一套接口自动化拆成四层：配置层、公共请求层、用例层、数据层。配置层放环境地址和账号信息，公共请求层统一处理请求头、Token刷新、日志记录，用例层只写业务场景和断言，数据层用YAML或JSON存放用例输入和预期结果。这样分完，新增一个接口用例基本上不需要动公共代码。

2.2 最小可运行的工程骨架：从目录到请求封装

先看一个能跑起来的目录结构，这个结构不花哨，但足够撑起后续扩展：

api_test/ ├── config/ │ ├── __init__.py │ └── settings.py # 环境地址、超时、数据库连接等 ├── common/ │ ├── __init__.py │ ├── request_client.py # requests会话封装 │ ├── assert_utils.py # 断言工具 │ └── logger.py # 日志封装 ├── testcases/ │ ├── __init__.py │ ├── conftest.py # pytest fixtures │ ├── test_login.py │ └── test_order.py ├── data/ │ ├── login_cases.yaml │ └── order_cases.yaml └── reports/

关键在request_client.py。如果不做封装，每个用例里都写一遍requests.get或requests.post，一旦需要统一处理Token失效重登、统计请求耗时、记录返回报文，就要改所有用例文件。封装之后这些逻辑集中在一处：

import requests import time import logging logger = logging.getLogger("api_client") class RequestClient: def __init__(self, base_url, token=None): self.base_url = base_url self.session = requests.Session() if token: self.session.headers.update({"Authorization": f"Bearer {token}"}) def request(self, method, path, **kwargs): url = self.base_url + path start_time = time.time() # 统一在这里捕获异常并记录，避免用例层被网络错误打散 try: resp = self.session.request(method, url, timeout=10, **kwargs) logger.info(f"{method} {url} -> {resp.status_code} 耗时 {time.time() - start_time:.2f}s") return resp except requests.exceptions.Timeout: logger.error(f"{method} {url} 请求超时") raise except requests.exceptions.ConnectionError: logger.error(f"{method} {url} 连接失败，请确认服务是否可用") raise def get(self, path, **kwargs): return self.request("GET", path, **kwargs) def post(self, path, **kwargs): return self.request("POST", path, **kwargs)

这个封装的思路是把所有请求统一收口。timeout统一设置为10秒，防止某个接口偶发卡住把整个测试套件拖死；异常在这里做一层转换并把上下文日志打全，用例层拿到的就是明确的失败信息，而不是一长串traceback。后续如果要加失败重试、上报测试平台，全都改这一个文件就行。

2.3 用例怎么设计才能不沦为“脚本堆”：数据驱动与分层断言

接口用例最容易犯的毛病是每个用例都是独立脚本，各写各的循环和判断。结果用例越来越多，维护成本越来越高，最后自动化变成了负担。要避免这个陷阱，核心手段是数据驱动：把输入和预期从代码里挪到数据文件里，用例代码只保留执行逻辑和断言逻辑。

举个例子，登录接口的用例数据可以写成YAML：

# data/login_cases.yaml - name: 正常登录 username: "valid_user" password: "valid_pass" expect_code: 0 expect_msg: "success" - name: 密码错误 username: "valid_user" password: "wrong_pass" expect_code: 1001 expect_msg: "用户名或密码错误" - name: 账号不存在 username: "no_such_user" password: "whatever" expect_code: 1002 expect_msg: "账号不存在"

对应的用例代码只需要一个参数化函数：

import pytest import yaml from common.request_client import RequestClient from common.assert_utils import assert_response with open("data/login_cases.yaml", encoding="utf-8") as f: login_cases = yaml.safe_load(f) @pytest.mark.parametrize("case", login_cases, ids=[c["name"] for c in login_cases]) def test_login(case, client): resp = client.post("/api/login", json={ "username": case["username"], "password": case["password"] }) assert_response(resp, case["expect_code"], case["expect_msg"])

逻辑说明：通过parametrize把YAML里每条数据生成一个独立的测试用例，ids参数让失败用例的名称直接显示中文字段名，一眼就能看出是哪种场景挂了。新增用例不写代码，只往YAML里加一条记录。这里注意conftest.py里需要定义client这个fixture，返回一个已经初始化好的RequestClient实例，这样用例层完全不感知环境切换。

断言这块也值得多说一句。很多项目断言只看HTTP状态码等于200，这是远远不够的。返回200只能说明服务端处理了这个请求，业务是否成功取决于响应体里的业务码和数据内容。所以assert_response要同时校验状态码和业务字段，常见做法是支持预期code、预期message、以及可选的JSONPath提取值校验。

3. Web UI自动化怎么做才稳：从Selenium到Playwright的选择与实战

3.1 选型对比：Selenium还是Playwright

Web UI自动化第一个要做的决定是选型。当前主流的两个方向是Selenium和Playwright，也有人用Cypress，但Cypress的定位更偏向前端测试，受限于必须在浏览器里跑，不适合做跨域和复杂多标签场景。真正在测试团队里大规模落地，绝大多数选的是Selenium和Playwright二选一。

Selenium是老牌选手，生态成熟，资料多，几乎任何浏览器都能驱动，坑也基本被前人踩平了。但它的劣势很明显：需要额外维护driver（chromedriver、geckodriver等），浏览器升级稍不注意就报版本不匹配；内置等待只有sleep和显式等待，脚本不稳定时排查成本高。Playwright是后起之秀，由微软维护，核心优势有三条：无需单独安装driver，npm或pip安装时自动下载对应浏览器内核；自带auto-wait机制，元素稳定后才会操作，大量减少了sleep；支持trace viewer和video录制，失败排查直观得多。

从我的经验看，新项目直接上Playwright是更划算的选择。如果团队对Selenium非常熟、代码资产都在，不必要推倒重来；但如果是空白起步或者准备重构，Playwright的学习曲线比想象中平滑。

3.2 用Playwright落地一套最小可运行的UI用例

先看最基础的安装和启动：

pip install playwright playwright install chromium

install chromium这一步会下载浏览器内核，放在用户目录下的缓存里，不需要系统安装Chrome。下载缓慢的话建议配置镜像环境变量：PLAYWRIGHT_DOWNLOAD_HOST。这里要注意团队CI环境也要执行同样步骤，否则一换机器就跑不起来。

下面是一段完整的用例代码，覆盖打开页面、操作元素、断言三个动作：

import re from playwright.sync_api import sync_playwright, expect def test_user_login_flow(): with sync_playwright() as p: browser = p.chromium.launch(headless=True) page = browser.new_page() page.goto("https://example.com/login", wait_until="networkidle") page.get_by_label("用户名").fill("test_user") page.get_by_label("密码").fill("test_pass") page.get_by_role("button", name="登录").click() # auto-wait会等到元素可交互，这一步不需要显式sleep expect(page).to_have_url(re.compile(r"/dashboard")) assert page.get_by_text("欢迎回来").is_visible() browser.close()

逻辑说明：launch里的headless=True表示无头模式，CI环境必须用这个参数，但本地调试建议改成False，能直观看到每一步操作。get_by_label和get_by_role是Playwright推荐的定位方式，相比css/xpath，它们更接近用户视角，页面结构变了但语义没变时用例依然稳定。expect断言内置自动重试机制，默认5秒内持续检查条件直到满足或超时。

3.3 元素定位的稳定策略：为什么不要盲写CSS选择器

UI自动化翻车最多的原因就是定位不稳定。前端稍微改个class名、加一层div，CSS选择器就失效了。所以要有一套定位优先级：用户可感知的文本和角色优先，id次之，data-testid再次之，CSS和XPath放最后。

常见做法是在测试环境约定前端必须给关键交互元素加data-testid属性。这不是测试单方面的需求，而是把可测试性写进前端开发的验收标准里。有了data-testid，哪怕文案和结构都变了，用例照样能跑。项目里如果前端配合度不高，至少要保证所有页面入口和表单控件有稳定的id或name属性。

另一个稳定性的关键是等待策略。新手最容易犯的错是一路sleep，跑起来慢，而且sleep时间短了不稳、长了浪费时间。Playwright的auto-wait机制已经解决了大部分等待问题，但有一些场景需要显式处理：比如某个元素在DOM里存在但不可见，或者某个操作触发了异步请求需要等数据回填。这时候用expect进行状态断言，让它来做轮询等待，而不是自己写time.sleep。

3.4 无头模式与有头模式：本地调试和CI跑法不能同一套配置

无头模式（headless）是CI环境里的唯一选择，因为没有显示器也没有交互桌面。但本地调试时如果也用无头模式，定位失败就只能看截图和trace，效率很低。所以我建议把运行模式做成可配置的，而不是写死。

常见的做法是用环境变量控制：

import os from playwright.sync_api import sync_playwright headless = os.getenv("UI_HEADLESS", "true").lower() == "true" with sync_playwright() as p: browser = p.chromium.launch(headless=headless) page = browser.new_page(viewport={"width": 1920, "height": 1080})

本地跑的时候设置UI_HEADLESS=false，浏览器窗口会弹出来，每一步操作肉眼可见，定位不对当场就能发现。跑CI的时候不设置这个变量，默认就是无头。另外viewport统一设置成1920x1080，避免因为窗口尺寸差异导致响应式布局把按钮挤到不可见的位置。

4. 把Web UI和接口自动化收进同一套框架：分层设计与统一配置

4.1 为什么要统一框架而不是两个独立项目

很多团队接口自动化是一套代码，UI自动化是另一套代码，各跑各的，报告也分开看。短期内没什么问题，时间一长就会遇到两个麻烦：一是公共能力重复建设，比如报告生成、日志收集、环境配置、结果通知，两套系统要做两遍；二是业务关联性没法体现，接口层的某个失败明明可能就是UI层某个用例失败的根因，但因为报告分离，排查时要人工去两个系统里找。

统一框架并不是说要在一个进程里跑接口和UI用例，而是共用同一套配置管理、同一套公共库、同一个报告输出体系。执行器可以分开，但底层和产物是统一的。

4.2 分层设计：接口、UI、公共能力各占一层

整个框架我从上到下分成三层：用例层、领域层、基础层。

用例层就是testcases目录下的各个测试文件，接口用例和UI用例分别放在api和ui两个子目录下。领域层封装业务操作，比如“创建订单”“登录用户”，接口测试里一个领域函数就是一个API调用组合，UI测试里一个领域函数就是一组页面操作序列。基础层是配置读取、请求封装、浏览器驱动、报告writer、日志工具这些公共服务。

这样做的好处是：当业务操作发生变化时，用例层和基础层都不动，只改动领域层；当公共能力升级时，比如切换报告模板，基础层改动也不影响用例层。所有代码都是单向依赖，避免了下游用例直接耦合某个requests.Session或某个Playwright页面实例。

4.3 统一配置管理：一份配置驱动两个执行端

环境切换是框架里最容易乱的东西。接口测试要base_url和数据库连接信息，UI测试要base_url和账号密码，这些在不同环境（dev/test/staging）下都不相同。我见过最糟糕的写法是把这些信息写死在用例文件里，换环境要全文搜索替换。

统一的做法是引入一个配置目录，按环境分文件，运行时根据环境变量加载：

# config/settings.py import os import yaml ENV = os.getenv("AUTO_TEST_ENV", "test").lower() class Config: def __init__(self, env): with open(f"config/{env}.yaml", encoding="utf-8") as f: data = yaml.safe_load(f) self.base_url = data["base_url"] self.api = data["api"] self.ui = data["ui"] self.db = data.get("db", {}) config = Config(ENV)

对应的配置文件test.yaml大致长这样：

base_url: "http://test.example.com" api: login_path: "/api/login" order_path: "/api/order" ui: login_url: "/login" username: "test_user" password: "test_pass" db: host: "10.0.0.5" port: 3306

用的时候只要设置环境变量AUTO_TEST_ENV=staging，整个框架就切换到预发环境的配置。每次跑测试前，报告里自动带上当前ENV信息，排查问题的时候就不会搞混。这里需要提醒一点：配置文件里的敏感信息，比如数据库密码，不要直接提交到仓库。常见做法是用本地环境变量再覆盖一层，配置文件里只放非敏感项或者占位符。

4.4 报告和日志的整合：让接口失败帮UI定位问题

统一框架最有价值的产出就是一份合并报告。接口用例失败和UI用例失败在同一个报告里按业务模块聚合，看报告的人能直接看到“这个模块的接口挂了，UI失败大概率是同一个根因”，不用等测试人员去翻日志。

实现上其实不复杂：接口用例和UI用例都是pytest用例，只是执行目录不同。用pytest自带的junitxml或者接入allure，把两个目录的用例统一收集、统一出报告。我一般配置pytest.ini指定testpaths为testcases/api和testcases/ui，跑一次就是全量。

日志系统也要统一。之前的RequestClient里已经有了requests的耗时和状态记录，UI层同样在浏览器操作的关键节点打日志：导航到哪个URL、点击了哪个按钮、断言了什么内容。报告负责展示“出了什么问题”，日志负责回答“当时到底发生了什么”，两者配合才能高效定位。

5. 自动化框架落地避坑：5个最常见的翻车现场

5.1 接口断言只查状态码，业务错误漏到线上

现象：接口自动化跑得全绿，线上却出了事故。事后一查，某个接口在返回200的同时返回了一个业务错误码，比如“库存不足”，但因为断言只写了assert resp.status_code == 200，这个问题根本没被拦住。

原因：测试设计时偷懒，只校验了传输层状态，没有校验业务状态。根因是对接口自动化的定位理解不到位——它检测的不是“服务有没有响应”，而是“业务是否符合预期”。

解决：断言必须覆盖业务码和关键数据字段。在AssertUtils里增加字段匹配逻辑，允许对JSON嵌套字段做路径提取和值比对。数据驱动的用例里，每条用例数据必须带上预期的业务code，必要时带预期数据库变更结果。

5.2 UI用例本地能过，CI上玄学失败

现象：同一个用例，本地跑十次过十次，推到CI上三天两头挂，而且挂在不同的位置。

原因：环境差异导致的不稳定，主要来源是执行速度不同。本地是人操作电脑，宿主CPU负载低；CI上并发跑任务，CPU调度慢，页面加载和动画特效的时序全变了，等待时间不够就操作了还不存在的元素。

解决：全面依赖auto-wait而不是固定sleep。对每个弹窗动画和异步加载区域，用expect进行可见性和可用性断言，让框架自己去等。如果用了Selenium，要把所有显式等待改成WebDriverWait配合expected_conditions，禁止裸sleep。另外CI上建议限制浏览器并发数，我一般控制在并行2到3个browser实例以内。

5.3 用例数据和业务数据耦合，跑一次就不能重跑

现象：用例第一次跑通过，第二次跑同一个用例就失败。细看是因为用例创建了一个订单，第二次执行时同样的订单号已经存在，数据库唯一约束拦住了。

原因：没有做测试数据隔离。接口用例直接用了生产或共享环境里的业务数据，既没有造数也没有清理，测试执行之间互相污染。

解决：每个用例的数据必须是独立的。常见做法是用例里动态生成唯一前缀，比如订单号用时间戳加随机数；更规范的做法是接一个造数服务或者测试库，用例结束后在teardown里清理。对于UI用例，至少要确保每次跑之前重置数据库或使用独立的测试账号，避免用户状态互相干扰。

5.4 没有失败重试机制，半夜告警炸群

现象：CI半夜定时跑回归，一个网络抖动的瞬时错误导致某条用例失败，整个pipeline标记失败，告警通知发到了整个测试群和研发群。

原因：把偶发基础设施抖动当成了测试结论。自动化框架缺少“快速失败”和“重试”的区分：重试机制能过滤偶发问题，只有重试后依然失败才需要走告警。

解决：pytest里用pytest-rerunfailures插件，对UI用例设置reruns=1或2，接口用例可以设0或1。重试要谨慎——如果业务本身不允许重复执行，比如支付场景，重试会造成重复扣款。这类用例要显式标记为不重试，或者重试策略放在更细粒度的错误类型上，比如只有超时和连接错误才重试。

5.5 环境配置散落在代码和全局变量里，换个人就跑不起来

现象：新同事拉下代码后跑测试，报错说找不到数据库连接。查了半天发现是上个同事在本地环境变量里设置了一堆东西，代码里压根没有默认值，也没写文档。

原因：配置没有规范化。环境依赖全部隐式地依赖了个人电脑上的设置，而不是跟着代码走。

解决：统一配置文件或者.env文件，提交一份示例文件到仓库，真实配置通过环境变量注入。至少保证“新环境按文档能20分钟内跑起来”这个下限。我一般在README里放一个checklist：安装依赖、设置环境变量、初始化浏览器内核、跑冒烟用例，四条全过再开始开发用例，避免把环境问题混进测试问题里。

6. 从能跑到跑得稳：把框架接进持续集成的一件关键事

框架能跑只是起点，真正让它产生价值的是接进持续集成流程里，在每次代码合并之前自动执行，在每次深夜回归之后输出一份可信的报告。这里只说一件我在落地过程中被反复教育的事：报告的可读性决定了自动化框架的寿命。

技术上的做法很具体：接入Allure，给接口用例和UI用例都打上功能模块标签，让同一模块的接口失败和UI失败在同一个视图里按层级展开。同时把每个UI用例的关键操作截图和页面快照挂到报告里，失败的时候报告直接展示最后一步所见即所得。

团队里如果有人不常看自动化报告，第一次打开报告看到的应该是一个明确的结论，“哪个版本、哪个环境、哪些模块挂了、挂了几个”，而不是一串需要二次解读的日志文本。我在一开始没意识到这个问题，框架跑起来之后，我花了很多时间给报告加模块分层、加失败截图、加耗时统计。后来发现这些投入比写用例本身更值钱。

另外一个常见的做法是给UI用例单独加一条“重试后失败才发通知”的告警策略。接口自动化失败往往意味着服务真出事了，要立刻通知；UI自动化失败有相当概率是脚本自身问题，先自动重试、再决定是否升级为真实缺陷。两种用例的失败要分开处理，不能一刀切。

说实话，这也是我自己踩过最多的坑。早期我为了追求覆盖率，什么页面都写UI用例，结果维护成本远大于发现缺陷的收益。后来我改变了习惯：所有业务规则先问“接口层能不能验证”，能则绝不写UI用例；UI层只覆盖用户核心路径和视觉相关的交互。经过这次调整，框架的稳定性才真正上来了，跑一次不再提心吊胆等结果。希望这个取舍思路和前面那些配置细节，能帮你在搭建框架时少走一段我走过的弯路。

本文还有配套的精品资源，点击获取