简介这份用例文档以“好食上餐厅管理系统”为实例系统展示标准用例文档的撰写框架适合软件工程学习者、需求分析师及产品经理参考。全文依次介绍前言、背景与内容概述、用例列表、用例图、用例描述和总结覆盖顾客资料管理、店内顾客订餐、电话订餐、网上订餐、账单结算、顾客反馈信息管理、连锁店管理等典型业务场景。其中用例描述部分对每个用例的名称、前置条件、触发条件、基本流程、扩展流程及特殊要求均给出示例例如店内顾客订餐从顾客选择菜单到订单确认的全过程能帮助读者将功能需求转化为清晰的文档表达。资源共包含一个docx文档压缩包约2.9MB体量虽小但结构完整可作为课程设计、项目开发或软件工程实训中的需求文档写作模板。已有615人学习下载适合需要快速上手用例文档编写的初学者借鉴。1. 用例文档难写根子在 docx 的编辑性与用例的结构化冲突用例文档大概是软件工程里最被低估的交付物。团队里常见两种极端一种是测试用例写成了散文步骤、预期混在一个单元格里评审时全靠人肉找另一种是用力过猛前置条件、步骤编号、预期结果分得极细但每次需求变更都要改几十个表格改到后来文档和实际测试行为脱节。这个标题「用例文档.docx」的微妙之处在于.docx不是单纯的存储格式它的开放性让自动化生成、批量修改和版本审阅成为可能而绝大多数人只用到了它的 Word/WPS 编辑面。把用例从「写给人看的手工表」升级成「既给人看也能被程序解析的半结构化数据」才是这个标题真正值得做的事。这篇文章面向测试工程师、测试开发和对文档工程化有要求的项目经理从用例字段设计讲到用脚本驱动 docx 生成与校验全程不依赖任何商业插件。2. 最小可复现用例的写法docx 表格里的「用例子集」该长什么样2.1 用例的本质是三元组docx 只是它的载体无论用例文档长成什么样拆到最底层都是同一个结构前置条件、操作步骤、预期结果。前置条件用来限定执行环境操作步骤是驱动被测系统的动作序列预期结果是每一步或最终的可观察状态。把这三件事写清楚用例就成立在这之前纠结模板样式、字段数量都是本末倒置。我见过不少用例文档把「用例编号」「所属模块」「优先级」「用例名称」「前置条件」「操作步骤」「预期结果」「实际结果」「测试数据」九个字段全塞进一张表。字段多有多的好处比如便于统计和追踪缺陷但字段太多会让维护成本暴涨。对于中小团队我更建议保留六个核心字段用例编号、所属模块、前置条件、操作步骤、预期结果、测试数据。优先级和实际结果可以放到缺陷管理系统里不必在 docx 里重复维护。这是「用例文档.docx」作为测试交付物时最值得做的一步减法。2.2 从「比例调整」到「逐单元格设宽」docx 表格的 3 个必调参数用例文档的表格在 Word 里调整格式本质上改的是 Open XML 里的w:tblGrid列定义和w:tcPr单元格属性。手工操作时大家习惯拖动标尺来调列宽但用脚本或批量处理时列宽的稳定设置就变成了一件必须较真的事。用 python-docx 初始化一张用例表的基本做法是from docx import Document from docx.shared import Cm doc Document() table doc.add_table(rows1, cols6) table.style Table Grid table.autofit False widths [Cm(1.5), Cm(2.0), Cm(3.0), Cm(4.5), Cm(3.5), Cm(2.5)] headers [用例编号, 所属模块, 前置条件, 操作步骤, 预期结果, 测试数据] for idx, (cell, text, width) in enumerate(zip(table.rows[0].cells, headers, widths)): cell.text text cell.width width这段逻辑的关键在最后两个属性。table.autofit False关闭 Word 的自动调整机制防止 Word 根据内容重新分配列宽cell.width Cm(...)是逐单元格设置宽度这在 python-docx 里比设置table.columns[idx].width更可靠——后者受表格整体宽度和网格列定义影响经常出现设了但没生效的情况。需要特别留意的是python-docx 生成的列宽单位是英制单位的 EMU用Cm或Inches包装之后最终落在 XML 里的值是整形数值所以设置 3.0 厘米和 3.1 厘米在 Word 里显示差别极小不必追求小数点后的精度。一个常见误用是只改表头行的单元格宽度数据行不加。Word 的表格列宽实际由网格定义决定但渲染时单元格宽度会覆盖网格设置。如果你只设置了表头行的cell.width新插入的数据行仍按默认网格渲染表现在界面上就是列宽参差不齐。处理办法是在向表格添加行并逐单元格写入内容时每次都同步设置该行单元格的宽度。提示用脚本维护用例文档时把宽度配置提取成模块级常量。不同项目的用例字段长度可能差异很大固定写在函数里会让后续调整成本变高。2.3 操作步骤的原子化每行一个动作别把「步骤」变成「段落」操作步骤是「用例文档.docx」里最容易被写烂的部分。很多人把整条用例的操作步骤写成一个单元格里的长段落用「1. 打开登录页 2. 输入账号 3. 点击登录」这种换行方式表达多步操作。这种做法在人工执行时没有问题但一旦用例数量超过两百条或者你希望通过脚本把 docx 里的步骤解析出来跑自动化这种写法就是灾难。比较好的做法是让每个步骤独立成行甚至在步骤前加上显式编号。下面这个表格结构是经过了实际项目验证的步骤操作预期结果1打开登录页输入已注册账号与正确密码页面跳转至首页右上角显示用户昵称2点击右上角「退出登录」跳回登录页本地存储的会话标识被清除3使用错误密码重复步骤 1页面提示「账号或密码错误」停留当前页这种结构的优势不只是排版清晰。当用例需要通过接口或 UI 自动化框架回放时解析「步骤 操作」两列比解析一段散文式的描述稳定得多。操作列里的每个动词短语可以继续切分成「动作 定位 参数」例如「点击」「输入」「选择」配合元素描述和数据。如果未来有回归自动化计划建议从第一天就用这种原子化格式不要等到用例文档积累了上千条再回头改。3. 用 python-docx 批量生成「用例文档.docx」的最小脚本3.1 为什么是 python-docx以及它的工作边界处理 docx 的方案选择其实不多。VBA 宏在 Windows 上很顺手但跨平台、进 CI 都困难手动维护模板能解决样式统一解决不了从 Excel 或 JSON 数据源批量生成用例表的问题。python-docx 是目前最成熟的开源方案它不对 Word 做「自动化操作」而是直接读写 docx 包内的 XML 文档所以在 Linux 服务器上也能运行。它的边界也需要明确读现有文档时对复杂样式例如嵌套表格、分节符、修订记录支持并不完整写文档时能控制的样式项也比 Word 界面能设置的少很多。需要精细排版时我通常让脚本只负责表格内容样式在最后用模板文档统一套。确认环境后安装pip install python-docx3.2 从用例数据到 docx一个能直接改的生成脚本实际项目中用例数据通常来源于需求文档、Excel 或测试管理平台导出。这里演示一个从 Python 列表生成用例文档的脚本数据源换成读 Excel 或 JSON 只需要替换数据加载部分。from docx import Document from docx.shared import Cm, Pt from docx.enum.text import WD_ALIGN_PARAGRAPH # 数据源每条用例是一个 dictkey 与表格列对应 cases [ { id: TC-LOGIN-001, module: 登录模块, precondition: 系统已部署数据库正常连接, steps: 1. 打开登录页\n2. 输入正确账号密码\n3. 点击登录, expect: 登录成功跳转至系统首页, data: user01 / 123456 }, # ... 更多用例 ] doc Document() # 设置正文默认字体避免生成后还要手工全选改字体 normal doc.styles[Normal] normal.font.name Microsoft YaHei normal.font.size Pt(10.5) doc.add_heading(登录模块用例文档, level1) doc.add_paragraph(版本 v1.0自动生成时间 2025-01-20) table doc.add_table(rows1, cols6) table.style Table Grid table.autofit False headers [用例编号, 所属模块, 前置条件, 操作步骤, 预期结果, 测试数据] widths [Cm(2.2), Cm(2.0), Cm(3.2), Cm(5.0), Cm(4.0), Cm(2.6)] for idx, (cell, text, width) in enumerate(zip(table.rows[0].cells, headers, widths)): cell.text text cell.width width for case in cases: row_cells table.add_row().cells for idx, key in enumerate([id, module, precondition, steps, expect, data]): row_cells[idx].text case[key] row_cells[idx].width widths[idx] doc.save(用例文档.docx) print(f已生成 {len(cases)} 条用例)脚本的运行逻辑是先创建空文档设置默认字体然后添加标题和版本说明再创建一张六列表格并写入表头最后逐条追加数据行。table.add_row()返回的是一行单元格列表注意这里和 Excel 不同python-docx 的单元格写入.text时会替换该单元格原有内容所以对空行来说不需要额外清空。操作步骤里的换行是在数据源里用\n实现的。python-docx 会把换行符变成w:br/标签在 Word 里显示为同一个单元格内的多行文本。这种写法的优点是不用为每条步骤创建子表格解析时按换行拆分即可还原步骤序列。3.3 数据导入 docx 后如何在数据驱动中保留格式当模板文件已经存在你希望往已有的「用例文档.docx」模板里填入新的用例数据而不是每次从空文档重建。这在需求变更频繁的项目里更常见。python-docx 可以打开现有文档并追加表格from docx import Document from docx.shared import Cm doc Document(example.docx) # 打开现有模板 # 找到第一个表格作为用例表也可以遍历查找特定标题对应的表格 table doc.tables[0] new_case [TC-ORDER-002, 订单模块, 用户已登录, 1. 添加商品到购物车\n2. 提交订单, 订单创建成功状态为待付款, 商品ID1001] row_cells table.add_row().cells widths [Cm(2.2), Cm(2.0), Cm(3.2), Cm(5.0), Cm(4.0), Cm(2.6)] for idx, text in enumerate(new_case): row_cells[idx].text text row_cells[idx].width widths[idx] doc.save(用例文档_v2.docx)这里唯一要小心的坑是模板中表格的行数。add_row()追加的行完全复制表格原有行的结构如果你的模板表格首行是「表头行」已经写好了字段名追加行是数据行结构上没有冲突。但如果模板中存在合并单元格的行追加行的单元格数量可能与预期不一致那是 python-docx 对合并单元格支持不完全造成的建议生成模板时尽量少用跨行合并。提示无论新建还是追加生成后都用doc.save(用例文档_v2.docx)另存为新文件不要直接覆盖模板。模板一旦被脚本写坏手工恢复成本很高。4. 批量文件入库与场景增强docx、CSV 与图片的协同处理4.1 用 docx2txt 和 python-docx 读取已有用例文档反推数据结构不是为了生成就有价值反过来读取旧文档入库也经常发生。历史遗留的用例文档往往没有统一的数据源全部散落在各个版本的 Word 文件里。这时候需要用程序扫描 docx 并提取表格内容。docx2txt 是一个轻量库但它只提取纯文本会丢失表格结构python-docx 读取表格更可靠。下面这段脚本扫描一个目录下所有 docx 文件把六列的用例表格统一提取成 CSVimport glob import csv from docx import Document output_rows [] for filepath in glob.glob(用例文档_old/*.docx): doc Document(filepath) for table in doc.tables: # 跳过明显不是用例表的结构列数不匹配 if len(table.columns) ! 6: continue for row in table.rows[1:]: # 跳过表头 cells [cell.text.strip().replace(\n, ) for cell in row.cells] if any(cells): output_rows.append(cells) with open(用例_汇总.csv, w, newline, encodingutf-8-sig) as f: writer csv.writer(f) writer.writerow([用例编号, 所属模块, 前置条件, 操作步骤, 预期结果, 测试数据]) writer.writerows(output_rows) print(f共导出 {len(output_rows)} 条用例)这段逻辑有几个细节值得注意。len(table.columns)用来过滤掉非目标表格批量处理时目标目录下很可能混有别的小表row.cells在存在合并单元格时同一个单元格对象可能重复出现去重的最简单方式是检查前后值是否相同输出为utf-8-sig编码的 CSV 是为了让 Excel 打开时不出现中文乱码。4.2 在用例文档里放图片截图证据和 MP4 视频的取舍用例文档里有一类特殊的「数据」不是放在表格里的而是以截图形式出现的——登录页截图、报错信息截图、接口返回报文截图。python-docx 插入图片的标准做法是from docx import Document from docx.shared import Cm doc Document() doc.add_picture(screenshot_login.png, widthCm(14)) doc.paragraphs[-1].alignment 1 # 居中 doc.save(用例文档.docx)screenshot_login.png会被嵌入到word/media/目录在 docx 文件里实际是一张独立的图片资源。建议插入的图片统一在截取时压缩宽度到 14 厘米以内因为原始分辨率过大的截图会让 docx 文件体积激增用手机或邮件传输时很不方便。一组规范的做法是把截图命名为「用例编号_步骤号.png」的格式再用脚本按步骤自动插入到对应单元格后面。至于视频很多测试场景会录屏比如演示一个复杂交互流程。MP4 直接嵌入 docx 虽然技术上可以但跨平台打开的成功率低尤其 WPS 和 Word 对视频对象的支持不同步经常出现对方收到文件后无法播放。我一般建议在用例文档里放两个东西一帧关键的封面截图外加视频文件的路径或网盘链接。如果团队使用在线文档例如飞书云文档把 MP4 传上去再在 docx 里留链接是最稳的做法既保证文档体积可控又避免了格式兼容问题。docx 的价值是结构化地表达「预期」视频的价值是记录「实际」两者不必硬塞进同一个文件。4.3 用例文档入库后的自动化检查文档批量生成之后做一个简单的完整性检查很有必要比如步骤为空、预期结果为空、编号重复。手工检查大文档效率太低脚本能在一秒内完成from docx import Document doc Document(用例文档.docx) seen_ids set() issues [] for table in doc.tables: for row in table.rows[1:]: cells [c.text.strip() for c in row.cells] # 按列位置取字段这里假设六列结构固定 case_id, module, precondition, steps, expect, data cells[:6] if case_id in seen_ids: issues.append(f重复用例编号: {case_id}) seen_ids.add(case_id) if not steps: issues.append(f{case_id}: 操作步骤为空) if not expect: issues.append(f{case_id}: 预期结果为空) print(\n.join(issues) if issues else 检查通过)这里的检查逻辑很容易扩展——比如步骤列必须包含编号「1.」预期结果不能是「正常」这类模糊词。这类规则型检查放进 CI 里每次提交用例文档变更后自动跑一遍能显著减少评审会上因低级遗漏导致的返工。5. 易踩的坑与团队协作技巧docx 审阅的 3 个边界5.1 用 WPS 打开 docx 的兼容性陷阱「docx 无法预览」「WPS 不能默认新建 docx」这类问题在团队协作里经常被当成环境问题实际是文档设置层面有差异。WPS 的默认保存格式可能被设成.wps或.et导致发送给同事的「用例文档.docx」文件对方用 WPS 双击打开看到的是新建的空白文档。处理办法是在 WPS 设置里将默认格式改为 docx同时分发文件后用文件扩展名和图标双重确认——扩展名是一回事Word 能否正常打开是另一回事。这类兼容问题在纯 Word 环境里极少出现但一旦团队混合使用两套 Office 软件建议把「用 LibreOffice 打开验证一遍」作为文档交付前的最后一步。5.2 版本对比不友好docx 二进制结构带来的 diff 难题用例文档在评审阶段最痛的一点是版本对比。文档从 v1.0 改到 v1.3谁改了哪一行、某个用例的预期结果从什么时候被修改的在 Word 里打开修订模式可以看但把修改后的文档发出来对方看到的是一份干净的版本没有上下文。这是 docx 的深层问题如果不用修订模式两次保存的文件在包结构上差异极其微小任何 diff 工具都无法对非程序员友好的方式展示「上一版里步骤 2 的预期结果是什么」。一种务实做法是每次评审前导出 PDF 版本做对比基线。WPS 或 Word 打开 docx 后「另存为 PDF」再用 PDF 对比工具例如 Adobe Acrobat 或免费的 DiffPDF比较两版差异。比在 docx 里开修订模式更稳因为 PDF 的渲染结果是确定的。另一种做法是从一开始就把用例维护在在线文档里飞书文档或腾讯文档天然带版本历史docx 只作为分发用的快照格式。这个思路也解释了为什么很多人检索「用例文档.docx」相关词时总带着在线文档的疑问——本质上大家在找一种既能离线交付又能在线协作的混合模式。5.3 当 docx 不适合作为用例载体时的替代选择最后提一个判断依据。用例文档的.docx适合作为交付物但不太适合作为唯一的维护源。当用例数量超过 500 条或者需要跟自动化测试框架联动时把用例维护在 Excel 或测试管理平台里再用脚本导出为「用例文档.docx」用于评审和归档会比直接在 Word 里维护表格省力得多。docx 的优势在于正式、稳定、随处可读它的劣势在于结构化程度低、无法做数据约束。认清这个边界你把 docx 用在文档交付环节用 Excel、JSON 或数据库用在存储环节再让脚本在两者之间做转换这是最不容易翻车的组合。这三个边界分别对应格式兼容、版本对比、载体选择都是团队日常协作中真实会碰到的场景。提前想清楚边界比会写一百条生成脚本更能让「用例文档.docx」持续发挥价值。本文还有配套的精品资源点击获取
