1. 概述
在TestRail中，我们经常需要根据特定的条件来管理和执行测试用例。一个常见的需求是，只将那些被标记为“可自动化”的测试用例添加到新的测试运行中。本教程将通过TestRail的RESTful API，演示如何实现这一目标。整个过程分为两个主要步骤：首先，从测试套件中筛选出符合条件的测试用例；其次，将这些筛选出的用例添加到指定的测试运行中。
2. 筛选测试用例：使用 get_cases API
要从TestRail套件中筛选出具有特定自定义字段（例如 custom_can_be_automated = true）的测试用例，我们需要使用 get_cases API 端点。
2.1 API 请求结构
get_cases 端点用于获取指定项目和测试套件中的所有测试用例。
GET index.php?/api/v2/get_cases/{project_id}&suite_id={suite_id}- {project_id}：你的TestRail项目ID。
- {suite_id}：你想要从中筛选用例的测试套件ID。
2.2 API 响应示例
执行上述查询后，TestRail会返回一个JSON格式的响应，其中包含测试套件中的所有用例及其详细信息。自定义字段通常以 custom_ 前缀命名。
"cases":[
{
"id":22478,
"title":"Test Case Steps (Text)",
"section_id":2347,
"template_id":1,
// ... 其他字段 ...
"suite_id":196,
"custom_automation_type":6,
"custom_can_be_automated":true, // 关注此自定义字段
"custom_preconds":"Test Case Step *TEXT* Precondition",
// ... 其他自定义字段 ...
},
{
"id":22494,
"title":"Automated Checkout",
"section_id":2347,
"template_id":9,
// ... 其他字段 ...
"suite_id":196,
"custom_automation_type":0,
"custom_can_be_automated":false, // 关注此自定义字段
"custom_preconds":null,
// ... 其他自定义字段 ...
}
]在上述响应中，我们可以看到 custom_can_be_automated 字段，它的值可以是 true 或 false。我们将根据这个字段来筛选用例。
2.3 筛选用例ID
获取到JSON响应后，你需要解析它并根据 custom_can_be_automated 字段的值来提取符合条件的用例ID。
使用 cURL 和 jq 进行筛选（示例）
如果你在命令行环境中使用 curl，可以结合 jq 工具来方便地解析和筛选JSON数据。
curl -H "Content-Type: application/json" \
-u "$TESTRAIL_EMAIL:$TESTRAIL_PASS" \
"$TESTRAIL_URL/index.php?/api/v2/get_cases/{project_id}&suite_id={suite_id}" | \
jq '[.[] | select(.custom_can_be_automated == true) | .id]'这个 curl 命令会：
- 向TestRail API发送 GET 请求，获取指定项目和套件的所有用例。
- 通过 jq 管道，筛选出 custom_can_be_automated 值为 true 的用例。
- 从筛选出的用例中，提取出它们的 id 字段，并输出一个包含所有符合条件ID的JSON数组。
在 JavaScript 环境中筛选
慧谷动力企业网站管理系统（www.elonr.com）中国企业网站达到50万用户，程序采用最简单易用的asp+access进行搭建，拥有完善的网站前后台，并特别根据企业网站的特点开发出独具特色的栏目和功能，让您能够在短时间内就拥有自己的企业网站，欢迎大家对演示网站进行测试，注意演示网站不能更改内容、修改和删除内容，否则会报错的，下载回去测试的用户可以修改添加删除的。
如果你在JavaScript中实现，你可以使用 fetch 或 axios 等库来发送HTTP请求，然后使用JavaScript的原生方法来解析和筛选JSON响应：
async function getAutomatedCaseIds(projectId, suiteId, testrailUrl, email, password) {
const auth = btoa(`${email}:${password}`); // Base64编码认证信息
const response = await fetch(`${testrailUrl}/index.php?/api/v2/get_cases/${projectId}&suite_id=${suiteId}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
'Authorization': `Basic ${auth}`
}
});
if (!response.ok) {
throw new Error(`Error fetching cases: ${response.status} ${response.statusText}`);
}
const cases = await response.json();
const automatedCaseIds = cases
.filter(testCase => testCase.custom_can_be_automated === true)
.map(testCase => testCase.id);
return automatedCaseIds;
}
// 示例调用
// getAutomatedCaseIds(1, 196, 'https://your-testrail-instance.testrail.io', 'your_email@example.com', 'your_password')
// .then(ids => console.log('Automated Case IDs:', ids))
// .catch(error => console.error(error));3. 将筛选出的用例添加到测试运行：使用 update_run API
获取到符合条件的用例ID列表后，下一步就是将它们添加到指定的测试运行中。这可以通过 update_run API 端点实现。
3.1 API 请求结构
update_run 端点用于修改现有测试运行的属性，包括其包含的测试用例。
POST index.php?/api/v2/update_run/{run_id}- {run_id}：你想要更新的测试运行ID。
3.2 请求体结构
要添加特定的测试用例，请求体应包含 include_all 字段设置为 false，并提供一个 case_ids 数组，其中包含你想要添加的用例ID。
{
"include_all": false,
"case_ids": [1, 2, 3, 5, 8]
}重要提示： 根据TestRail API文档，当您希望指定要包含的特定测试用例时，include_all 必须设置为 false。如果 include_all 为 true，则 case_ids 字段将被忽略或用于排除用例（取决于TestRail版本和配置），这与我们仅添加特定用例的目标不符。
3.3 POST 请求示例
使用 cURL 进行 POST 请求
curl -X POST \
"https://$TESTRAIL_URL/index.php?/api/v2/update_run/{run_id}" \
-H "Content-Type: application/json" \
-u "$TESTRAIL_EMAIL:$TESTRAIL_PASS" \
-d '{"include_all": false, "case_ids": [22478, 22499, 22501]}'在 JavaScript 环境中进行 POST 请求
async function addCasesToTestRun(runId, caseIds, testrailUrl, email, password) {
const auth = btoa(`${email}:${password}`); // Base64编码认证信息
const response = await fetch(`${testrailUrl}/index.php?/api/v2/update_run/${runId}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Basic ${auth}`
},
body: JSON.stringify({
include_all: false,
case_ids: caseIds
})
});
if (!response.ok) {
throw new Error(`Error updating test run: ${response.status} ${response.statusText}`);
}
return response.json(); // 通常会返回更新后的run对象
}
// 示例调用
// const automatedIds = [22478, 22499, 22501]; // 假设这是从getAutomatedCaseIds获取到的ID
// addCasesToTestRun(123, automatedIds, 'https://your-testrail-instance.testrail.io', 'your_email@example.com', 'your_password')
// .then(run => console.log('Test Run updated successfully:', run))
// .catch(error => console.error(error));3.4 成功确认
如果操作成功，TestRail API将返回一个状态码为 200 的响应，表示测试运行已成功更新。
4. 注意事项与总结
- API 认证： 所有的API请求都需要进行认证。示例中使用了HTTP Basic Auth（邮箱和密码），你也可以使用TestRail提供的API Key进行认证，这通常更安全。
- 自定义字段名称： TestRail中自定义字段的API名称通常以 custom_ 前缀开头。请确保你使用的字段名与TestRail中实际的自定义字段标识符一致。
- 错误处理： 在实际应用中，务必对API响应进行错误检查。例如，检查HTTP状态码是否为 200，并处理可能的错误消息。
- 语言适应性： 本教程提供了 curl 和 JavaScript 的示例。你可以根据你所使用的编程语言和HTTP客户端库，将这些示例适配到你的环境中。核心逻辑是发送正确的HTTP请求和解析JSON响应。
- API 速率限制： TestRail API可能有速率限制。在进行大量请求时，请注意控制请求频率，避免被服务器暂时阻止。
通过遵循上述步骤，你可以有效地利用TestRail API来自动化测试用例的管理流程，实现根据自定义字段筛选并添加到测试运行的需求，从而提高测试管理的效率和灵活性。
5. 参考链接
- 更新测试运行 (Update Run)： https://www.php.cn/link/7966a1b638bd6906654fd9190feeb801
- 获取测试用例 (Get Cases)： https://www.php.cn/link/31beb41824b307d9f0deb076f8f9ee3b
