---
name: jmeter-har-conversion
description: >-
  Convert HAR (HTTP Archive) files into JMeter JMX scripts. Use when the user
  mentions HAR files, HAR conversion, Chrome DevTools recording, Fiddler capture,
  mitmproxy, Postman export, or creating a JMeter script from browser network traffic.
---

# HAR to JMeter JMX Conversion

## When to Use This Skill

- User wants to convert a HAR file into a JMeter script
- User mentions HAR, Chrome DevTools, Fiddler, Charles, mitmproxy, or Postman recording
- User has a `.har` file from a browser recording 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 HAR file into a structured network capture JSON
2. Analyzes the capture to identify dynamic values (correlations) and auto-generates
   variable names for them
3. **(Gate)** If low-confidence or orphan correlations are found, pauses for correlation
   variable name review before script generation
4. Generates a parameterized JMeter JMX script from the finalized naming data

### Parameter Reference

**Required:**

- `test_run_id` — Unique identifier for this test run (e.g., `hardemo1`).
  All artifacts are written to `artifacts/{test_run_id}/jmeter/`.
- `har_path` — Absolute filesystem path to the `.har` file.
  Relative paths will fail.

**Optional:**

- `step_strategy` — How to group HAR entries into test steps. Defaults to `auto`.
  - `auto` — Use HAR page references when available, fall back to time-gap detection
  - `page` — Group strictly by HAR page entries
  - `time_gap` — Group by time gaps between requests
  - `single_step` — All entries in one step
- `time_gap_threshold_ms` — Gap threshold in milliseconds for the `time_gap` strategy.
  Defaults to `3000`.

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

- HAR files from real browser sessions contain actual request/response data, so
  correlation analysis typically finds more meaningful results than synthetic
  Swagger-based captures.
- Use `page` strategy if the HAR has clean page entries. Use `time_gap` if pages
  are missing.
- Cache-busting parameters (e.g., `_t`, `_`) with epoch-millisecond values are common.
  These are typically orphan IDs best handled with JMeter's `__time()` function.
- OAuth redirect flows may have tokens exchanged outside the capture window, resulting
  in orphan correlations for auth-related values.
- After conversion, the user can proceed to HITL editing or debugging workflows.
- The correlation naming file is auto-generated by the analysis tool. **Always review
  and adjust variable names before generating the JMX script** when the analysis
  reports any low-confidence or orphan correlations — variable names are baked into
  the JMX at generation time and cannot be updated retroactively without re-generating
  or manually editing the script. Use the correlation naming skill at
  `.cursor/skills/jmeter-correlation-naming/SKILL.md` (Scenario A) for the review.

---

## 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]
  har_path    = [ask user — must be absolute path]

OPTIONAL:
  step_strategy        = [ask user or use default: "auto"]
  time_gap_threshold_ms = [ask user or use default: 3000]
```

---

### Step 1 — Convert HAR to Network Capture

**Input:** `test_run_id`, `har_path`, `step_strategy`, `time_gap_threshold_ms`

**Action:** Call MCP tool `convert_har_to_capture`

```
convert_har_to_capture(
  test_run_id           = {test_run_id},
  har_path              = {har_path},
  step_strategy         = {step_strategy},
  time_gap_threshold_ms = {time_gap_threshold_ms}
)
```

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

---

### Step 2a — Correlation Naming Review (Conditional Gate)

**Condition:** Check the `summary` from Step 2. If any of the following are non-zero,
this gate is **mandatory** before proceeding to Step 3:

- `low_confidence` > 0
- `orphan_ids` > 0

**Action:** Pause and present the low-confidence and orphan correlations to the user.

For each flagged correlation, show:
- The auto-generated `variable_name`
- The `type` and `value_type` (e.g. `orphan_id / email`, `progressive_auth / jwt`)
- Where the value was found (source URL and location)
- A suggested rename if the auto-generated name is generic or ambiguous

Ask the user to confirm or provide corrected names before continuing.

Once names are confirmed, follow the correlation naming skill at
`.cursor/skills/jmeter-correlation-naming/SKILL.md` (Scenario A) to apply any changes
to `correlation_naming.json`.

**If all correlations are high or medium confidence with no orphans:** skip this gate
and proceed directly to Step 3.

> **Why this gate exists:** `generate_jmeter_script` reads `correlation_naming.json`
> at generation time. Variable names are baked into extractor names and parameterized
> request fields in the JMX. Renaming after generation only updates the naming file —
> it does not retroactively update the script.

---

### 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 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.