Swagger / OpenAPI to JMeter JMX Conversion

When to Use This Skill

• User wants to convert a Swagger or OpenAPI spec into a JMeter script
• User mentions Swagger, OpenAPI, API spec, or API definition file
• User has a .json or .yaml API specification and needs a .jmx load test script

Reference

This section provides context for humans and capable models. For the step-by-step execution instructions, skip to the Execution section below.

What This Workflow Does

1. Converts a Swagger/OpenAPI spec file into a synthetic network capture JSON
2. Analyzes the capture to identify dynamic values (correlations) and auto-generates variable names for them
3. Generates a parameterized JMeter JMX script from the capture and naming data

Parameter Reference

Required:

• test_run_id — Unique identifier for this test run (e.g., swaggerdemo1). All artifacts are written to artifacts/{test_run_id}/jmeter/.
• spec_path — Absolute filesystem path to the Swagger/OpenAPI file (JSON or YAML). Relative paths will fail.

Optional:

• base_url — Base URL for the API (e.g., https://api.example.com/). Required when the spec uses relative server URLs, which is common in Swagger 2.x. Defaults to empty string.
• step_strategy — How to group endpoints into test steps. Defaults to tag.
  • tag — Group by OpenAPI tags
  • path — Group by URL path prefix
  • single_step — All endpoints in one step
• include_deprecated — Include deprecated endpoints. Defaults to false.

Related Rules

These Cursor Rules apply when using this skill:

• prerequisites.mdc — test_run_id and artifact structure validation
• skill-execution-rules.mdc — Follow steps in order, collect inputs first, do not skip
• mcp-error-handling.mdc — Error handling for MCP tool calls (retry policy, reporting format)
• jmeter-script-guardrails.mdc — Applies to downstream HITL editing and debugging after conversion

Notes

• Synthetic Swagger data uses placeholder values like sample_string, which causes the analyzer to detect broad correlations. This is expected for spec-based captures.
• After conversion, the user can proceed to HITL editing or debugging workflows.
• The correlation naming file is auto-generated by the analysis tool. The user can optionally review and adjust variable names using the correlation naming skill at .cursor/skills/jmeter-correlation-naming/SKILL.md.

Execution

Follow these steps exactly, in order. Each step has one action.

Collect Inputs

Ask the user for the following values. Do not proceed until all required values are collected.

REQUIRED:
  test_run_id  = [ask user]
  spec_path    = [ask user — must be absolute path]

OPTIONAL:
  base_url           = [ask user if spec uses relative server URLs, otherwise ""]
  step_strategy      = [ask user or use default: "tag"]
  include_deprecated = [ask user or use default: false]

Step 1 — Convert Swagger to Network Capture

Input: test_run_id, spec_path, base_url, step_strategy, include_deprecated

Action: Call MCP tool convert_swagger_to_capture

convert_swagger_to_capture(
  test_run_id        = {test_run_id},
  spec_path          = {spec_path},
  base_url           = {base_url},
  step_strategy      = {step_strategy},
  include_deprecated = {include_deprecated}
)

Expected response:

{
  "status": "OK",
  "network_capture_path": "artifacts/{test_run_id}/jmeter/network-capture/network_capture_YYYYMMDD_HHMMSS.json",
  "test_run_id": "{test_run_id}"
}

Save: capture_path = value of network_capture_path from the response.

On error: If status is "ERROR", stop. Report the full error message to the user.

Step 2 — Analyze Network Traffic

Input: test_run_id

Action: Call MCP tool analyze_network_traffic

analyze_network_traffic(
  test_run_id = {test_run_id}
)

Expected response:

{
  "status": "OK",
  "correlation_spec_path": "artifacts/{test_run_id}/jmeter/correlation_spec.json",
  "correlation_naming_path": "artifacts/{test_run_id}/jmeter/correlation_naming.json",
  "count": 7,
  "summary": { "total_correlations": 7, "business_ids": 3, "..." : "..." }
}

Save: correlation_count = value of count from the response.

On error: If status is "ERROR", stop. Report the full error message to the user.

This step produces two files:

• correlation_spec.json — raw correlation analysis
• correlation_naming.json — auto-generated variable names (no manual step needed)

Step 3 — Generate JMeter JMX Script

Input: test_run_id, capture_path (saved from Step 1)

Action: Call MCP tool generate_jmeter_script

generate_jmeter_script(
  test_run_id = {test_run_id},
  json_path   = {capture_path}
)

Expected response:

{
  "status": "success",
  "jmx_path": "artifacts/{test_run_id}/jmeter/ai-generated_script_YYYYMMDD_HHMMSS.jmx",
  "message": "JMX script generated successfully: ..."
}

Save: jmx_path = value of jmx_path from the response.

On error: If status is "error", stop. Report the full error message to the user.

Note: This tool returns lowercase "success" / "error", unlike the other tools which return uppercase "OK" / "ERROR".

Step 4 — Report to User

Input: test_run_id, jmx_path (saved from Step 3), correlation_count (saved from Step 2)

Action: Present the results to the user.

Tell the user:

• The JMX script was created at {jmx_path}
• {correlation_count} correlations were detected and parameterized
• The following artifacts were generated:

artifacts/{test_run_id}/jmeter/
├── network-capture/
│   └── network_capture_<timestamp>.json
├── capture_manifest.json
├── correlation_spec.json
├── correlation_naming.json
├── ai-generated_script_<timestamp>.jmx
└── testdata_csv/
    └── environment.csv

Ask the user:

• "Do you want to review or adjust the correlation variable names?" — If yes, follow the skill at .cursor/skills/jmeter-correlation-naming/SKILL.md (Scenario A).
• "Do you want to proceed with HITL editing or debugging?" — If yes, proceed to the appropriate downstream workflow.

Error Handling

These rules apply to every step:

• If any MCP tool returns an error status, stop immediately.
• Report the full error message to the user.
• Do NOT write code to fix MCP tool issues.
• Do NOT proceed to the next step if the current step failed.
• Ask the user for next steps.