简介这是一份自动化测试需求分析说明书模板面向软件测试工程师、质量保障负责人与测试开发人员适用于项目立项或测试体系搭建阶段用于梳理自动化测试目标、范围、策略与资源规划。文件为doc文档格式全包共一个文档大小约113KB下载后可直接编辑复用。目前已有102人学习适合需要规范化输出需求文档的团队。模板系统覆盖测试目标、需求收集、测试范围、优先级排序、自动化工具选型、测试框架设计、资源规划、实施计划、风险评估、性能稳定性、维护更新及测试结果分析等关键模块同时补充了沟通协作与文档完整性要求。借助该模板读者可快速明确自动化测试的边界、优先级和成功度量指标减少遗漏与返工为编写高质量需求说明书提供清晰的结构参考和落笔框架。1. 自动化测试需求分析说明书不是测试用例而是测试策略的“预算表”很多团队把“自动化测试需求分析”当成体力活把手工用例复制一遍加两列“是否自动化”“优先级”导出 Word盖章完事。结果自动化跑了两个月脚本数量上去了报告是绿的但项目组没人敢信——因为这份文档根本没回答三个核心问题哪些场景值得自动化、自动化到什么程度、失败之后算谁的。自动化测试需求分析说明书本质上是把手工测试策略翻译成一份面向脚本开发的任务书。它不写“点登录按钮、输入账号密码”这种步骤而是写清楚被测对象的边界、数据的来源与回放方式、环境的重建成本、元素定位的稳定性策略以及“跑挂了”之后的重试和止损规则。适合谁来读测试开发、QA lead、以及被拉去评审的研发负责人。如果你正准备启动 Appium 或 Selenium 自动化或者要给现有项目补一份能落地的自动化测试方案这份需求说明书的写法决定了你后面是写脚本还是写“为什么脚本又挂了”的检讨。2. 先把“要不要自动化”用规则说清楚范围筛选与 ROI 评估2.1.1 自动化测试需求分析的第一步不是写需求是砍需求反直觉的结论是自动化测试需求分析说明书里最重要的章节叫“不做清单”。任何自动化项目失控几乎都是因为一开始把回归测试里所有用例都标成了“自动”然后用三周时间给一个下个月就要下线的营销页写了 50 条脚本。我一般会先定三条硬规则用例执行频率低于每周一次的不自动。需求仍在频繁变动的模块不自动。断言无法用代码稳定描述的比如主观视觉评估不自动。这三条规则不是拍脑袋它们对应的是自动化测试的 ROI 公式收益 执行次数 × 单次节约时间 − 脚本维护成本。维护成本里最大头是定位器和等待策略的持续修复需求一变动定位器就失效脚本要重写。所以“砍需求”不是偷懒是让自动化资产集中在真正高频、稳定、有回归价值的功能上。有了候选集之后再用一个简单的评分脚本把“优先级”而不是“做不做”定下来。2.1.2 用 ROI 评分脚本把优先级变成数字而不是形容词# roi_score.py # 用法: python roi_score.py --frequency 50 --failure_impact 8 --change_frequency 2 --locator_stability 8 def calc_roi(frequency, failure_impact, change_frequency, locator_stability): # frequency: 每周手工执行次数 # failure_impact: 功能挂了对线上影响的严重度, 0-10 # change_frequency: 该模块最近一个月需求变更次数 # locator_stability: 元素定位稳定度预估, 0-10, 越高越稳 roi (frequency * 0.4 failure_impact * 0.3) - (change_frequency * 0.2 (10 - locator_stability) * 0.3) return round(roi, 2) def suggest(score): if score 6: return P0: 第一批自动化 elif score 3: return P1: 第二批自动化 else: return P2: 暂不自动化, 下个迭代复审 if __name__ __main__: import argparse parser argparse.ArgumentParser() parser.add_argument(--frequency, typefloat, requiredTrue) parser.add_argument(--failure_impact, typefloat, requiredTrue) parser.add_argument(--change_frequency, typefloat, requiredTrue) parser.add_argument(--locator_stability, typefloat, requiredTrue) args parser.parse_args() score calc_roi(args.frequency, args.failure_impact, args.change_frequency, args.locator_stability) print(fROI Score: {score}, 建议: {suggest(score)})这个脚本的目的是把“重要、紧急、稳定”这类模糊词变成可比较的数字。注意权重的设定不是固定的核心交易链路可以把 failure_impact 权重提到 0.4内容型网站可以把 locator_stability 提到 0.4。我这里给的是通用基线你落到具体项目时应该先拿历史模块试跑一轮把权重调到评出来的优先级与团队直觉一致为止。2.1.3 范围矩阵表自动化测试需求分析说明书的正文骨架评分完成后把所有候选用例整理成一张范围矩阵表这张表就是自动化测试需求分析说明书的正文骨架。列名我一般固定为模块、用例编号、自动化层级、数据依赖、频率、优先级、脚本负责人。其中“自动化层级”是一个常被忽略但极其重要的判定维度它决定了这条用例是前端 UI 自动化Selenium/Appium、接口自动化还是二者混合。表格示例模块用例编号自动化层级数据依赖执行频率优先级登录LOGIN_001接口预置账号池每周30次P0新闻列表NEWS_012UI无每周15次P1用户中心UC_003UI接口需清库重置每周2次P2这里有个常见误用把纯查询类接口用例全部标成 P0。接口自动化成本低但收益也低——查询接口的断言往往只能验证状态码和响应结构真正容易出问题的是状态变更类接口的组合场景。所以我的建议是接口层优先做“写操作”UI 层优先做“读流程”这个分工在需求分析说明书里就应该写死否则脚本开发会自由发挥最后做出一堆“验证不了业务逻辑”的假自动化。2.1.4 排除项不是垃圾桶视觉验证类场景的处置方式第二类容易写进模板又容易烂尾的是“图片对比”和“视觉验证”。比如验证海报图是否正确展示、图表渲染是否符合设计稿这类场景用 Selenium 的 element 存在性断言是做不到的需要接入视觉回归工具。对于这类用例模板里应该单列一个“视觉验证”分区标注所用工具和阈值参数而不是含糊地写“截图比对”。下手写之前先想清楚视觉断言是最脆的自动化资产CSS 改一个圆角整条断言就飘红。而 SikuliX 这类基于图像识别的自动化工具在极端场景下有价值但也依赖屏幕分辨率和对比度一点环境差异就全盘重跑。模板里我一般会写死一条约定“视觉验证只用于跨端一致性抽检不进入每日回归主链路”。3. 把“需求”翻译成可执行的自动化任务元素定位、数据与环境3.1.1 从功能需求到定位策略的映射是需求分析的硬功夫自动化测试需求分析说明书区别于普通测试用例文档的标志性章节叫做“定位与等待策略”。手工测试不用管元素怎么找到但自动化测试必须回答这个输入框怎么唯一识别它是在 iframe 里吗页面加载完的标志是什么这些问题如果不在需求分析阶段解决脚本开发阶段就会陷入“定位器写一天第二天元素变了再改定位器”的死循环。对于前端来说定位优先级的推荐顺序是id →># waitategy.py from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC from selenium.webdriver.common.by import By def wait_for_element(driver, by, value, timeout10, visible_onlyTrue): # 按元素可见性等待: 用于表单页、弹窗 if visible_only: condition EC.visibility_of_element_located((by, value)) else: # 按元素存在等待: 用于列表加载、异步容器创建 condition EC.presence_of_element_located((by, value)) element WebDriverWait(driver, timeout).until(condition) return element def wait_for_network_idle(driver, timeout10): # 通过注入JS判断document.readyState, 处理SPA页面异步请求 js_script return document.readyState; WebDriverWait(driver, timeout).until( lambda d: d.execute_script(js_script) complete )这里的参数timeout10是个有讲究的数字选 5 秒在 CI 高峰期大概率误报选 20 秒失败用例要多等很久才显示“真挂了”。我的经验值是普通页面 10 秒数据大屏类 15 秒扫码支付类 20 秒。而且超时后不要立刻抛异常先截图再重试一次两次都失败才算失败。这条规则应该写进需求分析说明书里的“超时约定”小节。3.1.3 测试数据的“三张表”必须在需求分析里定完自动化测试需求分析说明书里至少要有三张数据表账号数据表哪些身份、什么权限、业务数据表订单、文章、商品、清理策略表哪些数据跑完必须要清。这三张表最容易出问题的是最后一张没人想写但不清数据的自动化跑一周就会把测试环境塞满垃圾。数据准备的方式在模板里我先给三个选项让项目经理勾选接口造数、数据库直插、页面手工预置。接口造数是首选快且可控数据库直插最快但会绕过业务逻辑的校验适合准备基础数据而不适合准备被测数据本身页面手工预置只适用于无法用前两种方式造数的场景。3.1.4 环境矩阵是自动化测试需求分析的边界条款最后一项必须写清的是环境矩阵。这个矩阵不写“测试环境”四个字就完事要写操作系统、浏览器版本、移动端型号/系统版本、网络条件、是否需要 mock 外部服务。矩阵一旦写清楚就可以回答一个经典问题为什么同一套脚本在本地全过、在 CI 全挂维度本地开发CI 流水线说明屏幕分辨率1920x10801366x768影响响应式布局元素可见性浏览器Chrome 126Chrome 稳定版容器镜像版本不一致导致 CSS 渲染差异外部服务本地 mock测试桩依赖真实服务则不可重复执行网络有线宽带容器内网弱网场景需单独标记在 Appium 场景下矩阵更复杂一台 Android 真机 一台 iOS 模拟器是起步配置iOS 和 Android 的定位策略不一致是常态。需求分析说明书里应用一句“iOS 端不做全量回归只做 P0 冒烟”给范围画条线避免移动端自动化被设备矩阵拖垮。4. Appium 与自动化测试框架落地把说明书变成可验收的实施计划4.1.1 选型有套路但需求分析说明书决定的是组合方式先给结论Web 项目选 Selenium Python或 Java PO 模式移动端选 Appium接口层用 Python 的 requests pytest 就够想要测试报告好看嵌 pytest-html 或 allure。但需求分析说明书里不写“我们要用 Selenium”而要写“哪些场景用 UI 层、哪些场景直接走接口”因为纯 UI 自动化的维护成本是接口自动化的 3 到 5 倍。拿登录来说登录失败的各种分支密码错误、账号锁定、验证码过期都应该走接口自动化只有“登录成功后跳转并展示用户信息”这一条主流程才值得走 UI 自动化。这个分工必须在需求分析说明书中以矩阵形式写出来否则脚本开发会默认“需求分析全部 UI 化”。4.1.2 Page Object 是需求分析说明书里必须写明的代码约束Page Object 模式不是新东西但很多需求说明书不提它结果脚本直接在用例函数里写driver.find_element(...)一个页面要修改时脚本文件复制粘贴改七处。模板里我会强制加一节“代码结构约束”指明每条自动用例的主体必须是 Page 类方法用例层只做步骤编排和数据传入。# pages/login_page.py class LoginPage: def __init__(self, driver): self.driver driver self.username_input (id, username) self.password_input (id, password) self.submit_button (data-testid, login-submit) self.error_toast (class name, login-error) def login(self, username, password): # 输入用户名并调用等待策略, 避免未渲染完成时报错 self.driver.find_element(*self.username_input).send_keys(username) self.driver.find_element(*self.password_input).send_keys(password) self.driver.find_element(*self.submit_button).click() return self.is_login_success() def is_login_success(self): # 等待跳转后的页面容器出现, timeout10 return self.driver.find_element(class name, home-container).is_displayed()这个类写了三个关键约定定位器全部集中为类属性、页面动作返回业务状态的布尔值、不直接依赖用例层的断言。按这个结构做需求分析说明书里关于“当多个用例复用同一登录入口时封装 login 函数并在 conftest.py 声明为 fixture”的要求才能落地。参数说明里有一个容易被忽略的点send_keys前不需要额外 sleep因为类里已经通过find_element触发了隐式等待你需要保证的是is_login_success里的容器类名在需求分析阶段就与前端确认好。4.1.3 失败重试与“可重入性”验收线实施计划的最后要写两件事失败重试规则和通过率验收线。失败重试不是无脑把用例跑三次看哪次过而是要区分“环境失败”和“业务失败”。环境失败重试两次且间隔 30 秒业务失败不重试直接标记失败并保留现场证据。判断依据是如果是元素找不到或超时先定位是页面没渲染完还是页面结构变了如果元素连加载与网络请求都成功但断言错误那就是业务 bug 或断言过期。验收线可以写死为P0 用例成功率 100%P1 成功率不低于 95%P2 不低于 85%。低于这个线就算失败版本不允许合入主干。没有验收线自动化测试需求分析说明书就是一份没有检查机关的规定。5. 用 AI 辅助生成脚本时需求分析说明书就是你的 Prompt 上下文5.1.1 把说明书压缩成 Prompt 模板让 codex 与 cursor 输出更稳最近团队都在尝试用 Codex、Cursor 这类工具辅助生成自动化脚本你会发现一个现象AI 生成的脚本能用但很脆定位器又长又怪等待用sleep(2)硬扛。原因不是工具不行而是你没有给它需求约束。自动化测试需求分析说明书天然就是一份最佳 Prompt 上下文把范围矩阵、定位器约定、等待超时值、失败重试规则放进去AI 生成的脚本质量会上一个台阶。你是资深测试开发工程师。根据以下自动化测试需求分析摘要 - 被测模块: {模块名} - 用例层级: {UI/接口/UI接口} - 元素定位偏好: 优先 style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />