jmeter-har-conversion

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:

{
  "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

---

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:

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