硬件协议测试套编写：从帧建模到异常注入与CI回归

做硬件协议相关的联调最消耗人的从来不是写业务代码而是那条“把协议文档变成一条条可复现的测试用例”的路。我见过不少团队协议文档写了三十多页验证手段却还停留在打开串口助手手敲十六进制指令肉眼比对返回字节。一次全量回归两天起步改一版固件就得重来一遍出了问题只能凭记忆复现。hw 协议测试套编写这件事本质上就是把这套靠人肉堆出来的验证流程变成一份可复用、可回归、可交给 CI 跑起来的资产。这里说的 hw 协议指的是硬件设备之间或主控与从机之间实际跑在物理链路上的通信协议串口、总线、自定义帧格式都算测试套则是一组带断言、能自动执行、失败能定位的用例集合。它解决的是三件事协议实现是否按文档办事、异常输入下设备会不会挂、改了一行代码之后老功能还在不在。适合正在做嵌入式、上位机、设备联调、产线测试的开发者阅读也适合刚接手一份祖传协议文档、不知道从哪下手的新人照着抄结构。1. 先把测试套的边界划清楚别一上来就写用例我踩过最深的坑是拿到协议文档当天就建工程开始写用例写到第三十条才发现方向错了我测的是“我的上位机能不能正确解析回复”而不是“设备的协议实现是否符合文档”。这两件事听起来接近实际差别巨大——前者在解析层做断言设备回什么我都能自圆其说后者必须拿原始字节去比对设备回错一个字节就得红。1.1 被测对象是协议实现不是你的解析代码在动手之前先在心里给被测对象画一条线。线的一头是物理层电平、波特率、采样点、终端电阻这些属于硬件特性通常不放在协议测试套里做除非你在做一致性认证。另一头是应用层语义这条指令是读温度还是读版本号返回的数值范围是多少。协议测试套真正覆盖的是中间那一段——帧的边界怎么定、字段怎么排、长度和校验怎么算、请求和应答的对应关系、超时和重传的规则。把这条线画清楚之后用例的断言就有了落点发送一段构造好的字节流接收一段原始字节流先做帧解析再逐字段比对。解析失败就是失败不做“尽量理解”的容错。我习惯在测试套里单独放一个raw层把物理链路上收到的每一个字节原样记录到日志断言全部基于raw做而不是基于解析后的对象。这样一旦用例红了翻日志就能看到设备到底吐了什么不用再插一次抓包工具。注意如果你的断言基于自己写的解析库那这个库本身有 bug 的时候测试套会一起骗你。至少要用两套独立实现交叉验证一次或者拿几组人工核对过的黄金样本做锚点。1.2 激励层、观测层、判定层三件套各管一段一个能被长期维护的协议测试套结构上我会拆成三层。激励层负责“发什么”它把用例里的语义参数翻译成字节流包括组帧、填字段、算校验观测层负责“收什么”它管理链路句柄、读超时、分包拼包、原始日志落盘判定层负责“对不对”它只做纯函数式的比较输入是收发两段字节和期望规则输出是布尔值加差异描述。这么拆的好处是可替换。换一款设备激励层和判定层基本不动只改观测层的适配代码换一种链路比如从串口换到总线观测层重写用例层一行不用改。我见过把所有逻辑揉在一个test_xxx()函数里的写法二十个用例之后改一个校验算法要改二十处改完还得重新核对每一处有没有漏。1.3 用例粒度定在“一次完整交互”不要拆太碎粒度这件事很影响后期维护成本。拆得太细一个读取动作拆成“发帧”“收帧”“解析”三个用例跑起来互相依赖顺序单独跑就失败拆得太粗一个用例里塞十几次交互红了之后不知道是哪一步坏的。我的经验是以一次完整的请求-应答为一个用例一次交互里如果包含多帧比如分包传输那也归在一个用例内用步骤记录区分。对于需要连续多步才能验证的场景比如握手、鉴权、参数下发、生效确认我会把它写成一个“场景用例”内部用状态机或者步骤列表驱动每一步都有独立的断言点和日志标记。这样它整体是一个用例失败时又能定位到具体第几步。粒度方案优点缺点适用场景单帧单用例定位精准用例数量爆炸依赖顺序帧格式验证单次交互一用例平衡推荐需要良好的失败信息绝大多数功能验证场景一用例贴近真实使用失败定位靠步骤日志流程类、状态机类全流程一用例接近验收极难定位维护成本高出厂自检、冒烟2. 把协议文档翻译成数据结构这一步决定后面全部工作量协议测试套里最容易返工的地方是帧结构的建模方式。文档上画的是表格偏移、字段名、长度、说明。很多人第一反应是照着写一个结构体或者写一个类每个字段一个属性。这个做法在字段少的时候很舒服字段一多、变长字段一出现、可选字段一加代码就开始发臭。2.1 表驱动描述帧比手写结构体抗得住改版我现在的默认做法是用一张字段表来描述帧表里每一行是一个字段的元信息名称、字节偏移或相对位置、长度、类型、是否变长、变长时由哪个字段决定。整个编码和解码过程都由这张表驱动新增字段只改表不改逻辑。# 帧描述表一行一个字段 FRAME_SPEC [ {name: sof, len: 2, type: const, value: b\xAA\x55}, {name: cmd, len: 1, type: uint}, {name: seq, len: 1, type: uint}, {name: plen, len: 2, type: uint, endian: little}, {name: payload, len: plen, type: bytes}, {name: crc, len: 2, type: crc16, endian: little}, ] def encode(fields: dict) - bytes: out bytearray() for f in FRAME_SPEC: if f[type] const: out f[value] elif f[type] uint: n f[len] if isinstance(f[len], int) else fields[plen] out fields[f[name]].to_bytes(n, f.get(endian, big)) elif f[type] bytes: out fields[f[name]] elif f[type] crc16: out crc16(out).to_bytes(f[len], f.get(endian, big)) return bytes(out)这段代码不长但它带来一个隐性收益当协议改版时你能一眼看出改动影响哪些字段而不是在几百行组帧代码里翻找。另外字段表本身可以作为文档的镜像评审的时候直接对照原文表格看比看代码快得多。2.2 字节序和位域是协议测试套里翻车率最高的两块字节序的坑在于“文档默认”和“实现默认”经常不一致。协议文档写“长度字段两字节”没写大小端实现的人按自己的习惯写了小端测试的人按自己的习惯按大端解两边都觉得自己对。我的做法是在字段表里强制显式声明 endian缺失就报错不允许默认值。这一条规则拦下过我至少三次误判。位域更麻烦。一个字节里塞了四五个标志位文档画的是从高位到低位实现按位运算写测试按位运算读只要有一边理解错了起始位整条用例就是错的而且错得很隐蔽——因为标志位通常只影响某一小段逻辑。对付位域我一般准备一张“位映射表”把每一位的含义、期望值、复位值都列出来然后用一个专门的用例把所有位的组合边界跑一遍比如全 0、全 1、单 bit 翻转。提示遇到位域字段先做一次“写-读回来”的验证再去做业务验证。如果设备连自己写的标志位都读不回来后面的业务断言全是白费。2.3 黄金样本加往返测试让编解码层先自己有底气在测设备之前先测自己的编解码层。具体做法是准备一批黄金样本从真实设备抓下来的完整帧人工逐字节核对过含义存成二进制文件加一份说明。然后写两类用例一类是“给定语义字段编码结果必须等于黄金样本”另一类是“给定黄金样本解码出来的字段必须等于说明里写的内容”。这两类用例跑绿你再拿它去测设备才敢相信失败是设备的问题而不是工具的问题。我吃过一次亏解码里长度字段偏移算错了一个字节导致所有用例都红团队花了半天排查固件最后发现是测试套自己错了。从那以后编解码层的自测成了我新建测试套的固定第一步。验证对象用例类型断言方式目的编码器语义到字节与黄金样本逐字节相等证明发出去的帧合法解码器字节到语义与人工注释逐个字段相等证明收回来解得对编解码往返一致decode(encode(x)) x证明无信息丢失解析器畸形输入抛指定异常而非崩溃证明鲁棒性3. 时序类用例最容易写脆参数化是唯一的解硬件协议里有一大类验证点和数据内容无关只和时间有关应答必须在多少毫秒内返回、两条指令之间至少间隔多久、超时之后重发几次、心跳丢失多久判定断链。这类用例写起来快跑起来碎换个机器、换个负载、换个 USB 转接芯片结果就飘。3.1 超时值不要写死从配置里读并留出容差我最开始写的时候每个用例里直接写timeout0.5跑在本机很稳搬到 CI 的容器里开始偶发失败。后来改成两级参数协议规定的名义值加环境容差系数容差系数按运行环境从配置里取本机 1.2 倍CI 容器 2.0 倍产线夹具 1.5 倍。这么改之后同一批用例在不同环境下的稳定性差别非常明显。需要强调的是容差只能放大“等待上限”不能放大“判定下限”。协议要求 10ms 内应答你把上限放到 30ms那 25ms 才应答的设备也会被判过这就失去了测试意义。所以我的做法是把断言拆成两条一条断言“必须应答”用放大的上限另一条断言“应答时延落在协议窗口内”用严格值并且这条用例只在受控环境下跑不进日常回归。3.2 用步骤序列描述交互比嵌套函数好读连续交互的用例我倾向于用一份步骤列表来描述每一步声明动作、期望、超时、失败策略。这样整条用例读起来像一份操作手册评审的时候非技术同事也能看懂在测什么。SCENARIO_HANDSHAKE [ {step: 上电复位, action: power_cycle, wait: 0.2}, {step: 发送握手, action: send, frame: {cmd: 0x01}, expect: resp, timeout: 0.1}, {step: 校验会话号, action: assert_field, field: session, op: !, value: 0}, {step: 空窗期内发指令, action: send, frame: {cmd: 0x02}, expect: nack, timeout: 0.1}, {step: 等待超时后重连, action: sleep, seconds: 3.0}, {step: 重发握手, action: send, frame: {cmd: 0x01}, expect: resp, timeout: 0.1}, ]用这种结构新增一个场景只是加一份列表不用碰执行器。执行器本身固定做四件事执行动作、等待期望、记录实际值、按策略处理失败。失败策略我一般分三档立即中止、跳过后续继续、标记为已知问题继续。第三档在协议还在迭代的阶段特别好用能先跑通主干把已知缺陷挂起。3.3 抖动、重试、丢包要分清是特性还是故障同样的“没收到应答”可能是三种完全不同的情况设备真的没回、设备回了但链路丢了、设备回得慢超出了窗口。这三者在测试套里的处理方式完全不同不能一律判失败。我的处理办法是在观测层把这三件事分开记录物理层收字节的时间戳、组帧完成的时间戳、业务层拿到应答的时间戳。三个时间戳一对比就能判断是链路上丢了还是应用层慢了。配合一个可控的链路损伤注入开关比如故意丢第 N 个包、故意延迟 M 毫秒可以把“设备在丢包情况下的重试行为”也纳入验证而不是只在理想链路上跑。提示不要在没有链路损伤能力的情况下把“重试逻辑正确”写进测试报告。理想链路上的重试用例大概率一次都没真正触发过重试路径。4. 异常注入才是这套东西真正的价值所在正常帧的验证人工敲几次也就覆盖了真正花时间、真正能抓出问题的是异常输入。我统计过自己维护过的几个测试套能在版本迭代中稳定抓出新引入缺陷的用例八成以上是异常注入类而不是正常流程类。4.1 畸形帧清单先列全再挑着实现异常注入不要凭灵感要列清单。我通常按“帧的构成要素”逐项破坏形成一张覆盖表帧头错、帧头缺失、长度字段与实际不符偏大、偏小、为零、校验错、校验缺失、命令字非法、序号重复、序号跳变、负载超长、负载为空、字段值越界、保留位被置位、帧尾多余字节。这张清单不需要一次全实现但列全很重要因为它决定了你的测试套有没有盲区。我一般先实现“长度类”和“校验类”这两类最容易触发缓冲区溢出和状态机错乱性价比最高然后再补“命令字类”和“序号类”验证设备的错误处理路径是否健全。破坏维度典型构造期望行为常见实际缺陷帧头改成错误常量丢弃并重新同步卡死等待、错位解析长度声明长度大于实际超时丢弃越界读、内存异常长度声明长度小于实际截断后重新同步粘包、后续帧全错校验翻转一位返回校验错误码静默接受脏数据命令字未定义值返回不支持无响应、复位序号重复上一帧幂等处理或拒绝重复执行副作用4.2 半包、粘包、超长包链路层的三种典型病这三类问题在串口和流式链路上极其常见而且人工测试很难稳定复现。测试套里做起来反而简单在观测层的发送函数外面套一层“切包器”把一整帧按指定位置切开分两次发中间插一个延迟或者把两帧拼在一起一次发或者在一帧后面追加几十个垃圾字节。def send_split(link, frame: bytes, at: int, gap: float 0.02): 在指定位置把一帧拆成两段发送模拟半包 link.write(frame[:at]) time.sleep(gap) link.write(frame[at:]) def send_glued(link, f1: bytes, f2: bytes): 两帧粘在一起发送模拟粘包 link.write(f1 f2) def send_trailing_garbage(link, frame: bytes, n: int 64): 帧后追加垃圾字节验证重新同步能力 link.write(frame bytes(random.getrandbits(8) for _ in range(n)))每一类都要断言两件事设备对这次异常输入的反应丢弃、报错、还是错误解析以及异常之后能否恢复正常通信。第二件事比第一件重要得多很多设备的毛病不是不能处理异常而是处理完异常之后状态机没回位后续正常帧全部失效。4.3 判定“恢复”的标准要写死不能靠感觉“恢复”这件事必须有明确判据否则用例会变成主观判断。我的判据通常是三条同时满足异常帧之后的第一条正常请求能得到正确应答、异常帧期间没有产生非预期的副作用比如误写寄存器、设备没有发生复位可以通过版本号或运行计数值变化判断。这三条里第二条最容易被忽略。举个典型场景你发了一条长度字段造假的写寄存器指令设备把它当成合法帧解析了虽然返回了错误码但寄存器已经被改了一半。这种情况在只看应答码的测试里是过的在检查副作用之后就会红。所以我在测试套里会给关键寄存器做“前后快照”异常注入用例跑完自动比对。5. 接上真实设备之后麻烦才真正开始测试套在自己写的模拟器上跑绿只说明逻辑自洽。接到真实硬件上环境问题会成倍出现串口被占用、设备枚举顺序变化、上电时序不对、夹具接触不良、跑久了设备发热降频。这些不属于协议问题但会让你的用例红得莫名其妙。5.1 适配层要薄把设备差异全部挡在外面我坚持一个原则用例层不允许出现任何具体的链路 API。用例只认open、send、recv、reset这几个抽象动作具体怎么实现由适配层决定。串口是一种实现USB 转接是另一种总线收发器又是另一种将来换夹具只改适配层。适配层里我会额外加两个东西一是链路自检打开之后先发一条已知能通的探测帧确认物理连接正常再跑用例避免把“线没插好”报成“协议不兼容”二是复位能力包括软复位指令和硬复位控制电源或复位引脚用例失败后自动复位再继续防止一个用例把设备搞死拖垮后面全部。5.2 用例之间必须隔离顺序依赖是维护灾难早期我写过依赖顺序的测试套用例一到用例十必须按顺序跑单独跑用例五就失败。这种测试套用起来极其痛苦排查问题要跑全量、并行执行不可能、任何一条挂了后面全挂。后来统一改成每条用例开头自带前置条件需要什么状态就自己构造什么状态构造方式写成一个可复用的 fixture。代价是单条用例耗时变长收益是任意子集都能独立跑、能并行、能只跑失败的那几条。实际算下来总体时间是省的因为排查成本降了太多。5.3 日志和波形对齐排障效率差好几倍设备出问题时光有收发日志往往不够还得知道那一刻线上到底发生了什么。如果条件允许我会让测试套在每条用例开始时打一个标记同时触发一次逻辑分析仪或示波器的采集把时间戳对齐。这样用例红了直接跳到对应时间窗口看波形比对着日志猜时序快得多。没有波形设备也行退一步至少要做到日志里记录每条收发的绝对时间戳、字节数、原始十六进制、解析结果、用例步骤编号。这五样齐全八成问题能靠日志定位。我见过只记“发送成功/接收失败”的日志那种日志在排障时基本等于没有。6. 用例写完只是开始治理才是长期活一个测试套从三十条长到三百条的过程中最大的敌人不是写不出来而是跑得慢、红得乱、没人看。这三件事只要出现一件测试套就会在半年内变成摆设。6.1 分层执行让日常回归控制在可接受的时间内我会把用例分成三档。冒烟档二十条以内覆盖上电、握手、核心读写、异常恢复要求一分钟内跑完每次提交都跑全量档覆盖所有功能点和异常注入十分钟到半小时每天定时跑或者合并前跑长稳档做持续通信、反复复位、边界温度下的长时间运行几小时到几天每周跑。分层的依据不是用例的重要性而是执行时间。这点很重要很多人按重要性分层结果冒烟档里塞了一堆关键但很慢的用例跑一次五分钟最后大家都不愿意跑。我的标准很简单一条用例如果超过三秒它就不该在冒烟档里除非能证明它不可替代。6.2 不稳定用例要处理不能靠重跑掩盖偶发失败的用例业内俗称 flaky。处理方式有三种我按优先级排修掉、隔离、删除。修掉是首选绝大多数不稳定来自写死的等待时间、共享的链路句柄、没有清理干净的状态。隔离是把已知不稳定但仍有价值的用例打上标记单独一个任务跑不阻塞主干。删除是最狠的但对那些“跑十次红三次、修了三次还是红、也没抓到过真问题”的用例删掉比留着好——它消耗的是团队对整个测试套的信任。我给自己定了一条线一条用例连续两周出现无法解释的偶发失败就必须做决定不允许一直挂着。挂着的用例比没有用例更糟因为它会训练大家忽略红色。6.3 失败信息要能自证别让人再去翻代码一条好的失败信息应该让看到的人不用打开用例源码就知道发生了什么。我的模板大致是用例名、步骤号、期望值、实际值、原始收发字节、发生时间、设备状态快照。理想情况下再加一句“最可能的原因”这句不是猜而是基于断言类型给出的提示比如“长度字段不符优先检查组帧逻辑或设备对变长字段的处理”。def assert_frame(actual: bytes, expect: dict, step: str): got decode(actual) for k, v in expect.items(): if got.get(k) ! v: raise AssertionError( f[{step}] 字段 {k} 不符: 期望 {v!r}, 实际 {got.get(k)!r}\n f原始帧: {actual.hex( )}\n f解析结果: {got} )这个函数没什么技术含量但它把排障所需的信息一次性打全了。我在实际项目里最大的体会是测试套的价值一半在发现问题上另一半在让人愿意去看它报的错。报错信息写得敷衍再全的覆盖也没人维护。最后分享一个我自己的习惯。每次协议改版我会先只改字段表和黄金样本然后跑一遍全量看有多少用例红。红的那批就是这次改版真正影响到的范围比对着文档逐条推演靠谱得多。这个动作做多了你会对自己这套测试套的覆盖边界心里有数也就知道哪些地方还欠着用例——那种感觉比看覆盖率数字实在。