常见问题指南

问题1：上传结果后，TestRail中找不到对应的测试用例。

原因：这一般发生在代码优先的集成方式中，CLI或脚本无法自动创建新用例。

指南：在运行 trcli 时，尝试添加 --auto-create-cases 或类似的参数。具体请查阅所用版本CLI的帮助文档（trcli parse_junit --help）。

问题2：API返回 429 Too Many Requests 错误。

原因：短时间内发送了过多请求，触发了TestRail Cloud的速率限制。

指南：在代码中实现 重试思路 和 指数退避。当收到429响应时，程序应等待 Retry-After 头中指定的秒数后重试。同时，尽量使用批量操作接口。

问题3：包含附件（如截图、日志）的请求失败。

原因：上传附件需使用 multipart/form-data 编码，其处理方式和标准JSON请求不同。

指南：保证请求的 Content-Type 正确设置为 multipart/form-data，并严格按照API文档构造请求体。使用社区SDK一般能简化此操作。

问题4：权限不足 (403 Forbidden)。

原因：用于认证的用户账号可能没有执行该操作的角色或权限。

指南：请在TestRail管理后台（Administration > Users & Roles）检查该用户的角色及其拥有的项目权限，保证其有修改测试运行、添加测试结果等必要权限。

建议

从安全和管理角度，始终优先使用API密钥而不是密码进行认证。

尽量使用支持批量处理的API端点（如 add_results_for_cases），以减少请求数量，规避速率限制。

在代码中实现错误处理和重试机制，特别是针对 429 和 5xx 这类临时性错误。

绝不要将 API 密钥、用户名或密码硬编码在源代码中。应使用环境变量或 CI/CD 平台的 Secrets 管理功能来安全地注入这些信息。

对于标准的结果上传场景，CLI是比直接调用API更简单、更高效的解决方案。