QTM4J: Search Test Cycles

Search for test cycles in a QTM4J project by status, owner, folder, date range, or keyword. projectId is injected automatically from the active project context.

Toolset: Test Cycles

Parameters:

• filter (object): Filter criteria — multiple fields are combined with AND; multiple values within one field use OR.

• fields (array): Fields to include in each result object. If omitted, server returns its default set (NOTE: plannedStartDate and plannedEndDate are NOT in the default response — include them explicitly when needed). Available fields: key, summary, description, status, priority, assignee, reporter, isAutomated, plannedStartDate, plannedEndDate, labels, components, fixVersions, sprint, defectCount, estimatedTime, actualTime, created, updated. Example: ['key', 'summary', 'status', 'assignee', 'plannedStartDate', 'plannedEndDate']

• startAt (number): Zero-indexed offset for pagination (URL query param). Default: 0. (default: 0)

• maxResults (number): Number of results per page (URL query param). Default: 20. Maximum: 100. To page through results, increment startAt by 20 until startAt >= total. (default: 20)

• sort (string): Sort pattern sent as a URL query param. Format: 'fieldName:order'. Default: 'key:asc'. Order values: 'asc' (lowest/oldest first) or 'desc' (highest/newest first). Sortable fields: key, summary, status, plannedStartDate, plannedEndDate, defectCount. Examples: 'key:asc', 'plannedStartDate:desc' (default: "key:asc")

Output Description: JSON object with total (matching cycles across all pages), startAt, maxResults, and data (array of test cycle objects for this page). Each item always has id and key. Other fields depend on what was requested via the fields parameter.

Use Cases: 1. Find test cycles by status, priority, assignee, reporter, or folder 2. Find test cycles by planned execution date range (plannedStartDate / plannedEndDate) 3. Find test cycles created or updated within a date range (createdOn / updatedOn) 4. Search test cycles by keyword across key, summary, and description 5. Paginate, sort, and select specific response fields

Examples:

1. Find all in-progress and to-do cycles

{
  "filter": {
    "status": [
      "In Progress",
      "To Do"
    ]
  }
}

Expected Output: Paginated list of matching test cycles

2. Find cycles owned by a specific user

{
  "filter": {
    "assignee": [
      "5b10a2844c20165700ede21f"
    ]
  }
}

Expected Output: Test cycles assigned to that user

3. Find cycles with planned start date in a range, requesting date fields explicitly

{
  "filter": {
    "plannedStartDate": "01/Apr/2026,30/Apr/2026"
  },
  "fields": [
    "key",
    "summary",
    "status",
    "assignee",
    "plannedStartDate",
    "plannedEndDate"
  ]
}

Expected Output: Cycles with planned start date in April 2026 including date fields

4. Keyword search with sort, pagination, and selected fields

{
  "filter": {
    "searchText": "regression"
  },
  "fields": [
    "key",
    "summary",
    "status",
    "assignee"
  ],
  "sort": "plannedStartDate:asc",
  "startAt": 0,
  "maxResults": 25
}

Expected Output: Cycles matching 'regression', sorted by planned start date

5. Find cycles created last week

{
  "filter": {
    "createdOn": "01/May/2026,07/May/2026"
  },
  "fields": [
    "key",
    "summary",
    "status",
    "assignee"
  ],
  "sort": "key:asc"
}

Expected Output: Test cycles created between 01 May and 07 May 2026

6. Find high-priority cycles updated recently by reporter

{
  "filter": {
    "priority": [
      "High"
    ],
    "reporter": [
      "5b10a2844c20165700ede21f"
    ],
    "updatedOn": "01/May/2026,21/May/2026"
  },
  "fields": [
    "key",
    "summary",
    "status",
    "priority",
    "assignee"
  ]
}

Expected Output: High-priority cycles updated in May 2026 reported by that user

7. All filters combined with explicit field selection

{
  "filter": {
    "status": [
      "In Progress"
    ],
    "priority": [
      "High",
      "Medium"
    ],
    "assignee": [
      "5b10a2844c20165700ede21f"
    ],
    "folderId": 109987,
    "plannedStartDate": "02/Apr/2026,15/May/2026",
    "searchText": "regression"
  },
  "fields": [
    "key",
    "summary",
    "status",
    "priority",
    "assignee",
    "plannedStartDate"
  ],
  "sort": "plannedStartDate:asc",
  "maxResults": 25
}

Expected Output: Test cycles matching all specified filters with selected fields

Hints: 1. PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project. 2. SUPPORTED FILTER FIELDS: status, priority, assignee, reporter, folderId, labels, components, plannedStartDate, plannedEndDate, searchText, createdOn, updatedOn, isAutomated, aiGenerated. Do NOT use any other filter field names. 3. DATE FILTERS: createdOn = creation date; updatedOn = last-updated date; plannedStartDate / plannedEndDate = planned execution window. Format: 'dd/MMM/yyyy,dd/MMM/yyyy' e.g. '01/May/2026,21/May/2026'. Month is case-sensitive. 'Created last week' → createdOn, NOT plannedStartDate. 4. FIELDS: Pass as an array to select what to return. plannedStartDate and plannedEndDate are NOT in the default response — include them explicitly. Available: key, summary, description, status, priority, assignee, reporter, isAutomated, plannedStartDate, plannedEndDate, labels, components, fixVersions, sprint, defectCount, estimatedTime, actualTime, created, updated. 5. REQUEST STRUCTURE: filter → request body; fields, sort, startAt, maxResults → URL query params. 6. SORT: Allowed fields: key, summary, status, plannedStartDate, plannedEndDate, defectCount. Format: 'fieldName:asc' or 'fieldName:desc' e.g. 'plannedStartDate:asc'. 7. FOLDER ID: folderId in fields.testCycle and fields.testCase is a numeric ID. Tell the user they can get it by right-clicking the target folder in QTM4J and selecting 'Copy Folder Id'. Always ask the user for the numeric ID directly — never try to look it up.