QTM4J: Search Linked Test Cases in Test Cycle
qtm4j_search_linked_test_cases_in_test_cycleSearch and filter test case executions linked to a QTM4J test cycle. Locate failed or blocked tests, apply filters by result, priority, status, or assignee, and paginate results.
Instructions
Search and filter test case executions linked to a QTM4J test cycle. Supports pagination, field selection, sorting, and rich filter criteria.
Toolset: Test Cycles
Parameters:
cycleKey (string) required: Test Cycle key in '{PROJECT_KEY}-TR-{id}' format (e.g., 'SCRUM-TR-1'). Resolved to the internal cycle UID automatically.
fields (array): Fields to include in each result object. Allowed: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, seqNo, latestTcExecutionId, customFields, flakyScore, passRateScore. Omit to return all fields.
maxResults (number): Maximum results per page (1-100). Default: 50. (default: 50)
sort (string): Sort pattern in 'field:asc|desc' format (e.g., 'key:desc'). Allowed sort fields: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, flakyScore, passRateScore.
startAt (number): Zero-indexed offset for pagination. Default: 0. (default: 0)
filter (object): Optional filter criteria to narrow down results. projectId is auto-filled from the active project context.
Output Description: JSON object with total (total matching executions), startAt, maxResults, and data (array of test case execution objects for this page).
Use Cases: 1. List all test cases linked to a test cycle 2. Find failed or blocked test case executions in a cycle 3. Search for test cases in a cycle by execution result (Pass, Fail, Blocked) 4. Filter test cases in a cycle by priority or status 5. Retrieve test cases assigned to a specific executor in a cycle 6. Get test cases with defects in a cycle 7. Paginate through large test cycle execution lists 8. Request only specific fields to reduce response size
Examples:
List all test cases in a cycle
{
"cycleKey": "SCRUM-TR-1"
}Expected Output: Paginated list of test case executions in the cycle (first 50 results)
Find failed test cases in a cycle
{
"cycleKey": "SCRUM-TR-1",
"filter": {
"executionResult": [
"Fail"
]
},
"fields": [
"key",
"summary",
"executionResult",
"priority"
]
}Expected Output: Test case executions with Fail result
Search with pagination and sort
{
"cycleKey": "SCRUM-TR-5",
"maxResults": 25,
"startAt": 0,
"sort": "key:asc",
"filter": {
"status": [
"To Do"
]
}
}Expected Output: First 25 To Do test cases in the cycle sorted by key ascending
Filter by execution assignee and environment
{
"cycleKey": "SCRUM-TR-2",
"filter": {
"executionAssignee": [
"5b10a2844c20165700ede21f"
],
"environment": [
"Staging"
]
},
"fields": [
"key",
"summary",
"executionResult",
"environment",
"actualTime"
]
}Expected Output: Test cases assigned to the specified user in the Staging environment
Hints: 1. PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project. 2. CYCLE KEY FORMAT: '{PROJECT_KEY}-TR-{id}' — e.g. 'SCRUM-TR-1'. Resolved to internal UID automatically. 3. projectId in filter is auto-filled from the active project context — do not set it manually. 4. fields is sent as a query parameter; filter is sent in the request body. 5. Allowed fields: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, seqNo, latestTcExecutionId, customFields, flakyScore, passRateScore. 6. Allowed sort fields: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, flakyScore, passRateScore. 7. Date range format for filter fields: 'dd/mmm/yyyy,dd/mmm/yyyy' (e.g., '01/Jan/2024,31/Mar/2024'). 8. maxResults defaults to 50, maximum is 100. Use startAt to paginate. 9. executionResult filter accepts values like 'Pass', 'Fail', 'Blocked', 'Unexecuted'.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort pattern in 'field:asc|desc' format (e.g., 'key:desc'). Allowed sort fields: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, flakyScore, passRateScore. | |
| fields | No | Fields to include in each result object. Allowed: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, seqNo, latestTcExecutionId, customFields, flakyScore, passRateScore. Omit to return all fields. | |
| filter | No | Optional filter criteria to narrow down results. projectId is auto-filled from the active project context. | |
| startAt | No | Zero-indexed offset for pagination. Default: 0. | |
| cycleKey | Yes | Test Cycle key in '{PROJECT_KEY}-TR-{id}' format (e.g., 'SCRUM-TR-1'). Resolved to the internal cycle UID automatically. | |
| maxResults | No | Maximum results per page (1-100). Default: 50. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Test case execution entries on this page. | |
| total | Yes | Total test case executions matching the filter (across all pages). | |
| startAt | Yes | Offset of this page. | |
| maxResults | Yes | Page size used for this response. |