QMetry: Update Test Case

Update an existing QMetry test case OR create a new version by tcID and tcVersionID, with auto-resolution from entityKey.

Toolset: Test Cases

Parameters:

• projectKey (string): Project key - unique identifier for the project (default: "default")

• tcID (number) required: Test Case numeric ID. CRITICAL: the parameter name is 'tcID' — do NOT use 'testCaseId', 'testCaseID', 'tcId', or other variants. Accepts a string or number. This is the internal numeric identifier, not the entity key like 'MAC-TC-1684'. You can get this ID from test case search results or by using filters.

• tcVersionID (number) required: Test Case version number. This is the internal numeric identifier for the version.

• tcVersion (number): Test Case version number (required when withVersion=true for creating new version). This is the current version number from which a new version will be created.

• withVersion (boolean): Pass 'true' if you want to create a new version of the test case with incremented version number. When true, a new version is created (e.g., if current version is 2, new version 3 is created). When false or omitted, updates the existing version specified by tcVersionID. IMPORTANT: Always send proper tcVersionID to identify which version the request is for.

• versionComment (string): Comment or description for the new version (used only when withVersion=true). Helps track what changed in this new version. Example: 'Updated test steps for new requirements'

• notruncurrent (boolean): Flag to control execution behavior for current version when creating a new version. Used in conjunction with withVersion=true.

• notrunall (boolean): Flag to control execution behavior for all versions when creating a new version. Used in conjunction with withVersion=true.

• folderPath (string): Folder path for test suites - SYSTEM AUTOMATICALLY SETS TO ROOT. Leave empty unless you want specific folder. System will automatically use empty string "" (root directory). Only specify if user wants specific folder like "Automation/Regression". (default: "")

• scope (string): Scope of the operation - defines the context for data retrieval. Common values: 'project' (default), 'folder', 'release', 'cycle'. Applies to any entity type being fetched or operated upon. (default: "project")

• isStepUpdated (boolean): Set to true when steps are being added, updated, or removed. Required when including 'steps' or 'removeSteps' arrays.

• steps (array)

• removeSteps (array)

• name (string)

• priority (number)

• component (array)

• owner (number)

• testCaseState (number)

• testCaseType (number)

• estimatedTime (number): Estimated execution time in seconds. Example: 7200 for 2 hours

• executionMinutes (number)

• testingType (number)

• description (string)

• updateOnlyMetadata (boolean): Set to true to update only metadata fields without touching test steps. When true, steps and removeSteps are ignored.

• udfFields (record<string, union>): Flat UDF field values. Keys = UDF field names from 'Fetch UDF Layout'. Values depend on fieldTypeName: STRING/LARGETEXT: string, NUMBER: number, DATETIMEPICKER: date string ('14-08-2026'), LOOKUPLIST: numeric ID, MULTILOOKUPLIST: array of IDs [101, 102], CASCADINGLIST: { parent: 101, child: 102 }. Call 'Fetch UDF Layout' with entityType + pageName='ADD' to discover available fields and list option IDs.

• UDF (record<string, object>): UDF wrapper required for update operations. Keys = UDF field names. Each value must include fieldID (from 'Fetch UDF Layout' with pageName='DETAIL') and value. Also set matching flat key in udfFields for the LOOKUPLIST Alias display. Example: { custom_text: { fieldID: 1001, value: 'new value' } }

Output Description: JSON object containing the test case ID, version ID, summary, update/creation metadata. When withVersion=true (version creation), response includes new version number and version ID. When withVersion=false/omitted (existing version update), response includes updated fields confirmation.

Use Cases: 1. Update test case summary (name) 2. Change priority, owner, or state of a test case 3. Edit, add, or remove test steps 4. Update only metadata (no steps) 5. Create a new version of a test case (withVersion=true) 6. Update a specific version of a test case (without withVersion flag) 7. Bulk update using entityKey auto-resolution 8. Modify test case description or estimated time 9. Change test case type or component 10. Update testing type or custom fields 11. Update, add and remove test case steps 12. Version control for test case evolution tracking

Examples:

1. Update test case summary (existing version update)

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "name": "MAC Test11"
}

Expected Output: Test case summary updated. tcID and tcVersionID auto-resolved from entityKey. Only 'name' field changed. Version remains the same.

2. Create NEW VERSION with updated summary and description

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Add two numbers 2 v2",
  "description": "Test Description version 2",
  "withVersion": true,
  "versionComment": "version 2 comment add",
  "notruncurrent": true,
  "notrunall": true
}

Expected Output: New version created (version 2). Test case now has incremental version with updated summary and description. Original version 1 remains unchanged.

3. Create NEW VERSION with all metadata fields (release, cycle, priority, owner, etc.)

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Facebook Login Validation Failed update from MCP V2",
  "description": "Existing description V2",
  "priority": 2355751,
  "testcaseOwner": 6963,
  "testCaseState": 2355753,
  "testCaseType": 2355762,
  "estimatedTime": 7200,
  "withVersion": true,
  "versionComment": "Created version 2 with updated metadata",
  "notruncurrent": true,
  "notrunall": true,
  "folderPath": 602290,
  "scope": "project"
}

Expected Output: New test case version 2 created with updated summary, description, priority (High), owner (umang.savaliya), state, type, and estimated time (2 hours). Version comment added for tracking.

4. Update EXISTING VERSION 2 (not creating new version)

{
  "tcID": 4572654,
  "tcVersionID": 5514385,
  "name": "Updated version 2 name",
  "priority": 2355752
}

Expected Output: Version 2 updated with new name and priority. No new version created because withVersion flag is not set. This is a normal update of existing version.

5. Update priority to High and owner to john.doe (existing version)

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "priority": 505015,
  "testcaseOwner": 6963
}

Expected Output: Priority and owner updated. Field IDs auto-resolved from project info. tcID/tcVersionID resolved from entityKey. Existing version modified.

6. Update steps (edit, add, remove) - existing version

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "steps": [
    {
      "orderId": 1,
      "description": "Step 22",
      "inputData": "Input 22",
      "expectedOutcome": "Outcome 22",
      "tcStepID": 3014032
    },
    {
      "orderId": 2,
      "description": "Step3",
      "inputData": "Input 3",
      "expectedOutcome": "Outcome 3"
    }
  ],
  "removeSteps": [
    {
      "tcStepID": 3014031,
      "description": "Step 1",
      "orderId": 1
    }
  ],
  "isStepUpdated": true
}

Expected Output: Steps updated: Step 22 edited (tcStepID preserved), Step3 added (no tcStepID), Step 1 removed. tcID/tcVersionID auto-resolved. Existing version modified.

7. Create NEW VERSION with updated steps

{
  "tcID": 4572654,
  "tcVersionID": 5514384,
  "tcVersion": 1,
  "name": "Add two numbers 2 v2",
  "steps": [
    {
      "orderId": 1,
      "description": "I and u have a calculator",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001791
    },
    {
      "orderId": 2,
      "description": "I add 41 and 31",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001793
    },
    {
      "orderId": 3,
      "description": "the result should be 72",
      "inputData": "",
      "expectedOutcome": "",
      "tcStepID": 38001792
    }
  ],
  "withVersion": true,
  "versionComment": "version 2 with preserved steps",
  "notruncurrent": true,
  "notrunall": true,
  "isStepUpdated": true
}

Expected Output: New version 2 created with all steps from version 1 preserved. Steps carry forward with their tcStepID values. Version comment added for tracking.

8. Update only metadata (no steps) - existing version

{
  "tcID": 4519260,
  "tcVersionID": 5448492,
  "updateOnlyMetadata": true,
  "name": "New Name"
}

Expected Output: Metadata updated only. Steps unchanged. tcID/tcVersionID auto-resolved. Existing version modified.

9. Create NEW VERSION from existing version 2 with updated steps (working payload for linked test cases)

{
  "tcID": 4594145,
  "tcVersionID": 5536706,
  "tcVersion": 2,
  "name": "Mock Test Case - E-commerce Checkout Flow - v3",
  "steps": [
    {
      "orderId": 1,
      "description": "Open browser and navigate to e-commerce website",
      "expectedOutcome": "Homepage loads successfully with product catalog",
      "inputData": "URL: https://example-shop.com",
      "tcStepID": 38129471
    },
    {
      "orderId": 2,
      "description": "Search for product",
      "expectedOutcome": "Search results display relevant products",
      "inputData": "Search term: 'wireless headphones'",
      "tcStepID": 38129475
    },
    {
      "orderId": 3,
      "description": "Select product and add to cart",
      "expectedOutcome": "Product added to cart, cart counter increments",
      "inputData": "Click 'Add to Cart' button",
      "tcStepID": 38129472
    },
    {
      "orderId": 4,
      "description": "Proceed to checkout",
      "expectedOutcome": "Checkout page displays with cart summary",
      "inputData": "Click cart icon and 'Proceed to Checkout'",
      "tcStepID": 38129473
    },
    {
      "orderId": 5,
      "description": "Complete payment",
      "expectedOutcome": "Order confirmation page displayed",
      "inputData": "Fill payment details and submit",
      "tcStepID": 38129474
    },
    {
      "orderId": 6,
      "description": "Verify order confirmation email received",
      "expectedOutcome": "Email with order details received in inbox",
      "inputData": "Check email account for confirmation"
    },
    {
      "orderId": 7,
      "description": "Check order status in account dashboard",
      "expectedOutcome": "Order status shows as 'Processing' with tracking information",
      "inputData": "Navigate to My Orders section"
    }
  ],
  "withVersion": true,
  "versionComment": "Created version 3: Added 2 new verification steps (email and order status check)",
  "notrunall": false,
  "notruncurrent": false,
  "scope": "project"
}

Expected Output: New version 3 created successfully from version 2. Test case now has 7 steps (5 preserved + 2 new). Key: tcVersion=2 was used because version 2 already existed in system. notrunall and notruncurrent both false (not true). Result shows tcVersion: 3 in response with new tcVersionID.

Hints: 1. === DEFAULT VALUES — APPLY FOR ANY UNSET FIELD === 2. Call 'Fetch UDF Layout' with entityType='TC', pageName='DETAIL' before updating. 3. defaultValues (from Fetch UDF Layout): { fieldName: defaultValueId } — sweep ALL entries. 4. For EACH key in defaultValues: if user did not explicitly provide that field → include it in payload with the default value. 5. This applies to non-mandatory fields too (e.g. priority, estimatedTime). Omitting them = data loss. 6. === END DEFAULT VALUES === 7. 8. === DATE FORMAT CHECK (MANDATORY — EVERY UPDATE REQUEST) === 9. ALWAYS call 'Fetch QMetry Project Info' before every update request — not only when the user explicitly mentions a date. 10. Any UDF field could be a DATETIMEPICKER. Wrong format causes QMetry to silently discard the field value (API returns success but value is NOT stored — no error). 11. STEP 1: From project info, read dateTimeFormatID (e.g. 3). 12. STEP 2: Find entry in dateTimeFormatNew where id === dateTimeFormatID → read its unique_value (e.g. 'yyyy-MM-dd'). 13. STEP 3: unique_value pattern: yyyy=4-digit year, MM=2-digit month (01-12), dd=2-digit day, MMM=3-letter month (Jan/Feb/...). 14. Example: id=1 → MM-dd-yyyy → '10-25-2000' | id=2 → dd-MM-yyyy → '25-10-2000' | id=3 → yyyy-MM-dd → '2000-10-25' | id=4 → dd-MMM-yyyy → '25-Oct-2000' 15. STEP 4: For EVERY DATETIMEPICKER field in the payload: parse any user-provided date and re-format it using the active unique_value pattern before sending. 16. NEVER assume a date format — always derive it from dateTimeFormatID. Wrong format = silent data loss. 17. === END DATE FORMAT CHECK === 18. 19. CRITICAL - VERSION CREATION vs UPDATE DISTINCTION: 20. This tool supports TWO MODES using the SAME API endpoint: 21. 22. MODE 1: CREATE NEW VERSION (withVersion=true) 23. - Purpose: Create an incremental version of the test case (e.g., v1 → v2, v2 → v3) 24. - When to use: User explicitly asks to 'create new version', 'create version 2', 'increment version' 25. - Required fields: tcID, tcVersionID (of source version), tcVersion (current version number), withVersion=true 26. - Optional but recommended: versionComment (track what changed), notruncurrent, notrunall 27. - Behavior: Creates a NEW test case version with incremented version number. Source version remains unchanged. 28. - Example: If current version is 1, setting withVersion=true creates version 2 29. - Use cases: Updating test case for new requirements, creating variants for different scenarios, version control 30. 31. MODE 2: UPDATE EXISTING VERSION (withVersion=false or omitted) 32. - Purpose: Modify fields of an EXISTING version without creating a new version 33. - When to use: User asks to 'update test case', 'modify version X', 'change summary' (without mentioning new version) 34. - Required fields: tcID, tcVersionID (of version to update) 35. - Do NOT include: withVersion flag, versionComment, tcVersion 36. - Behavior: Updates the specified version in-place. No new version is created. 37. - Example: Updating version 2's summary - only version 2 is modified, no version 3 is created 38. - Use cases: Fixing typos, updating metadata, modifying steps in existing version 39. 40. CRITICAL FIELD UNDERSTANDING: 41. - tcVersionID: The VERSION ID (numeric identifier) of the version you're working with 42. - tcVersion: The VERSION NUMBER (1, 2, 3, etc.) - only needed when withVersion=true 43. - tcID: The TEST CASE ID (remains same across all versions) 44. - Example: Test case VKMCP-TC-10 (tcID: 4572654) has version 1 (tcVersionID: 5514384, tcVersion: 1) 45. - When creating version 2 from version 1: Send tcVersionID=5514384 (source), tcVersion=1 (current), withVersion=true 46. 47. HOW TO DETERMINE WHICH MODE: 48. - User says 'create new version' → MODE 1 (withVersion=true) 49. - User says 'create version 2' → MODE 1 (withVersion=true) 50. - User says 'update test case with new version' → MODE 1 (withVersion=true) 51. - User says 'update test case VKMCP-TC-10 summary' → MODE 2 (no withVersion, update existing version) 52. - User says 'update version 2 summary' → MODE 2 (no withVersion, update existing version 2) 53. - User says 'change priority of version 1' → MODE 2 (no withVersion, update version 1) 54. - If ambiguous, ask user: 'Do you want to create a new version or update the existing version?' 55. 56. VERSION CREATION WORKFLOW (withVersion=true): 57. Step 1: Fetch test case details to get current tcID, tcVersionID, and tcVersion 58. Step 2: Optionally fetch current steps if they need to be preserved/modified 59. Step 3: Prepare payload with: 60. - tcID (test case ID) 61. - tcVersionID (source version ID to create from) 62. - tcVersion (current version number) 63. - withVersion: true (CRITICAL flag) 64. - versionComment (recommended: describe what changed) 65. - Updated fields (name, description, priority, steps, etc.) 66. - notruncurrent: true (recommended) 67. - notrunall: true (recommended) 68. Step 4: Call update API - a new version will be created with incremented version number 69. Step 5: New version inherits all fields from source version, with your specified updates applied 70. 71. EXISTING VERSION UPDATE WORKFLOW (no withVersion): 72. Step 1: Fetch test case details to get tcID and tcVersionID of the version to update 73. Step 2: Prepare payload with: 74. - tcID (test case ID) 75. - tcVersionID (version ID to update) 76. - DO NOT include withVersion, versionComment, or tcVersion 77. - Only include fields you want to change 78. Step 3: Call update API - specified version is updated in-place 79. Step 4: No new version is created, only specified fields are modified 80. 81. FIELD MAPPING FOR VERSION CREATION: 82. When creating a new version, include ALL fields you want the new version to have: 83. - name: Test case summary (required if different from source) 84. - description: Test case description (required if different from source) 85. - priority: Priority ID (get from project info customListObjs.priority[index].id) 86. - testcaseOwner: Owner ID (get from project info customListObjs.owner[index].id) 87. - testCaseState: State ID (get from project info customListObjs.testCaseState[index].id) 88. - testCaseType: Type ID (get from project info customListObjs.testCaseType[index].id) 89. - testingType: Testing type ID (get from project info customListObjs.testingType[index].id) 90. - component: Array of component IDs (get from project info customListObjs.component[index].id) 91. - estimatedTime: Time in seconds (e.g., 7200 for 2 hours) 92. - steps: Array of step objects (include tcStepID from source version to preserve steps) 93. - folderPath: Folder path or folder ID 94. - scope: Usually 'project' 95. 96. STEPS HANDLING IN VERSION CREATION: 97. When creating a new version WITH steps: 98. - To PRESERVE existing steps: Include them with their original tcStepID values 99. - To ADD new steps: Include them WITHOUT tcStepID 100. - To MODIFY steps: Include them with tcStepID and updated description/data 101. - To REMOVE steps: Include them in removeSteps array 102. - Set isStepUpdated: true if any steps are modified, added, or removed 103. - If no steps are included, new version may inherit steps from source (verify with QMetry docs) 104. 105. If user provides entityKey (e.g., MAC-TC-1684), first call FETCH_TEST_CASES with a filter on entityKeyId to resolve the tcID and tcVersionID. 106. To get valid values for priority, owner, component, etc., call the project info tool and use the returned customListObjs IDs. 107. If the user provides a priority name (e.g. 'Blocker'), fetch project info, find the matching priority in customListObjs.priority[index].name, and use its ID in the payload. If the name is not found, skip the priority field (it is not required) and show a user-friendly message: 'Test case updated without priority, as given priority is not available in the current project.' 108. If the user provides a component name, fetch project info, find the matching component in customListObjs.component[index].name, and use its ID in the payload. If the name is not found, skip the component field (it is not required) and show a user-friendly message: 'Test case updated without component, as given component is not available in the current project.' 109. If the user provides an owner name, fetch project info, find the matching owner in customListObjs.owner[index].name, and use its ID in the payload as testcaseOwner. If the name is not found, skip the testcaseOwner field (it is not required) and show a user-friendly message: 'Test case updated without owner, as given owner is not available in the current project.' 110. If the user provides a test case state name, fetch project info, find the matching state in customListObjs.testCaseState[index].name, and use its ID in the payload as testCaseState. If the name is not found, skip the testCaseState field (it is not required) and show a user-friendly message: 'Test case updated without test case state, as given state is not available in the current project.' 111. If the user provides a test case type name, fetch project info, find the matching type in customListObjs.testCaseType[index].name, and use its ID in the payload as testCaseType. If the name is not found, skip the testCaseType field (it is not required) and show a user-friendly message: 'Test case updated without test case type, as given type is not available in the current project.' 112. If the user provides a testing type name, fetch project info, find the matching type in customListObjs.testingType[index].name, and use its ID in the payload as testingType. If the name is not found, skip the testingType field (it is not required) and show a user-friendly message: 'Test case updated without testing type, as given testing type is not available in the current project.' 113. Example: If user says 'Update test case with title "High priority test case" and set priority to "Blocker"', first call project info, map 'Blocker' to its ID, and use that ID for the priority field in the update payload. If user says 'set priority to "Urgent"' and 'Urgent' is not found, skip the priority field and show: 'Test case updated without priority, as given priority is not available in the current project.' 114. CRITICAL: To update test case steps without Duplication, use the following rules: 115. - ANTI-DUPLICATION RULE: The tcStepID field is THE KEY to prevent duplication: 116. * WITH tcStepID = UPDATE existing step (QMetry modifies the existing step in place) 117. * WITHOUT tcStepID = CREATE new step (QMetry adds a brand new step) 118. - For steps to be UPDATED: ALWAYS fetch existing steps first using FETCH_TEST_CASE_STEPS, then include the tcStepID in the step object. 119. - For steps to be ADDED: omit tcStepID completely in the step object. 120. - For steps to be REMOVED: add a full removeSteps object for each step to be deleted, matching the removeTestCaseStep interface. 121. - CRITICAL WARNING - DO NOT ADD UNSOLICITED STEPS: 122. * ONLY add, edit, or remove steps that the user EXPLICITLY requested 123. * DO NOT invent, create, or add extra steps based on assumptions or best practices 124. * DO NOT add 'helpful' steps that the user did not ask for 125. * When user says 'remove step 1', the result should have (N-1) steps, not N steps with extras 126. * When user says 'add 1 step', ONLY add that 1 step, nothing more 127. * When user says 'update step 2', ONLY update step 2, do not add or modify other steps 128. * If unsure what user wants, ASK first rather than adding steps autonomously 129. - WORKFLOW TO AVOID DUPLICATION: 130. 1. Call FETCH_TEST_CASE_STEPS to get all existing steps with their tcStepID values 131. 2. For steps you want to KEEP/UPDATE: Include them in steps[] WITH their original tcStepID 132. 3. For steps you want to ADD: Include them in steps[] WITHOUT tcStepID (ONLY if user requested) 133. 4. For steps you want to REMOVE: Include them in removeSteps[] with full details 134. 5. Always set isStepUpdated: true if steps are added, updated, or removed 135. 6. VERIFY your steps array matches user's explicit request (count and content) 136. - Example: If user says 'Edit step 1 to say ...', FIRST fetch steps to get tcStepID for step 1, THEN include it in the steps array with updated fields and the ORIGINAL tcStepID. 137. - Example: If user says 'Add a new step after step 2', add EXACTLY ONE new object to steps array with no tcStepID (not multiple steps). 138. - Example: If user says 'Remove step 3', add the full step object to removeSteps array, including tcStepID and all required fields. Do NOT add replacement steps. 139. - Example: If test case has 3 steps and user says 'remove step 1', result should have 2 steps (step 2 and step 3 with updated orderIds), NOT 3 steps with extras. 140. - Example: If user says 'add one mock step', add EXACTLY ONE step (not 2 or 3 steps even if they seem related). 141. - COMPLETE PAYLOAD EXAMPLE: { tcID: 123, tcVersionID: 456, steps: [{tcStepID: 1001, orderId: 1, description: 'Updated'}, {orderId: 2, description: 'New'}], removeSteps: [{tcStepID: 1002, orderId: 3, ...}], isStepUpdated: true } 142. - If only metadata is updated (no steps), set updateOnlyMetadata: true and do not include steps/removeSteps. 143. - Always preserve orderId sequence for proper step ordering. 144. - If user prompt is ambiguous, ask for clarification or show a user-friendly error. 145. - WARNING: Omitting tcStepID for existing steps will cause DUPLICATION - the API will create duplicates instead of updating! 146. - FINAL VERIFICATION BEFORE SENDING REQUEST: 147. * Count steps in your payload vs what user requested 148. * If user said 'add 1 step', steps array should have (existing_count + 1) items total 149. * If user said 'remove 1 step', steps array should have (existing_count - 1) items total, removeSteps should have 1 item 150. * If user said 'update step X', steps array should have same count as before, with step X's tcStepID preserved 151. * NEVER include steps the user did not explicitly mention or request 152. Steps are optional but recommended for manual test cases. 153. If the user provides a prompt like 'update test case with steps as step 1 - Go to login page, step 2 - give credential, step 3 - go to test case page, step 4 - create test case', LLM should parse each step and convert it into the steps payload array, mapping each step to an object with orderId, description, and optionally inputData and expectedOutcome. 154. Example mapping: 'step 1 - Go to login page' → { orderId: 1, description: 'Go to login page' }. 155. LLM should increment orderId for each step, use the step text as description, and optionally infer inputData/expectedOutcome if provided in the prompt. 156. Demo steps payload: steps: [ { orderId: 1, description: 'First Step', inputData: 'First Data', expectedOutcome: 'First Outcome', UDF: { customField1: 'Custom Field Data A', customField2: 'Custom Field Data B' } }, ... ] 157. UDF fields in steps must match your QMetry custom field configuration. 158. All IDs (priority, owner, etc.) must be valid for your QMetry instance. 159. If a custom field is mandatory, include it in the UDF object. 160. 161. ADDITIONAL VERSION CREATION GUIDANCE: 162. - versionComment field: STRONGLY RECOMMENDED when withVersion=true. Helps track why version was created. 163. Example comments: 'Updated for Sprint 5 requirements', 'Fixed test steps based on code review', 'Version 2 for production environment' 164. - notruncurrent and notrunall flags: Control execution behavior when creating versions. Set both to true as best practice. 165. - folderPath: Can be string path or numeric folder ID. Usually inherited from source version if not specified. 166. - attachments: Use ADD/REMOVE arrays to manage attachments when creating new version or updating existing version. 167. - estimatedTime vs executionMinutes: Use estimatedTime (in seconds) for version creation. executionMinutes (in minutes) is legacy field. 168. 169. REAL-WORLD VERSION CREATION EXAMPLES: 170. Example 1: User says 'create a new version of test case VKMCP-TC-10 with summary = "Facebook Login Validation Failed update from MCP V2", description = used existing description by at last add V2 text, release = default, cycle = default' 171. → Workflow: 172. 1. Fetch VKMCP-TC-10 details to get tcID, tcVersionID, tcVersion, current description 173. 2. Fetch project info to get default release ID and cycle ID 174. 3. Append ' V2' to current description 175. 4. Send payload with: tcID, tcVersionID (source), tcVersion (current), withVersion=true, name='...V2', description='...V2', versionComment='Created version 2', release/cycle IDs 176. → Result: New incremental version created (e.g., version 1 → version 2) with updated summary, modified description, associated with default release/cycle 177. 178. Example 2: User says 'update version 2 summary, release, cycle, priority' 179. → Workflow: 180. 1. Fetch test case details to get version 2's tcVersionID 181. 2. Fetch project info to get priority, release, cycle IDs 182. 3. Send payload with: tcID, tcVersionID (of version 2), WITHOUT withVersion flag, with updated summary, release, cycle, priority 183. → Result: Version 2 updated in-place. No new version created. Only specified fields modified. 184. 185. COMMON PITFALLS TO AVOID: 186. - Pitfall 1: Setting withVersion=true when user wants to update existing version → Creates unwanted new version 187. - Pitfall 2: Omitting versionComment when creating new version → Lost tracking of why version was created 188. - Pitfall 3: Not fetching current tcVersionID before update → Updating wrong version or causing error 189. - Pitfall 4: Using tcVersion for normal updates → tcVersion only needed when withVersion=true 190. - Pitfall 5: Not including tcStepID for steps when creating version → Steps may duplicate instead of preserving 191. - Pitfall 6: Confusing tcVersionID (version identifier) with tcVersion (version number) → Wrong API payload 192. 193. CRITICAL ERROR HANDLING: TC.VERSION_NOT_SYNCED FOR LINKED TEST CASES 194. 195. PROBLEM: Test cases linked to test suites or with existing executions cannot be updated directly 196. TRIGGERS: 197. ✓ Test case is linked to one or more test suites 198. ✓ Test case has execution history (test runs exist) 199. ✓ Test case is part of a release/cycle with test runs 200. ✓ Any step modification when test case has associations 201. 202. ERROR CODE: TC.VERSION_NOT_SYNCED 203. ERROR MESSAGE: 'This Test Case has been associated. Create a new version to save modifications.' 204. 205. AUTOMATIC RETRY STRATEGY (IMPLEMENT THIS PATTERN): 206. When you receive TC.VERSION_NOT_SYNCED error, AUTOMATICALLY retry with version creation: 207. DO NOT ask user for confirmation - this is expected behavior for associated test cases 208. 209. 1. FIRST ATTEMPT (Normal Update): 210. - Try updating with isStepUpdated=true (for step changes) or without withVersion flag 211. - If error code is TC.VERSION_NOT_SYNCED, proceed to step 2 212. - If error is different, report the error to user 213. 214. 2. AUTOMATIC RETRY (Version Creation): 215. - Use the SAME tcID, tcVersionID, and steps array from first attempt 216. - Add these flags to payload: 217. * withVersion: true (CRITICAL - enables version creation) 218. * tcVersion: (get from test case details or executions) 219. * notrunall: false (use false, not true) 220. * notruncurrent: false (use false, not true) 221. * scope: 'project' (always required) 222. * versionComment: 'Auto-created version due to test suite association' (or custom message) 223. - Set isStepUpdated: true whenever you modify steps (including when withVersion=true) 224. - IMPORTANT: Include ALL existing steps with tcStepID + new steps without tcStepID 225. 226. 3. VERIFICATION: 227. - Check response for new tcVersionID (will be different from source) 228. - Verify tcVersion incremented (e.g., 1→2, 2→3) 229. - Confirm success message: 'Test Case updated successfully' 230. 231. UI BEHAVIOR COMPARISON: 232. QMetry UI shows a popup: 'Save as new version?' with optional comment field 233. API equivalent: Automatic retry with withVersion=true after detecting TC.VERSION_NOT_SYNCED 234. 235. REAL-WORLD EXAMPLE FROM UI PAYLOADS: 236. 237. First Attempt (FAILS with TC.VERSION_NOT_SYNCED): 238. pseudo 239. { 240. "tcID": 4594140, 241. "tcVersionID": 5536696, 242. "withVersion": false, 243. "notrunall": false, 244. "steps": [ 245. // ... 5 existing steps with tcStepID ... 246. // ... 1 new step without tcStepID (orderId: 6) ... 247. ], 248. "removeSteps": [], 249. "isStepUpdated": true 250. } 251. 252. Response: 400 - TC.VERSION_NOT_SYNCED error 253. 254. Second Attempt (SUCCEEDS - Creates Version 2): 255. pseudo 256. { 257. "withVersion": true, // NEW: Version creation flag 258. "notrunall": false, 259. "notruncurrent": false, 260. "steps": [ 261. // SAME steps array as first attempt 262. // ... 5 existing steps with tcStepID ... 263. // ... 1 new step without tcStepID ... 264. ], 265. "removeSteps": [], 266. "scope": "project", 267. "tcID": 4594140, // SAME tcID 268. "tcVersion": 1, // NEW: Current version number 269. "tcVersionID": 5536696, // SAME tcVersionID (source version) 270. "versionComment": "test", // NEW: Version comment (optional) 271. // NOTE: isStepUpdated field is NOT included when withVersion=true 272. } 273. 274. Response: 200 - Success, new tcVersionID created (e.g., 5536697), tcVersion=2 275. 276. IMPLEMENTATION PSEUDO-CODE: 277. typescript 278. try { 279. // First attempt: Normal update 280. const response = await updateTestCase({ 281. tcID, tcVersionID, steps, isStepUpdated: true 282. }); 283. } catch (error) { 284. if (error.code === 'TC.VERSION_NOT_SYNCED') { 285. // Automatic retry with version creation 286. const testCaseDetails = await fetchTestCaseDetails(tcID); 287. // CRITICAL: Use the LATEST version number from system 288. const latestVersion = testCaseDetails.tcVersion; // e.g., 2 if v2 exists 289. const response = await updateTestCase({ 290. tcID, 291. tcVersionID, // Same source version 292. tcVersion: latestVersion, // Use latest version number (not always 1!) 293. steps, // Same steps array 294. // DO NOT include isStepUpdated when withVersion=true 295. withVersion: true, // Enable version creation 296. notrunall: false, // Use false (verified working value) 297. notruncurrent: false, // Use false (verified working value) 298. scope: 'project', // Always required 299. versionComment: 'Auto-created version due to test suite association' 300. }); 301. } else { 302. throw error; // Different error, report to user 303. } 304. } 305. 306. 307. KEY INSIGHTS: 308. - DO NOT ask user for confirmation - auto-retry is expected behavior 309. - Use SAME tcVersionID in both attempts (source version for creation) 310. - Second attempt creates NEW version (tcVersionID changes in response) 311. - Steps array is IDENTICAL in both attempts 312. - tcVersion parameter is ONLY in second attempt (withVersion=true) 313. - This matches QMetry UI behavior where popup auto-triggers version creation 314. 315. CRITICAL: INCREMENTAL tcVersion SELECTION RULE 316. 317. PROBLEM: When multiple versions exist, which tcVersion should you use? 318. SOLUTION: Use the VERSION NUMBER of the version you are creating FROM (the latest existing version) 319. 320. RULE: When creating a new version, tcVersion must equal the CURRENT LATEST VERSION in the system 321. 322. EXAMPLES: 323. - If only version 1 exists: Use tcVersion: 1 (creates version 2 from v1) 324. - If version 1 and 2 exist: Use tcVersion: 2 (creates version 3 from v2) 325. - If version 1, 2, and 3 exist: Use tcVersion: 3 (creates version 4 from v3) 326. 327. WORKFLOW TO DETERMINE CORRECT tcVersion: 328. 1. Call FETCH_TEST_CASE_DETAILS or FETCH_TEST_CASE_EXECUTIONS 329. 2. Check the highest tcVersion number in the system 330. 3. Use that number as your tcVersion parameter in the update payload 331. 4. This ensures you're creating from the latest version, not an old one 332. 333. REAL-WORLD SCENARIO: 334. Scenario: Test case VKMCP-TC-43 has version 2 already created in UI 335. Wrong Approach (will fail): tcVersion: 1, withVersion: true → TC.VERSION_NOT_SYNCED error 336. Correct Approach (will succeed): tcVersion: 2, withVersion: true → Creates version 3 successfully 337. 338. VERIFIED WORKING PAYLOAD (from user's Postman testing): 339. json 340. { 341. "notrunall": false, 342. "notruncurrent": false, 343. "scope": "project", 344. "tcID": 4594145, 345. "tcVersion": 2, // KEY: Use version 2 because v2 already exists 346. "tcVersionID": 5536706, // Source version ID (stays same) 347. "versionComment": "Added new steps", // Describes what changed 348. "withVersion": true, // Enable version creation 349. "steps": [ 350. // 5 existing steps with tcStepID (preserved from source) 351. // 2 new steps without tcStepID (to be added) 352. ] 353. } 354. 355. Result: New version 3 created successfully with 7 total steps 356. 357. DEFAULT VALUES FOR TC.VERSION_NOT_SYNCED RETRIES (THIS PATTERN): 358. - notrunall: false - For this retry pattern, override any usual true default 359. - notruncurrent: false - For this retry pattern, override any usual true default 360. - scope: "project" - Always use this 361. - withVersion: true - Required when creating a new version (both initial and retries) 362. 363. WHEN TO APPLY THIS PATTERN: 364. ✓ Adding steps to test case linked to test suite 365. ✓ Editing steps in test case with existing executions 366. ✓ Removing steps from associated test case 367. ✓ Any modification to steps when TC.VERSION_NOT_SYNCED occurs 368. ✓ When creating new versions from existing versions (always check latest version number) 369. 370. WHEN NOT TO APPLY: 371. ✗ Test case is NOT linked to test suite (normal update works) 372. ✗ Only updating metadata (name, priority, etc.) without steps 373. ✗ Different error codes (handle appropriately) 374. 375. BENEFITS OF THIS APPROACH: 376. 1. Seamless UX - LLM handles version creation automatically 377. 2. Matches UI behavior - no manual intervention needed 378. 3. Preserves test history - creates proper version trail 379. 4. Maintains test suite linkage - version creation preserves associations 380. 5. Handles incremental versions correctly - uses latest version as source 381. 382. 🎯 GRACEFUL HANDLING SUMMARY: 383. 384. When adding/editing/removing steps from test cases: 385. 1. Always TRY normal update first (without withVersion flag) 386. 2. If TC.VERSION_NOT_SYNCED error received: 387. - Fetch latest version number from test case details/executions 388. - Automatically retry with withVersion=true + correct tcVersion 389. - Use notrunall=false, notruncurrent=false, scope='project' 390. - Include version comment describing the changes 391. 3. Report success with new version details to user 392. 4. NEVER ask for confirmation - handle it transparently 393. 394. This ensures test cases with executions or suite associations are handled gracefully 395. without user intervention, matching the QMetry UI experience exactly. 396. 397. executionMinutes time is in minutes (legacy field). 398. estimatedTime is in seconds (preferred for version creation). 399. Description and testingType are optional but recommended for clarity. 400. 401. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 402. 1. Call 'Fetch UDF Layout' with entityType='TC', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 403. IF listOptions[field.listName] is empty after Fetch UDF Layout, the tool already tried a metadata fallback. If STILL empty, ask the user to provide the option ID from the QMetry UI — do NOT guess numeric IDs. 404. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 405. 3. For MULTILOOKUPLIST fields: pick an array of IDs; also pass the alias flat key (e.g., fieldNameAlias: 'Option Label'). 406. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 407. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. 408. Example: udfFields: { custom_text: 'new value' }, UDF: { custom_text: { fieldID: 1001, value: 'new value' } } 409. 6. Mandatory UDF fields (isMandatory=true) MUST be included. 410. STEP UDFs for update: Use same step UDF field names from 'Fetch UDF Layout' stepFields. Pass in each step's 'UDF' object. 411. For MULTILOOKUPLIST step UDFs in update: use { ADD: [id1, id2], REMOVE: [id3] } format.