run-collection
Execute Postman API test collections with Newman to validate endpoints and get detailed results. Specify collection path, environment, globals, and iteration count.
Instructions
Run a Postman Collection using Newman
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Path or URL to the Postman collection | |
| environment | No | Optional path or URL to environment file | |
| globals | No | Optional path or URL to globals file | |
| iterationCount | No | Optional number of iterations to run |
Implementation Reference
- src/newman/runner.ts:40-79 (handler)Core handler function that executes the Newman CLI to run the Postman collection, processes the run summary and failures into a structured TestResult.async runCollection(options: CollectionRunOptions): Promise<TestResult> { return new Promise((resolve, reject) => { const startTime = new Date().toISOString(); newman.run({ collection: options.collection, environment: options.environment, globals: options.globals, iterationCount: options.iterationCount, reporters: 'cli' }, (err, summary) => { if (err) { reject(err); return; } const endTime = new Date().toISOString(); // Format the results const result: TestResult = { success: summary.run.failures.length === 0, summary: { total: summary.run.stats.tests.total || 0, failed: summary.run.stats.tests.failed || 0, passed: (summary.run.stats.tests.total || 0) - (summary.run.stats.tests.failed || 0) }, failures: (summary.run.failures || []) .map(extractFailureInfo) .filter((failure): failure is TestFailure => failure !== null), timings: { started: startTime, completed: endTime, duration: new Date(endTime).getTime() - new Date(startTime).getTime() } }; resolve(result); }); }); }
- src/server/server.ts:69-101 (handler)MCP CallToolRequest handler specifically for 'run-collection' tool: validates input, executes NewmanRunner.runCollection, and formats success/error responses.this.server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name !== "run-collection") { throw new Error(`Unknown tool: ${request.params.name}`); } // Validate input const args = RunCollectionSchema.parse(request.params.arguments); try { // Run the collection const result = await this.runner.runCollection(args); // Format the response return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [{ type: "text", text: JSON.stringify({ error: errorMessage, success: false }, null, 2) }], isError: true }; } });
- src/server/server.ts:7-12 (schema)Zod schema for validating the input arguments to the 'run-collection' tool.const RunCollectionSchema = z.object({ collection: z.string(), environment: z.string().optional(), globals: z.string().optional(), iterationCount: z.number().min(1).optional() });
- src/server/server.ts:37-66 (registration)Tool registration in ListToolsRequest handler: defines name, description, and JSON inputSchema for 'run-collection'.this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "run-collection", description: "Run a Postman Collection using Newman", inputSchema: { type: "object", properties: { collection: { type: "string", description: "Path or URL to the Postman collection" }, environment: { type: "string", description: "Optional path or URL to environment file" }, globals: { type: "string", description: "Optional path or URL to globals file" }, iterationCount: { type: "number", description: "Optional number of iterations to run" } }, required: ["collection"] } } ] }));
- src/newman/runner.ts:7-32 (helper)Helper function to safely parse and extract structured failure information from Newman's failure objects.function extractFailureInfo(failure: NewmanRunFailure): TestFailure | null { try { if (!failure.error || !failure.source?.request) { return null; } const { error, source } = failure; const { request } = source; // Ensure we have all required properties if (!error.test || !error.message || !request.method || !request.url) { return null; } return { name: error.test, error: error.message, request: { method: request.method, url: request.url.toString() } }; } catch { return null; } }