第27章 测试文档：测试计划编写、测试报告模板、文档自动化

说实话，很多工程师对测试文档的态度就是——能省则省。我以前也这么想，觉得代码跑通了就行，写文档纯属浪费时间。直到有一次，我负责的一个通信模块出了个诡异的bug，翻遍所有测试记录，发现根本没人记录当时的测试环境和步骤。嗯，从那以后，我再也不敢轻视测试文档了。

这一章，我就跟你聊聊测试文档到底该怎么写。不是那种应付差事的模板填空，而是真正能帮你省时间的文档体系。

测试计划：别让测试变成无头苍蝇

测试计划不是写给领导看的，是写给你自己看的。你想想看，一个模块几十个函数，上百条路径，没有计划你怎么知道测了什么、漏了什么？

我个人习惯，测试计划至少包含这几块：

• 测试范围：明确哪些函数要测，哪些不测。比如底层驱动函数必须全覆盖，而一些简单的getter/setter可以跳过。
• 测试策略：用白盒还是黑盒？边界值怎么取？异常路径怎么覆盖？
• 测试环境：编译器版本、硬件平台、依赖库版本。这个我吃过亏——同一个代码，在GCC 4.8和GCC 9.3下行为不一样。
• 测试用例清单：每个用例的编号、输入、预期输出、优先级。
• 进度安排：谁在什么时候完成什么测试。

举个例子，我之前做的一个CAN总线驱动模块，测试计划里我专门标注了「波特率配置函数需要覆盖所有合法值+边界值+非法值」。为什么？因为我在项目里遇到过，某个非法波特率配置导致整个CAN控制器锁死，连复位都救不回来。

测试报告模板：数据说话，别写流水账

测试报告不是让你写「今天测了3个函数，都通过了」这种废话。好的测试报告，应该让读者一眼看出：

• 哪些功能是可靠的
• 哪些地方还有风险
• 回归测试有没有引入新问题

我常用的测试报告模板长这样：

模块	测试用例数	通过	失败	阻塞	通过率
内存管理	45	42	2	1	93.3%
协议解析	28	28	0	0	100%
定时器	15	12	3	0	80%

除了这个汇总表，我还会附上每个失败用例的详细信息：

• 用例编号和名称
• 失败时的输入和实际输出
• 预期输出和偏差分析
• 初步根因分析（是代码bug还是测试用例写错了？）
• 建议修复方案

文档自动化：别手动填表了，让工具干

手动写测试报告？太累了。我见过有人每次跑完测试，一条一条复制粘贴结果到Excel里。这不是工程师该干的事。

文档自动化的核心思路就一句话：测试结果从工具里直接生成，不要人工二次加工。

我常用的做法是：

1. 测试框架（比如Unity、Ceedling）跑完测试后，输出XML或JSON格式的结果。
2. 写一个Python脚本，解析这个结果文件，自动生成Markdown或HTML格式的测试报告。
3. 把这个脚本集成到CI/CD流水线里，每次提交代码自动跑测试、自动生成报告。

下面是一个简单的Python脚本片段，用来解析Unity测试结果：

import xml.etree.ElementTree as ET

def parse_unity_report(xml_file):
    tree = ET.parse(xml_file)
    root = tree.getroot()
    
    tests = root.findall('.//test')
    passed = sum(1 for t in tests if t.get('status') == 'pass')
    failed = sum(1 for t in tests if t.get('status') == 'fail')
    
    print(f"总用例: {len(tests)}")
    print(f"通过: {passed}")
    print(f"失败: {failed}")
    print(f"通过率: {passed/len(tests)*100:.1f}%")
    
    # 输出失败用例详情
    for t in tests:
        if t.get('status') == 'fail':
            print(f"  [失败] {t.get('name')}: {t.find('failure').text}")

知识体系：测试文档的核心逻辑

说了这么多，我画张图帮你理清思路。测试文档不是孤立的，它和测试流程、代码质量、团队协作都紧密相关。

你看，这三个部分其实是环环相扣的。测试计划指导你怎么测，测试报告记录测的结果，文档自动化让整个过程不再依赖人工。少了任何一个环节，文档体系都会出问题。

避坑指南：我踩过的那些坑

最后分享几个我亲身经历过的教训：

• 测试计划写得太粗：我曾经只写了「测试所有接口函数」，结果执行的时候发现有的函数参数组合太多，根本测不完。后来我学乖了，每个函数都标注「重点测试路径」和「可忽略路径」。
• 测试报告不及时更新：有一次项目赶进度，测试报告拖了一周才写。结果发现有个bug其实早就出现了，但因为没记录，开发人员又花了两天重新定位。嗯，从那以后我坚持「当日测试当日报告」。
• 自动化脚本没有错误处理：前面提过了，不重复。总之，自动化不是写出来就完事了，要考虑到各种异常情况。