canyonlabz/jmeter-swagger-conversion

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.