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)

• testcaseOwner (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. 'create new version' / 'create version 2' / 'update with new version' → MODE 1 (withVersion=true) 49. 'update test case' / 'change priority' / 'modify version X' (no mention of new version) → MODE 2 50. Ambiguous → ask: 'Do you want to create a new version or update the existing version?' 51. 52. VERSION CREATION WORKFLOW: fetch tcID + latest tcVersionID + tcVersion → build payload → call API. 53. New version inherits all source fields; only explicitly passed fields are overridden. 54. Recommended: include versionComment. Steps: use tcStepID to preserve, omit to add, use removeSteps to delete. 55. Set isStepUpdated:true if steps are added, modified, or removed. 56. 57. FIELD IDs for version creation — all from project info customListObjs.[].id: 58. priority | testcaseOwner (→owner list) | testCaseState | testCaseType | testingType | component (array of IDs) 59. estimatedTime in seconds | scope:'project' | folderPath: string path or numeric ID 60. 61. 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. 62. To get valid values for priority, owner, component, etc., call the project info tool and use the returned customListObjs IDs. 63. NAMED FIELD RESOLUTION (priority, component, owner, testCaseState, testCaseType, testingType): 64. If user provides a name instead of an ID: look up ID from project info customListObjs.[].name. 65. Field→key map: priority→priority | component→component | owner→testcaseOwner | state→testCaseState | type→testCaseType | testingType→testingType. 66. If not found after a fresh project info fetch: skip the field (it is not required) and show: 67. 'Test case updated without , as given is not available in the current project.' 68. 69. CRITICAL: To update test case steps without Duplication, use the following rules: 70. - ANTI-DUPLICATION RULE: The tcStepID field is THE KEY to prevent duplication: 71. * WITH tcStepID = UPDATE existing step (QMetry modifies the existing step in place) 72. * WITHOUT tcStepID = CREATE new step (QMetry adds a brand new step) 73. - For steps to be UPDATED: ALWAYS fetch existing steps first using FETCH_TEST_CASE_STEPS, then include the tcStepID in the step object. 74. - For steps to be ADDED: omit tcStepID completely in the step object. 75. - For steps to be REMOVED: add a full removeSteps object for each step to be deleted, matching the removeTestCaseStep interface. 76. - CRITICAL WARNING - DO NOT ADD UNSOLICITED STEPS: 77. * ONLY add, edit, or remove steps that the user EXPLICITLY requested 78. * DO NOT invent, create, or add extra steps based on assumptions or best practices 79. * DO NOT add 'helpful' steps that the user did not ask for 80. * When user says 'remove step 1', the result should have (N-1) steps, not N steps with extras 81. * When user says 'add 1 step', ONLY add that 1 step, nothing more 82. * When user says 'update step 2', ONLY update step 2, do not add or modify other steps 83. * If unsure what user wants, ASK first rather than adding steps autonomously 84. - WORKFLOW TO AVOID DUPLICATION: 85. 1. Call FETCH_TEST_CASE_STEPS to get all existing steps with their tcStepID values 86. 2. For steps you want to KEEP/UPDATE: Include them in steps[] WITH their original tcStepID 87. 3. For steps you want to ADD: Include them in steps[] WITHOUT tcStepID (ONLY if user requested) 88. 4. For steps you want to REMOVE: Include them in removeSteps[] with full details 89. 5. Always set isStepUpdated: true if steps are added, updated, or removed 90. 6. VERIFY your steps array matches user's explicit request (count and content) 91. - 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. 92. - 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). 93. - 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. 94. - 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. 95. - Example: If user says 'add one mock step', add EXACTLY ONE step (not 2 or 3 steps even if they seem related). 96. - 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 } 97. - If only metadata is updated (no steps), set updateOnlyMetadata: true and do not include steps/removeSteps. 98. - Always preserve orderId sequence for proper step ordering. 99. - If user prompt is ambiguous, ask for clarification or show a user-friendly error. 100. - WARNING: Omitting tcStepID for existing steps will cause DUPLICATION - the API will create duplicates instead of updating! 101. - FINAL VERIFICATION BEFORE SENDING REQUEST: 102. * Count steps in your payload vs what user requested 103. * If user said 'add 1 step', steps array should have (existing_count + 1) items total 104. * If user said 'remove 1 step', steps array should have (existing_count - 1) items total, removeSteps should have 1 item 105. * If user said 'update step X', steps array should have same count as before, with step X's tcStepID preserved 106. * NEVER include steps the user did not explicitly mention or request 107. Steps are optional but recommended for manual test cases. 108. 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. 109. Example mapping: 'step 1 - Go to login page' → { orderId: 1, description: 'Go to login page' }. 110. LLM should increment orderId for each step, use the step text as description, and optionally infer inputData/expectedOutcome if provided in the prompt. 111. 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' } }, ... ] 112. UDF fields in steps must match your QMetry custom field configuration. 113. All IDs (priority, owner, etc.) must be valid for your QMetry instance. 114. If a custom field is mandatory, include it in the UDF object. 115. 116. VERSION CREATION NOTES: 117. - notruncurrent + notrunall: default true for regular version creation; use false only in TC.VERSION_NOT_SYNCED retry. 118. - folderPath: string path or numeric ID; inherited from source version if omitted. 119. - attachments: use ADD/REMOVE arrays to manage attachments on create or update. 120. 121. PITFALL: tcVersionID (numeric version identifier, stays same across creation) ≠ tcVersion (version number 1/2/3, only used when withVersion=true). 122. 123. TC.VERSION_NOT_SYNCED — AUTO-RETRY (transparent, no user confirmation needed): 124. TRIGGER: Test case linked to test suites or has existing executions — direct step updates are blocked. 125. ERROR CODE: TC.VERSION_NOT_SYNCED | MESSAGE: 'This Test Case has been associated. Create a new version to save modifications.' 126. 127. RETRY FLOW: 128. 1. First attempt — normal update (no withVersion). If TC.VERSION_NOT_SYNCED → go to step 2. Different error → report and stop. 129. 2. Fetch test case details to get LATEST tcVersion number. 130. CRITICAL: use the highest existing version (e.g. v2 exists → tcVersion=2, not 1). Wrong value triggers the error again. 131. 3. Retry with SAME tcID, tcVersionID, steps[] PLUS these additional fields: 132. withVersion: true | tcVersion: | notrunall: false | notruncurrent: false | scope: 'project' 133. versionComment: 'Auto-created version due to test suite association' 134. NOTE: omit isStepUpdated when withVersion=true. 135. 4. Verify new tcVersionID in response (different from source) and report new version details to user. 136. 137. tcVersion RULE: always equals the LATEST version in the system. 138. Only v1 exists → tcVersion:1 (creates v2) | v1+v2 exist → tcVersion:2 (creates v3) | etc. 139. 140. VERIFIED PAYLOAD SHAPE (retry attempt): 141. { tcID, tcVersionID, tcVersion:, withVersion:true, notrunall:false, notruncurrent:false, 142. scope:'project', versionComment:'...', steps:[...same as first attempt...] } 143. 144. executionMinutes time is in minutes (legacy field). 145. estimatedTime is in seconds (preferred for version creation). 146. Description and testingType are optional but recommended for clarity. 147. 148. UDF (User Defined Fields) WORKFLOW FOR UPDATE: 149. 1. Call 'Fetch UDF Layout' with entityType='TC', pageName='DETAIL' to get field names, fieldIDs (projectUserFieldID), and list option IDs. 150. 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. 151. 2. For LOOKUPLIST fields: pick one ID from listOptions[field.listName][].id. 152. 3. For MULTILOOKUPLIST fields: pick an array of IDs; also pass the alias flat key (e.g., fieldNameAlias: 'Option Label'). 153. 4. For CASCADINGLIST fields: pick parent ID + fetch child with 'Fetch Cascade Child Values'. Pass { parent: parentId, child: childId }. 154. 5. Pass BOTH 'udfFields' (flat root values) AND 'UDF' wrapper (with fieldID) — both required for update. 155. Example: udfFields: { custom_text: 'new value' }, UDF: { custom_text: { fieldID: 1001, value: 'new value' } } 156. 6. Mandatory UDF fields (isMandatory=true) MUST be included. 157. STEP UDFs for update: Use same step UDF field names from 'Fetch UDF Layout' stepFields. Pass in each step's 'UDF' object. 158. For MULTILOOKUPLIST step UDFs in update: use { ADD: [id1, id2], REMOVE: [id3] } format.