QTM4J: Create Test Cycle
qtm4j_create_test_cycleCreate a test cycle in a QTM4J project with priority, status, labels, components, and planned dates. Automatically resolves names and uses the default folder for test planning.
Instructions
Create a new test cycle in a QTM4J project. Supports auto-resolving human-readable names for priority and status. projectId is injected automatically from the active project context.
Toolset: Test Cycles
Parameters:
summary (string) required: Short title of the test cycle. Must not be blank. Max 255 chars.
description (string): Detailed description of the test cycle. Max 65 535 characters.
priority (string): Priority name (e.g., 'High', 'Medium', 'Low'). Auto-resolved to ID.
status (string): Status name (e.g., 'To Do', 'In Progress', 'Done'). Auto-resolved to ID.
folderId (number): Numeric folder ID where the test cycle will be created. If omitted, the cycle is created in the 'MCP Generated' folder automatically.
assignee (string): Assignee account ID
reporter (string): Reporter account ID
labels (array): List of label names (e.g., ['Release_1', 'Sprint 1']). Auto-resolved to IDs.
components (array): List of component names (e.g., ['UI', 'Cloud']). Auto-resolved to IDs.
plannedStartDate (string): Planned start date. Format: 'dd/MMM/yyyy HH:mm' e.g. '10/May/2026 00:00'. Must be ≤ plannedEndDate when both are provided.
plannedEndDate (string): Planned end date. Format: 'dd/MMM/yyyy HH:mm' e.g. '15/May/2026 00:00'. Must be ≥ plannedStartDate when both are provided.
Output Description: JSON object with the new test cycle's id and key (e.g. 'TRWT-TR-218'). Warnings included if any fields were skipped.
Use Cases: 1. Create a test cycle with summary, priority, status, labels, or components 2. Set planned start and end dates on a new test cycle
Examples:
Create a simple test cycle (project must be set via set_project_context first)
{
"summary": "Smoke Test Cycle"
}Expected Output: Test cycle created with key 'SCRUM-TR-xxx'
Create a test cycle with priority, status, labels, and components
{
"summary": "Regression Suite – Sprint 42",
"description": "End-to-end regression covering payment and checkout modules.",
"priority": "High",
"status": "To Do",
"labels": [
"Release_1",
"Sprint 1"
],
"components": [
"UI",
"Cloud"
],
"plannedStartDate": "10/May/2026 00:00",
"plannedEndDate": "15/May/2026 00:00"
}Expected Output: Test cycle created with resolved priority, status, labels, and components
Hints: 1. PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project. 2. If any priority, status, label, or component name cannot be resolved, the cycle is still created but a warning is returned. Suggest the closest available value from the set_project_context response and ask the user to confirm before retrying. 3. FOLDER ID: folderId is optional. If omitted, defaults to the 'MCP Generated' folder. To place in a specific folder, ask the user to right-click the target folder in QTM4J and select 'Copy Folder Id' — never try to look it up. 4. Date format: 'dd/MMM/yyyy HH:mm' e.g. '10/May/2026 00:00'. Month must be capitalised. plannedStartDate must be ≤ plannedEndDate.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| labels | No | List of label names (e.g., ['Release_1', 'Sprint 1']). Auto-resolved to IDs. | |
| status | No | Status name (e.g., 'To Do', 'In Progress', 'Done'). Auto-resolved to ID. | |
| summary | Yes | Short title of the test cycle. Must not be blank. Max 255 chars. | |
| assignee | No | Assignee account ID | |
| folderId | No | Numeric folder ID where the test cycle will be created. If omitted, the cycle is created in the 'MCP Generated' folder automatically. | |
| priority | No | Priority name (e.g., 'High', 'Medium', 'Low'). Auto-resolved to ID. | |
| reporter | No | Reporter account ID | |
| components | No | List of component names (e.g., ['UI', 'Cloud']). Auto-resolved to IDs. | |
| description | No | Detailed description of the test cycle. Max 65 535 characters. | |
| plannedEndDate | No | Planned end date. Format: 'dd/MMM/yyyy HH:mm' e.g. '15/May/2026 00:00'. Must be ≥ plannedStartDate when both are provided. | |
| plannedStartDate | No | Planned start date. Format: 'dd/MMM/yyyy HH:mm' e.g. '10/May/2026 00:00'. Must be ≤ plannedEndDate when both are provided. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Opaque permanent identifier of the created test cycle. Use this in all subsequent API calls. | |
| key | Yes | Human-readable project-scoped key in format '<PROJECT_KEY>-TR-<number>'. e.g. 'TRWT-TR-218'. |