--- name: octoperf-loadrunner-migration description: Use when migrating a LoadRunner script or Controller scenario to OctoPerf. Triggers on "migrate from LoadRunner", "import my VuGen script", "convert a .usr script", "import an .lrs scenario", "we're leaving Micro Focus/OpenText LoadRunner", "can OctoPerf read a LoadRunner script". Decides first whether the script is worth migrating, imports what converts mechanically — including the load shape a .lrs describes — then finishes by hand what has no OctoPerf equivalent: hand-written C, conditions reading C locals, recorded cookies, parameterised servers, load generators, non-HTTP protocols. Requires the OctoPerf MCP server. --- # OctoPerf — LoadRunner migration `import_loadrunner_virtual_user` does the mechanical part: the requests — `web_rest` included, whose headers are written inside the call rather than before it — the transactions, the extractors and checks, the headers, the think times, the `.prm` parameters with their `.dat` files uploaded, and the parameters the script writes with `lr_save_string` and `lr_save_datetime`, and the credentials `web_set_user` puts on a server. Given a provider it also reads the `.lrs` — each Controller group becomes a user profile carrying the load its schedule describes. It deliberately stops short of what has no OctoPerf equivalent, and hands back everything it left undone in the response's `unconverted` list, some of it as a **named marker** planted in the tree. This skill is what turns that list into a test that runs. Work in this order. Skipping the first step is how migrations get committed to and then abandoned. ## 1. Decide before you import Call `analyze_loadrunner_project` and read `portability` before anything else: | Verdict | What it means | What to do | |---|---|---| | `MECHANICAL` | Plain HTTP throughout | Import; expect it to run nearly as-is | | `ASSISTED` | HTTP plus C helpers or control flow | Import, then work the `unconverted` list | | `MOSTLY_MANUAL` | The C outweighs the requests | **Say so before importing** | `MOSTLY_MANUAL` is not a difficulty rating, it is a different script. A VuGen `.c` is C: an author is free to build a whole framework in it, and plenty have. In the reference corpus of 276 published scripts, 120 come out `MOSTLY_MANUAL`, and they are not near misses — they are scripts whose calls are `getenv`, `sprintf`, `strtok` and the author's own `wi_*` helpers, branching on a `rc` returned by another of their own functions. Nothing in that converts, because nothing in it is a request. **A script can be `QTWeb` and send nothing at all.** Check `inventory`, not the protocol: a script with 99 calls and no pages is a framework. Importing it produces a tree of markers and no traffic, which reads as a broken importer and is not one. Then read `protocols`. A `TruClientWeb`, `DevWeb`, `Web2UI`, `SapGui`, `RTE` or `RDP` script is reported rather than converted, and the import creates no Virtual User for it at all — see `UNSUPPORTED_PROTOCOL` below. Tell the user the count and let them decide; importing first and discovering it later wastes their time and yours. The per-script `scripts` breakdown matters as much as the verdict. An upload can be `MOSTLY_MANUAL` overall while three of its six scripts are plain HTTP. Migrate those and leave the rest. `recordingLevel` on each script tells you what the tree will look like before you see it. `HTML` means VuGen recorded user actions — one step per click, resources implicit, and every URL recovered from the `data/` snapshots. `HTTP` means it recorded requests — every asset its own step. The same journey recorded both ways gives very different trees, and neither is wrong. Finally read `unconverted`, which the assessment carries too. Nothing has been planted at this point, so the `marker` of every entry is empty; the `kind`, the `script` and the `line` are what identify the piece. `octoperf://schema/loadrunner-assessment` is the full vocabulary — every kind, and the facts each carries. ## 2. Import `import_loadrunner_virtual_user` takes the **whole script folder** zipped. Not the `Action.c`. `data/` is not optional. A script recorded at the HTML level carries no URLs of its own: `web_link("Text=FI-SW-01", "Snapshot=t71.inf")` says "click the thing labelled FI-SW-01 on whatever page you are on", and the only record of which request that produced is `data/t71.inf`. Without it, every click imports as a request against the entry page — the script appears to convert and replays as one page fetched six times. Zip the folder with its `.usr`, its `.c` sources, `default.cfg`, `default.usp`, the `.prm` and the `.dat` files it names, and `data/`. Leave out `result*/`, `data/http.db/` (VuGen's snapshot database — the largest in the corpus holds 1630 files an import never reads) and the replay logs. `pre_cci.c` and `combined_*.c` are dropped by the reader whether you send them or not: the first declares every LoadRunner function the script *could* call, so counting it turns nine real calls into a hundred and five. Several script folders in one archive are fine — each becomes its own Virtual Users. **Send the `.lrs` too, and pass a provider.** A Controller scenario becomes an OctoPerf scenario only when `providerId` is given: each group becomes a user profile carrying the load its schedule describes, and a profile has to say where it runs. Without a provider the `.lrs` is read for the assessment and no scenario is created — which is the right call when you only want the traffic. The provider is yours to choose. A `.lrs` names its load generators by hostname, and a hostname says nothing about a region — see `LOAD_GENERATOR`. ## 3. Work the `unconverted` list `unconverted` is the whole of the manual work — the import merges into it what conversion hit and what it never touches, so it is the only list you need. An entry is data, not prose. It carries a `kind` — which construct it is — the `script` and the `action` it was in, the `line` of the `.c` it sat on, and for some kinds a `facts` object holding the values the importer had. **This skill is where the explanation lives**: find the section named after the `kind` below and it tells you what happened and what to do; the `facts` tell you with what. The `line` is what makes an entry actionable. A customer holding a two-thousand-line `Action.c` needs it, and the `script` alongside it — a project of six scripts has six `Action.c` files. `facts` is polymorphic and names its own shape in a `@type` property, so read `@type` before the fields. An entry with no `facts` at all is a kind whose section needs no values from the project: the section alone is the instruction. Some entries also name a `marker`, and a marker is a promise: a node of **exactly** that name is in the tree. Find it with `get_virtual_user`, rewrite it with `patch_virtual_user` against `octoperf://schema/vu`. An empty `marker` is the ordinary case, and it says something too: the work is not a step in a tree at all. A variable to fill, a server to point at an environment, a parameter a `.prm` declares, an iteration count that belongs to a user profile — searching a tree for those wastes a pass over it. Work those from the `kind`, the `script` and the `line`. The kinds that do plant one are `CUSTOM_C_CODE`, `UNSUPPORTED_FUNCTION`, the protocol kinds, `CONVERSION_FAILED`, `MISSING_SNAPSHOT`, `LOOP_BOUND_NOT_LITERAL`, `RENDEZVOUS_POLICY` and `SCRIPT_SEQUENCE` — the last one naming a Virtual User rather than an action. Work from the list, not from the tree. A `[LoadRunner] …` name is not by itself something to fix. If a name is not in `unconverted`, leave it. Take them in this order; the later ones are cheap and the first is sometimes a reason to stop. ### `UNSUPPORTED_PROTOCOL` — a different script, not a harder one The `.usr` declares an `ActiveTypes` that is not HTTP. **The rule is a one-name allowlist**: `QTWeb`, LoadRunner's token for HTTP/HTML, is converted and every other token is reported here — including one nobody has seen before, since a token that travelled silently would be a script converted on a guess. `function` holds whichever it was. The corpus's are `TruClientWeb`, `TruClient2Web`, `TC4Mobile`, `Web2UI`, `Web2UIMob`, `DevWeb`, `RTE`, `RDP`, `SapGui`, `General-Java`, `WS_SOAP` and `SAP_Web`, but do not read that as the list to match against. **No Virtual User is created for that script.** The importer does not enumerate its calls either: fifteen TruClient scripts in the corpus would have contributed 372 `truclient_step` entries, and a report of 372 lines that all say the same thing hides the ones that matter. There is nothing to translate. A TruClient or Web2UI script drives a real browser through recorded UI steps; a DevWeb one is JavaScript. The traffic has to be recorded again against the live application — with OctoPerf's own recorder, or as a HAR imported through `import_har_virtual_user`. An `ActiveTypes` the assessment reports as empty is not this. A script declaring no protocol is walked and converted on the strength of its calls, because an absent `ActiveTypes` says nothing about what a script does. All seven such scripts in the corpus turned out to be UFT or protobuf with no `web_` call at all — which is what walking them established. ### `SOCKET_PROTOCOL`, `SAP_PROTOCOL`, `RDP_PROTOCOL`, `TERMINAL_PROTOCOL` — the same, one call at a time A script that declared a convertible protocol, or none, and then calls `lrs_*` (WinSock), `sapgui_*`, `rdp_*`, `ctrx_*` (Citrix) or `te_*` (terminal emulation). That is a mixed script: its HTTP half converts and this half does not. `function` names the call and `line` places it. Decide per script whether the HTTP half is a test on its own. A journey that logs in over SAP GUI and then browses over HTTP is not — the browsing depends on a session the converted half cannot open. ### `CUSTOM_C_CODE` — the C is the script, not decoration A call whose name carries none of LoadRunner's own prefixes. Either the C library — `sprintf` is 108 call sites in the corpus, beside `malloc`, `strtok`, `atoi`, `fopen` — or a helper the author wrote: `wi_start_transaction`, `mystrcat`, `login`, `get_google_access_token`. 494 entries on the corpus, and they are the difference between a recording and a framework. Read them together rather than one at a time, and ask what the C was **for**: - **It computed a value later sent.** `sprintf(url, "%s/item/%d", base, i)` feeding a request. Rebuild the value as an OctoPerf variable, or as a `JSR223Action` if it needs arithmetic. The request itself will already be in the tree, pointing at whatever literal the recording held. - **It wrapped web calls.** `wi_generic_html_get` and its like are the author's own request functions. Their bodies are in the script's `.h` or in an action the `.usr` does not list, so the importer never saw them and no request came out. Find the body, read what it sends, and build the request by hand — or re-record the journey, which is usually faster. - **It logged, timed or counted.** `lr_output_message` and its family are dropped silently and never appear here. What does appear — `lr_user_data_point`, `wi_startPrintingInfo` — is instrumentation, and OctoPerf measures its own. Delete the marker. - **It paused.** `sleep(...)`, 7 sites on the corpus and not one of them a plain literal — the arguments are C locals, so there is no duration to carry over. A Delay action is the replacement and you choose the number. Two things to know before you do: `sleep` takes **milliseconds on a Windows load generator and seconds on a Linux one**, and the archive never says which the script was written for, so a mechanical conversion would be a factor of 1000 decided by a guess. And unlike `lr_think_time` it is not think time — `[ThinkTime] Options=NOTHINK` does not switch it off, which is usually why the author reached for it. A script whose `unconverted` is all `CUSTOM_C_CODE` and whose tree holds no request is the framework case from step 1. Say so rather than patching sixty markers. ### `UNSUPPORTED_FUNCTION` — read the function, most are one line A real `web_*` or `lr_*` function with no converter yet. 50 distinct functions across the corpus; these are the ones you will actually meet: | Function | What it did | What to do | |---|---|---| | `lr_user_data_point` | A custom metric | Delete; OctoPerf measures its own | | `web_js_run` | Ran JavaScript in the page | Not HTTP. Either the value it computed is correlatable, or the journey needs re-recording | | `lr_get_attrib_string` | Read a command-line attribute | A variable holding what the runtime passed | | `web_reg_async_attributes`, `web_stop_async` | Long-polling or server push | Neither is request/response. Model the polling with a Loop container, or drop it | | `web_websocket_connect`, `web_websocket_send` | A WebSocket session | OctoPerf has WebSocket support; rebuild the session by hand | | `web_stream_open`, `web_stream_play`, `web_stream_close` | Played a media stream | Read `Protocol=` on the open. `HTTP` is a progressive download and rebuilds mechanically: one GET on its `URL`, then a Delay of `PlayingDuration` seconds so the journey keeps its tempo. Close and stop convert to nothing. The GET pulls the whole media at once where the player spread it across the play — same bytes, different rate. Any other protocol is not HTTP; leave it reported | | `lr_mysql_*`, `lr_xml_get_values` | A database query, XML reading | Not traffic. Usually setup that belongs outside the test | | `lrvtc_*`, `vtc_*` | LoadRunner's Virtual Table Server | A shared value store. A shared CSV variable is the nearest thing; a counter if it was minting ids | Anything not in that table: read the function name, look it up if you do not know it, and ask whether it produced traffic. If it did not, delete the marker. ### `THINK_TIME_NOT_LITERAL` — the pause is gone, and it was real `lr_think_time(RThinkTime)`. The duration is a C variable, so there is no number to convert and none is invented: an invented pause lowers the throughput the test was written to produce. No Delay is built, and the entry is here because the silence cuts the other way — the converted user runs faster than the script did. `facts` is a `LoadRunnerThinkTimeFacts` holding the duration as the script wrote it. That text is where to start: find where the variable was filled — a runtime attribute, a `rand()`, a value read from a file — and decide what the test was meant to wait for. Then add a Delay with that number. **Check `default.cfg` before you do.** `[ThinkTime]` states whether think time runs at all and by what factor, and both apply to what you add: `Factor=1.5` on a two second pause is three seconds. A script with `Options=NOTHINK` never reports this kind — there the configuration removes every pause, the literal ones included, and adding one back would be a test the customer never ran. 7 sites on the corpus, against 725 think times that name a number. ### `CONDITION_NOT_SUPPORTED` — the guard is gone, the branch is not The construct converted and its condition did not. **The steps are in the tree**: an `if` whose guard could not be read becomes an If container on `true` with the `else` beside it on `false`, so the branch the script guarded still fires and the alternative does not. A `while` gets a blank condition, which ends the loop on its first failing request rather than never. A chain of `else if` stacks rather than flattens: each `if` after the first lands inside the preceding `else`, so it sits under a container on `false` and cannot fire whatever its own guard says. **Only the first branch of a chain runs.** Re-expressing one condition is not enough there — the cascade has to be rebuilt as a whole, and until it is, the branches below the first are unreachable rather than merely unguarded. 91 `else if` across the corpus, in 10 files. `facts` is a `LoadRunnerConditionFacts` holding the raw C. Three C shapes convert, and all three read a LoadRunner parameter: ```c strcmp(lr_eval_string("{status}"), "OK") == 0 atoi(lr_eval_string("{count}")) >= 1 strstr(lr_eval_string("{body}"), "token") != NULL ``` Everything else reads a C local, and that is why it cannot convert rather than a gap to be filled. The corpus's four most common unconverted guards say it plainly: - `rc != LR_PASS` (48 sites) — `rc` is never set from a `web_*` call. It comes from the author's own functions: `wi_end_transaction`, `WT3_SignIn`. It means "my helper failed", and nothing on the OctoPerf side stands for that. - `iVerbosity >= 2` (43) — a debug switch, set from a constant or a command-line parameter. Decide whether the debug branch should run at all; usually it should not, so delete that container. - `stricmp("X", LPCSTR_RunType) == FOUND` (28) — a run-mode switch on a C local read at startup. If the value comes from a parameter, rewrite the condition against the variable; if it comes from the command line, decide the mode now and delete the branch that does not run. - `strcmp(Day, "Monday") == 0` — a local filled earlier in the C. For each entry, decide which branch the test should take, then either delete the container that must not run, or give the surviving one a real condition with `patch_virtual_user`. Leaving both at `true`/`false` runs one path forever, which is a decision by default rather than a bug — but make it deliberately. ### `LOOP_BOUND_NOT_LITERAL` — decide the count A `for` whose iteration count is not a literal. The body is in a plain container that runs **once**, and `function` holds the loop header — `i = 0; i < iCount; i++`. Inventing a number would silently change how much load the script generates, which is why it was not. Read the header, find what bounds it, and either put the count on a Loop container or accept the single pass. A loop bounded by a retry counter usually should run once. 52 of the corpus's 83 `for` loops land here, so this is common and usually cheap. ### `CONTROL_FLOW` — a fall-through to widen A `switch` case that falls through carrying a body of its own. The case before it would need its body copied into every case beneath, which the importer does not do. Rare: one `switch` in 276 corpus scripts. `function` names the case. Either copy the body down, or widen the guard of the case below to cover both labels — the guards are plain expressions on the switch subject and `patch_virtual_user` can rewrite them. An empty fall-through — `case 1: case 2:` — is already folded into one guard and never appears here. ### `PARAMETERISED_SERVER` — one server edit fixes the whole script The server a request points at was written with parameters, and not all of them survived. `facts` is a `LoadRunnerServerFacts` with the recorded `url` and the `scheme` and `port` the import had to fill in. Two causes, both common: - **The whole origin was one parameter.** `"URL={URL_BASE}/actions/Catalog.action"` — 602 of the corpus's 5013 recorded URLs. There is no scheme or host to read, so the origin was recovered from what the parameter replaced: VuGen keeps `OriginalValue`, the literal the parameter stood in for. The request now points at the environment the script was **recorded against**, where the script pointed at whichever one it was given. - **The scheme or the port was its own parameter.** `"URL={SCHEME}://{HOST}:{PORT}/catalog"` — five sites. A parameterised *host* converts faithfully, because a server hostname is substituted at replay; a scheme and a port cannot, since an OctoPerf server holds one of two protocols and a number. Either way the fix is one edit, not one per request. Find the server with `list_http_servers_by_project`, point it at the environment under test with `update_http_server`, and every request on it follows. Check `scheme` in the facts against what you expect — HTTPS is the guess, and a plain-text service will refuse it. ### `RECORDED_COOKIE` — add back the one the application needs `web_add_cookie` is the third most frequent call of the corpus — 1489 sites — and what it carries is a browser's jar as it stood on the day of the recording. `function` holds the cookie's name. None of them is replayed, and that is deliberate. The corpus's cookies are `userCart` holding a JSON document beside `_ga`, `_gid`, `AMCV_…@AdobeOrg` and an `mbox=session#…` stamped 2021. Handing every virtual user of a five-hundred-user test the same analytics identity and the same expired session is not the load the test claims to produce, so the virtual user starts with the empty jar OctoPerf gives a new visitor. One exception, already handled: a cookie whose **value** carries a parameter — `web_add_cookie("JSESSIONID={jsessionid}")` — is a value the script correlated out of a response, so it is state the script computes rather than state it remembers, and it is sent. Those do not appear here. A parameterised `DOMAIN` does not count: that says where the cookie applies, not that its value was correlated. So: for each name, decide whether the application needs it. - **A session cookie the server sets itself** — `JSESSIONID`, `ASP.NET_SessionId`, `PHPSESSID` — needs nothing. OctoPerf's cookie manager receives it from the response and stores it, which is what a real browser does. - **A consent, locale or feature flag** — `cookieConsent`, `lang`, `ab_variant` — needs adding back, as a `Cookie` header on the first request. Take the value from the entry's line in the `.c`. - **Third-party analytics** — `_ga`, `_gid`, `_gat`, `mbox`, `ak_bmsc` — leave out. Replaying an Akamai bot-management token from 500 users is worse than not sending it. `web_cleanup_cookies` is in neither the list nor the tree, and that is correct rather than a gap: JMeter manages its own cookie store and a virtual user starts each iteration with an empty jar. A script that called it deliberately already has what it asked for. ### `MISSING_SNAPSHOT` — the click has no URL to recover A `web_link` or `web_image` whose `Snapshot=` names a `data/tNN.inf` the archive does not hold. The step is a named marker rather than a request, because there is genuinely nothing to fetch. Almost always a packaging mistake: re-zip the folder **with** its `data/`. If the snapshots really are gone, find what the click did in the application and build the request by hand — `function` names the function and `line` places the call, whose `Text=` or `Src=` says what was clicked. ### `MISSING_DATA_FILE` — upload it A `.dat` a `.prm` names, which the archive did not carry or the storage would not take. `facts` is an `ImportFileFacts` with the filename. The CSV variable was created either way, so every reference to it resolves the moment the file exists. Upload it with `upload_project_file` under **exactly** that name. Two of the corpus's 314 tables name an absolute Windows path in `TableLocation` — a shared table living outside the script folder. Those were never in the archive and never will be; get the file from whoever ran the test. ### `MISSING_SCRIPT` — the scenario arrived without its scripts A `.lrs` group points at its script by absolute Windows path — `C:\\Users\\…\\aos-web-html\\aos-web-html.usr` — so an upload holding the scenario alone carries none of them. `function` names the script and `facts` is an `ImportFileFacts` holding the same name. **This is why an import can come out empty.** A group whose script is not in the archive has nothing to run and makes no user profile; a scenario whose every group is in that state makes no scenario. Without this entry the result is a project with no Virtual User, no scenario, and an `unconverted` list that says nothing — which reads as a conversion that found nothing to do. Named once per script however many groups run it, since uploading it settles all of them: four groups running one journey from four cities is one file to find. What to do: zip the Controller folder **and** the script folders together and import again. The scripts are usually beside the `.lrs` on the machine that ran the test — 33 of the corpus's 36 scenarios have theirs in the same repository, even though the path written in the file points somewhere else entirely. ### `PARAMETER_TYPE` — the parameter has nothing to become A `.prm` parameter with no OctoPerf variable to map onto. `function` holds its name. Four types and one function reach here: | Type | What to do | |---|---| | `Time`, `Date` | A `JSR223Action` writing the format you need, or a constant if the test does not care | | `Userid` | JMeter's own thread number. A `JSR223Action` doing `vars.put("id", ctx.getThreadNum())` | | `Group` | The user profile's name. Usually a constant per profile | | `Output` | A parameter a LoadRunner function filled in. Find which, and correlate it | A `SaveCount` on a `web_reg_find` also lands here: the check converted, but OctoPerf states whether a pattern matched and not how many times. If the count mattered, a regexp extractor with match number `-1` puts the count in `${name_matchNr}`. A `Custom` parameter appears here only when it held nothing. One with a value became a constant variable, which is what makes the `{SCHEME}`/`{URL}`/`{PORT}` scripts work. ### `SCRIPT_SEQUENCE` — three trees, one script Not a defect and nothing to repair. A LoadRunner script runs three sequences and an OctoPerf Virtual User is only the repeated one, so `vuser_init` and `vuser_end` each became a Virtual User of their own, named `