migrate-to-testomatio

迁移到 Testomat.io

通过 UI 导入、API 迁移脚本或 CSV 转换器，将测试套件从其他 TMS 迁移到 Testomat.io。

发现迁移范围（先询问）

• 选择迁移策略前，询问用户需要迁移哪些内容：仅测试用例，还是还包括运行历史/结果、附件/截图、自动化运行、里程碑、缺陷/问题关联、自定义字段。
• 不要默认只迁移测试用例。明确确认：“您只需要迁移测试用例，还是还需要迁移运行记录/结果和附件？”
• 记录回答并据此选择迁移路径：超出测试用例范围的任何内容都必须使用 API 脚本路径（CSV 无法承载这些内容）。

选择策略

• 确定来源：只有在用户未提供时，才询问 TMS 名称。
• 主动了解最佳获取方式：只要迁移范围有此需求或数据集较大，优先使用实时 API 访问，而不是 CSV 导出。CSV 是快速备用方案，而非完整迁移的默认方式。
• 尽早询问 API 访问权限：“您是否拥有源实例的管理员/API 访问权限（URL + API token）？”如果有，即使也有 CSV 导出文件，也使用 API 脚本路径。
• 确定输入来源：具有 API 访问权限的实时实例，或导出的 CSV/XLSX 文件。
• 根据来源选择路径：
  • TestRail + API 访问权限、测试数 >1000 或需要附件/运行记录：使用 API 迁移脚本（TESTRAIL_MIGRATION.md）。
  • TestRail、测试数 <1000、无附件：使用内置 UI 导入（通过 Imports 窗口中的 CSV 或 TestRail API 选项）。
  • Testmo + API 访问权限，或需要运行记录/结果/附件：通过 Testmo REST API 进行 API 迁移（TESTMO_MIGRATION.md，参考 TestRail 脚本编写）。
  • XRay (Jira)：使用迁移脚本生成 Testomat.io CSV（XRAY_MIGRATION.md）。
  • Testmo、QMetry、TestCaseLabs、Allure TestOps 导出文件；仅迁移测试用例且无附件：使用 CSV 转换器脚本（CSV_MIGRATION.md）。
  • Qase、QTest、Zephyr 或其他 TMS 导出文件：直接通过 UI 导入 CSV，不使用脚本（CSV_MIGRATION.md）。
  • 不受支持或支持异常的 TMS：构建自定义转换器或 API 脚本（CUSTOM_MIGRATION.md）。
• CSV 的限制：CSV/XLSX 只能迁移测试用例，无法迁移运行结果/历史记录、附件/截图、自动化运行或里程碑。如果用户需要其中任何内容，请切换到 API 迁移路径。
• 如果需要截图或文件附件，请使用 API 脚本路径；CSV 导入无法创建附件。
• 切勿臆造转换器的输出列；转换后的文件始终以格式 Testomat.io 导入。
• API 脚本需要源系统凭据和 Testomat.io General Token；切勿将 token 硬编码，应使用 .env。

范围

• 默认迁移范围为测试用例；运行记录、结果/历史记录、附件、自动化运行、里程碑、缺陷和需求均为可通过 API 迁移的可选内容 — 确认用户需要哪些内容（参见“发现迁移范围”）。
• 只有在上传测试用例后，才能上传运行结果。
• Testomat.io 没有对应项的用户字段不能被静默丢弃：应将其映射到 Labels/Tags，或扩展转换器脚本。

工作流

• 创建一个空的 Testomat.io 项目作为导入目标。
• 获取源数据访问权限：API 凭据（TestRail/XRay/Testmo 路径）或导出文件（CSV 路径）。
• 按选择的路径执行：
  • API 脚本路径：将仓库克隆到临时目录，配置 .env，先执行 dry-run，再运行完整迁移。
  • CSV 路径：如果有转换器，则先转换，再通过 UI 导入。
  • 自定义路径：先构建转换器或 API 脚本，再按上述对应路径操作。
• 所有 UI 导入最终均按以下步骤进行：Tests 标签页 > (...) > Import from other TMS > Import > Import from CSV > 选择源格式 > Choose file > Create。
• 验证：检查 Tests 页面的数量、套件嵌套结构、步骤格式、优先级/标签。
• 提供迁移后的清理操作：detect-duplicate-test-cases、improve-test-cases。

参考资料

• TESTRAIL_MIGRATION.md — TestRail 界面选项、API 脚本环境变量、测试运行和附件迁移。
• TESTMO_MIGRATION.md — Testmo REST API 迁移（测试用例、测试运行、结果、附件），参考 TestRail 脚本构建。
• XRAY_MIGRATION.md — XRay 令牌提取、环境变量、按文件夹导入。
• CSV_MIGRATION.md — 转换器脚本、直接通过界面导入、自定义 Testomat.io XLSX 列。
• CUSTOM_MIGRATION.md — 针对不受支持或支持异常的 TMS，使用自定义转换器或 API v2 脚本。