Update TestRail Run
update_runModify existing test runs in TestRail by updating details like name, description, milestone, case selection, configurations, dates, and custom fields to keep test data current.
Instructions
Updates an existing test run. Partial updates are supported.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The ID of the test run to be updated | |
| name | No | The name of the test run | |
| description | No | The description of the test run | |
| milestone_id | No | The ID of the milestone | |
| include_all | No | True for including all test cases and false for a custom case selection | |
| case_ids | No | An array of case IDs for the custom case selection | |
| config | No | A comma-separated list of configuration IDs | |
| config_ids | No | An array of configuration IDs | |
| refs | No | A string of external requirements | |
| start_on | No | The start date (Unix timestamp) | |
| due_on | No | The due date (Unix timestamp) | |
| custom | No | Custom fields (key-value pairs) |
Implementation Reference
- src/server.ts:665-715 (handler)MCP handler function for the 'update_run' tool. Processes input parameters, removes undefined fields, calls the service layer updateRun, formats the response as MCP content or error.
async ({ run_id, name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom }) => { logger.debug(`Update run tool called with run_id: ${run_id}`); try { const updates = { name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom, }; // Remove undefined values to avoid sending empty fields const cleanUpdates = Object.fromEntries( Object.entries(updates).filter(([, value]) => value !== undefined) ); const result = await updateRun(run_id, cleanUpdates); logger.debug(`Update run tool completed successfully for run_id: ${run_id}`); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (err) { logger.error({ err }, `Update run tool failed for run_id: ${run_id}`); const e = err as { type?: string; status?: number; message?: string }; let message = 'Unexpected error'; if (e?.type === 'auth') message = 'Authentication failed: check TESTRAIL_USER/API_KEY'; else if (e?.type === 'not_found') message = `Run ${run_id} not found`; else if (e?.type === 'rate_limited') message = 'Rate limited by TestRail; try again later'; else if (e?.type === 'server') message = 'TestRail server error'; else if (e?.type === 'network') message = 'Network error contacting TestRail'; else if (e?.message) message = e.message; return { content: [ { type: 'text', text: message }, ], isError: true, }; } }, - src/server.ts:650-663 (schema)Zod input schema defining parameters for the 'update_run' tool, including run_id (required) and optional update fields.
inputSchema: { run_id: z.number().int().positive().describe('The ID of the test run to be updated'), name: z.string().min(1).optional().describe('The name of the test run'), description: z.string().optional().describe('The description of the test run'), milestone_id: z.number().int().positive().optional().describe('The ID of the milestone'), include_all: z.boolean().optional().describe('True for including all test cases and false for a custom case selection'), case_ids: z.array(z.number().int().positive()).optional().describe('An array of case IDs for the custom case selection'), config: z.string().optional().describe('A comma-separated list of configuration IDs'), config_ids: z.array(z.number().int().positive()).optional().describe('An array of configuration IDs'), refs: z.string().optional().describe('A string of external requirements'), start_on: z.number().int().optional().describe('The start date (Unix timestamp)'), due_on: z.number().int().optional().describe('The due date (Unix timestamp)'), custom: z.record(z.string(), z.unknown()).optional().describe('Custom fields (key-value pairs)'), }, - src/server.ts:645-716 (registration)Registration of the 'update_run' MCP tool using server.registerTool, including title, description, input schema, and handler function.
server.registerTool( 'update_run', { title: 'Update TestRail Run', description: 'Updates an existing test run. Partial updates are supported.', inputSchema: { run_id: z.number().int().positive().describe('The ID of the test run to be updated'), name: z.string().min(1).optional().describe('The name of the test run'), description: z.string().optional().describe('The description of the test run'), milestone_id: z.number().int().positive().optional().describe('The ID of the milestone'), include_all: z.boolean().optional().describe('True for including all test cases and false for a custom case selection'), case_ids: z.array(z.number().int().positive()).optional().describe('An array of case IDs for the custom case selection'), config: z.string().optional().describe('A comma-separated list of configuration IDs'), config_ids: z.array(z.number().int().positive()).optional().describe('An array of configuration IDs'), refs: z.string().optional().describe('A string of external requirements'), start_on: z.number().int().optional().describe('The start date (Unix timestamp)'), due_on: z.number().int().optional().describe('The due date (Unix timestamp)'), custom: z.record(z.string(), z.unknown()).optional().describe('Custom fields (key-value pairs)'), }, }, async ({ run_id, name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom }) => { logger.debug(`Update run tool called with run_id: ${run_id}`); try { const updates = { name, description, milestone_id, include_all, case_ids, config, config_ids, refs, start_on, due_on, custom, }; // Remove undefined values to avoid sending empty fields const cleanUpdates = Object.fromEntries( Object.entries(updates).filter(([, value]) => value !== undefined) ); const result = await updateRun(run_id, cleanUpdates); logger.debug(`Update run tool completed successfully for run_id: ${run_id}`); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (err) { logger.error({ err }, `Update run tool failed for run_id: ${run_id}`); const e = err as { type?: string; status?: number; message?: string }; let message = 'Unexpected error'; if (e?.type === 'auth') message = 'Authentication failed: check TESTRAIL_USER/API_KEY'; else if (e?.type === 'not_found') message = `Run ${run_id} not found`; else if (e?.type === 'rate_limited') message = 'Rate limited by TestRail; try again later'; else if (e?.type === 'server') message = 'TestRail server error'; else if (e?.type === 'network') message = 'Network error contacting TestRail'; else if (e?.message) message = e.message; return { content: [ { type: 'text', text: message }, ], isError: true, }; } }, ); - Service layer helper: transforms MCP updates to TestRailRunUpdateDto, ensures custom_ prefix, calls client.updateRun, normalizes response to RunDetailSummary.
export async function updateRun(runId: number, updates: RunUpdatePayload): Promise<RunDetailSummary> { // Transform the payload to match TestRail API format const updatePayload: TestRailRunUpdateDto = { name: updates.name, description: updates.description, milestone_id: updates.milestone_id, include_all: updates.include_all, case_ids: updates.case_ids, config: updates.config, config_ids: updates.config_ids, refs: updates.refs, start_on: updates.start_on, due_on: updates.due_on, }; // Add custom fields with proper naming convention if (updates.custom) { for (const [key, value] of Object.entries(updates.custom)) { // Ensure custom field keys have the 'custom_' prefix const fieldKey = key.startsWith('custom_') ? key : `custom_${key}`; updatePayload[fieldKey] = value; } } const data: TestRailRunDetailDto = await testRailClient.updateRun(runId, updatePayload); // Normalize the response using the same logic as getRun const standardFields = [ 'id', 'name', 'description', 'suite_id', 'milestone_id', 'assignedto_id', 'include_all', 'is_completed', 'completed_on', 'config', 'config_ids', 'passed_count', 'blocked_count', 'untested_count', 'retest_count', 'failed_count', 'custom_status1_count', 'custom_status2_count', 'custom_status3_count', 'custom_status4_count', 'custom_status5_count', 'custom_status6_count', 'custom_status7_count', 'project_id', 'plan_id', 'created_on', 'updated_on', 'refs', 'start_on', 'due_on', 'url' ]; const custom: Record<string, unknown> = {}; Object.keys(data).forEach(key => { if (!standardFields.includes(key)) { custom[key] = data[key]; } }); return { id: data.id, name: data.name, description: data.description, suite_id: data.suite_id, milestone_id: data.milestone_id, assignedto_id: data.assignedto_id, include_all: data.include_all, is_completed: data.is_completed, completed_on: data.completed_on, config: data.config, config_ids: data.config_ids, passed_count: data.passed_count, blocked_count: data.blocked_count, untested_count: data.untested_count, retest_count: data.retest_count, failed_count: data.failed_count, custom_status1_count: data.custom_status1_count, custom_status2_count: data.custom_status2_count, custom_status3_count: data.custom_status3_count, custom_status4_count: data.custom_status4_count, custom_status5_count: data.custom_status5_count, custom_status6_count: data.custom_status6_count, custom_status7_count: data.custom_status7_count, project_id: data.project_id, plan_id: data.plan_id, created_on: data.created_on, updated_on: data.updated_on, refs: data.refs, start_on: data.start_on, due_on: data.due_on, url: data.url, custom: Object.keys(custom).length > 0 ? custom : undefined, }; } - HTTP client method that performs POST to TestRail API /update_run/{runId} with updates payload, handles response and errors.
async updateRun(runId: number, updates: TestRailRunUpdateDto): Promise<TestRailRunDetailDto> { try { const res = await this.http.post(`/update_run/${runId}`, updates); if (res.status >= 200 && res.status < 300) { logger.info({ message: 'Successfully updated test run', runId, responseSize: JSON.stringify(res.data).length, }); return res.data as TestRailRunDetailDto; } throw Object.assign(new Error(`HTTP ${res.status}`), { response: res }); } catch (error) { const normalized = this.normalizeError(error); const safeDetails = this.getSafeErrorDetails(error); logger.error({ message: 'Failed to update test run', runId, error: normalized, details: safeDetails, }); throw normalized; } }