---
name: jmeter-swagger-conversion
description: >-
  Convert Swagger 2.x or OpenAPI 3.x specification files into JMeter JMX scripts.
  Use when the user mentions Swagger, OpenAPI, API spec conversion, or creating a
  JMeter script from an API specification file.
---

# 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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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.
