mirror of https://github.com/Postman-Devrel/postman-claude-code-plugin.git synced 2026-04-16 10:29:58 +00:00

Files

Sterling Chin 3f03fc19d3 feat: add 8 API lifecycle commands

Replace monolithic postman.md with focused, namespaced commands:
- setup: guided API key config and workspace verification
- sync: create/update collections from OpenAPI specs
- codegen: generate typed client code from collections
- search: discover APIs across private workspaces
- test: run collection tests and diagnose failures
- mock: create mock servers with auto-generated examples
- docs: analyze, improve, and publish API documentation
- security: OWASP API Top 10 security audit

Each command has proper frontmatter, error handling with actionable
next steps, and handles known MCP limitations (async polling, private
search, etc.).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-12 17:55:22 -08:00

3.0 KiB

Raw Blame History

description, allowed-tools

description	allowed-tools
Run Postman collection tests, analyze results, diagnose failures, and suggest fixes.	Bash, Read, Write, Glob, Grep, mcp__postman__*

Run Collection Tests

Execute Postman collection tests directly from Claude Code. Analyze results, diagnose failures, and suggest code fixes.

Prerequisites

The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run /postman:setup to configure the Postman MCP Server."

Workflow

Step 1: Find the Collection

Call getWorkspaces to find the target workspace
Call getCollections with the workspace parameter. Use the name filter if the user specified a collection.
If the user provides a collection ID directly, skip to Step 2.

Step 2: Run Tests

Call runCollection with the collection UID in OWNER_ID-UUID format. Get the UID from the getCollection response's uid field.

If the collection uses environment variables:

Call getEnvironments to list available environments
Ask which environment to use (or detect from naming convention)
Pass the environment ID to runCollection

Step 3: Parse Results

Present results clearly:

Test Results: Pet Store API
  Requests:  15 executed
  Passed:    12 (80%)
  Failed:    3
  Avg time:  245ms

  Failures:
  1. POST /users → "Status code is 201" → Got 400
     Request: createUser
     Folder: User Management

  2. GET /users/{id} → "Response has email field" → Missing
     Request: getUser
     Folder: User Management

  3. DELETE /users/{id} → "Status code is 204" → Got 403
     Request: deleteUser
     Folder: User Management

Step 4: Diagnose Failures

For each failure:

Call getCollectionRequest to see the full request definition
Call getCollectionResponse to see expected responses
Check if the API source code is in the current project
Explain what the test expected vs what happened
If code is local, find the handler and suggest the fix

Step 5: Fix and Re-run

After fixing code:

Offer to re-run: "Tests fixed. Want me to run the collection again?"
Call runCollection again
Show before/after comparison

Step 6: Update Collection (if needed)

If the tests themselves need updating (not the API):

Call updateCollectionRequest to fix request bodies, headers, or test scripts
Call updateCollectionResponse to update expected responses

Error Handling

MCP not configured: "Run /postman:setup to configure the Postman MCP Server."
Collection not found: "No collection matching that name. Run /postman:search to find available collections, or /postman:sync to create one."
401 Unauthorized: "Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys and run /postman:setup."
MCP timeout: Retry once. For large collections, suggest running a single folder to narrow the test run.
Plan limitations: "Collection runs may require a Postman Basic plan or higher for increased limits."

3.0 KiB Raw Blame History