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")

• baseUrl (string): The base URL for the QMetry instance (must be a valid URL)

• 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.

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