私有化测试管理平台如何对接自动化测试？接口与结果回传指南

私有化部署的测试管理平台把测试数据留在内网，自动化脚本却常常跑在流水线或独立测试机上。两边之间需要一条稳定的回传通道，对接才算真正完成。这条通道能否长期可用，不取决于第一次调用是否成功，而取决于三件事：用例能不能对上号、结果能不能被追溯、失败之后能不能自动进入 Bug 流程。

《2024 年软件测试行业现状调查报告》显示，在企业未来计划加大投入的测试领域中，接口自动化测试占比 50.0%，是投入意向集中的方向之一。执行量上去之后，靠人工回填结果或截图归档，很快会成为瓶颈。

下面按「前提 → 选路 → 操作 → 分支 → 验证」的顺序，说明三种对接路径和结果回传的关键细节。操作示例以禅道的测试管理与 ZTF 执行工具为主。禅道在测试管理领域已服务国内 100 万+ 团队，用例、测试单、执行结果与 Bug 闭环可以在同一个平台内完成。

接入前先确定三件事

私有化部署让数据留在内网，配置项不多，但每一项都决定后面能不能稳定跑通。

• 网络可达：执行脚本的机器（流水线 Agent 或独立测试机）要能访问平台的服务地址和端口。
• 独立的集成账号与最小权限：为对接单独建账号，只授予必要的接口和操作权限，不用管理员账号做集成。
• 用例标识规则：先确定脚本与用例怎么对应，按用例 ID、脚本文件名还是套件名，后续所有回传都依赖这条规则。

这三项没定下来就动手写代码，通常会在联调阶段返工：脚本找不到对应用例、结果重复写入、权限不足导致回传静默失败，都是前期规则缺失造成的。

三条对接路径怎么选

按团队现状，对接方式大致分三类。下表对比它们的适用场景、结果回传方式与自研工作量。

两条主要路径的差别在于改造位置：ZTF 只改执行方式，脚本内容基本不动；API 直连要把对接逻辑写进自研平台，换来字段与流程上的灵活度。数据库直连用于只读取数做报表尚可，写入要谨慎，它绕过了平台的字段校验、权限和操作日志，出问题难以定位。

路径一：用 ZTF 绑定脚本并回传结果

ZTF 是禅道配套的自动化测试执行工具，支持 Python、Ruby、Lua、Tcl、PHP、Perl、JavaScript、Shell、Bat 等语言编写的脚本，负责脚本组织、执行、结果比对与向平台回传。它的核心作用是把平台里的用例和自动化脚本一一绑定，执行结果提交回平台，执行失败的脚本可以自动创建 Bug。

配置执行节点

登录平台后台，进入「测试 → 执行 → 执行节点」添加节点：填写节点名称并勾选启用，指定该节点对应的产品模块、自动化脚本所在目录的绝对路径，以及执行前的依赖初始化命令（例如先安装依赖再执行，留空则跳过）。执行节点是调度脚本的运行载体，路径填错会直接导致后续同步找不到脚本。

同步脚本并绑定用例

在脚本根目录执行 ztf ci . -y --withCode true，工具会解析脚本中的元数据（用例标识、标题、步骤等注释），把脚本注册为平台里的自动化用例。同步完成后，在「测试 → 用例」列表可以看到带自动化标记的条目。新建用例时把类型选为「自动化」，在脚本字段中填写脚本文件名，即可建立绑定关系；已有用例也可以补充脚本引用。

在流水线里执行并回传

在持续集成任务中调用 ZTF 执行脚本即可。以接口测试为例：K6 脚本中保留 handleSummary 函数输出 summary.json，再由 ZTF 调用 K6 运行，执行结束后 ZTF 会分析生成的日志与摘要文件，转换成 XUnit 格式的测试结果并提交到平台。随后在「测试 → 用例」中按「单元测试」类型筛选，就能看到新建的测试单与结果详情。这条链路里，脚本用什么框架、怎么写，都不影响回传。

路径二：用 REST API 直连回传

自研平台或流水线脚本直接调接口，适合回传时要带上业务字段的场景。接口按 RESTful 风格设计，支持 GET、POST、PUT、DELETE 方法，流程分两步：先认证拿到凭证，再调用业务接口。

先解决认证

平台提供两种常见方式，按版本选择：

• 会话方式：先请求 api-getSessionID.json 取到 sessionID，再用 user-login.json 携带账号密码登录，之后每个请求都带上会话标识。
• Token 方式：调用 POST /api.php/v2/users/login，请求体提交 account 与 password，响应中返回 token，作为后续接口的凭证。

第三方应用集成还涉及签名：请求格式为 /api.php?m=模块&f=方法&参数&code=应用代号&time=时间戳&token=签名，签名算法为 md5(code + key + time)。时间戳只能用一次，下一次请求必须大于上一次，返回 330001 通常就是 token 算错或时间戳重复。握手阶段的问题基本都集中在这里。

结果落到哪条用例上

回传前把三个对应关系定清楚，后面才能追溯：

• 用例标识：用平台内的用例 ID 或脚本标识对上号，对不上时可能新增多余用例，或把结果写到错误的用例上。
• 执行批次：一次流水线执行对应一个测试单或执行记录，方便按版本回溯这一轮的通过情况。
• 结果状态：平台侧的执行结果分为通过、失败、阻塞、忽略四类，回传前先确认失败与阻塞的映射规则，避免自动化把失败写成忽略。

失败结果可以直接创建 Bug，并把触发它的用例记录在 Bug 的来源用例字段里。以后排查问题，可以从 Bug 直接跳回用例和执行记录，不必再去翻流水线日志。

私有化环境下的四个常见分支

私有化环境的问题往往不在接口本身，而在链路细节。

• 反向代理与证书：平台部署在内网 HTTPS 自定义证书下时，脚本侧要导入根证书或明确信任策略，否则请求在证书校验阶段就被拒绝。
• 编码：回传内容包含中文用例标题和步骤时统一用 UTF-8，脚本文件与请求体编码不一致会出现乱码。
• 重复回传：流水线重跑或断点续传可能造成同一批次重复写入，建议约定以执行批次号去重，重跑时覆盖或追加，而不是重复创建用例。
• 权限与审计：集成账号的可见范围决定它能读到哪些产品和用例，范围过大有风险，过小会让回传静默失败；接口返回与平台操作日志两头都留记录，排查更快。

回传结果怎么验证

配好之后用一次真实执行验证，而不是只看接口是否返回成功。

• 看用例侧：在「测试 → 用例」中按自动化或单元测试类型筛选，确认测试单、执行结果与用例状态和脚本输出一致。
• 看 Bug 侧：故意让一条用例失败，检查是否自动创建 Bug，来源用例是否指向正确。
• 看数据侧：把执行结果接入报表与研发效能度量，观察通过率、失败分布和回归覆盖的长期趋势。

三项都通过，说明这条回传通道已经可用。之后每次脚本变更、平台升级或网络调整，都回到这三处快速复查即可。私有化测试管理平台的对接质量，最终体现在用例状态与 Bug 记录能不能反映真实的测试结果，而不是接口调通的那一刻。