Skip to content

Recording a Scenario ​

If you don't have a JMeter test plan yet, the recorder makes one by watching you use your application. You click through a flow in a real browser — log in, search, check out — and it writes a .jmx you can run as a load test.

Install ​

sh
npm install -g @cloudbeat/atlas-recorder

This downloads a private browser build (a few hundred MB) used for capture. It won't touch the browsers you already have. Requires Node.js 18 or newer.

It's a separate package from the CLI because CI machines run tests but never record them.

Record ​

sh
atlas-rec record https://example.com -o checkout.jmx -n "Checkout"

Or through the CLI, which can upload the result straight into a project:

sh
atlas record https://example.com -o checkout.jmx --upload -p SHOP

A browser window opens with a small control panel in the corner. Click through your flow, then press Stop.

Your recording is saved when you press Stop, when you close the window, and on Ctrl+C — closing the window by mistake won't lose it.

What you get ​

Each thing you do — a click, a form submit, a page change — becomes a labelled transaction, with the requests it triggered grouped underneath. A report then tells you "Checkout took 3.2s" rather than just listing URLs.

While recording you can:

  • rename a transaction so the report reads in your language, not the app's URLs
  • ➕ New to start a new transaction before you click, when one page holds two steps worth measuring separately
  • expand a transaction and exclude or delete individual requests
  • ⏸ Pause while you set something up you don't want recorded

What's kept, and what isn't ​

Kept: the requests your application makes — pages, API calls, form posts — and the CORS preflight a browser sends before calling an API on another domain. Preflights are marked (OPTIONS), recorded once per address the way a real visitor's browser sends them, and placed directly before the call they were sent for.

Skipped: images, stylesheets, fonts and known analytics traffic. These inflate a load test without telling you anything about your application. Include one from the control panel if you need it.

WebSockets and SignalR ​

A WebSocket your application keeps open — live notifications, chat, SignalR — is recorded too: the connection and every message, both ways. While recording it shows as a WS row with a message count.

The plan opens the connection the way the browser did, with its connection id and access tokens taken fresh on every run from the responses that issued them (SignalR's negotiate step included). It sends again what the browser sent, and waits for what the scenario depends on: for SignalR, the handshake answer, the result of each hub call, and each kind of notification that arrived during a step, in whatever order or grouping the server sends them. Pings are left out; for SignalR, which closes a connection that is silent for 30 seconds, the plan pings before each request and during the pauses between steps.

Each wait gives up after 10 seconds (-Jws_read_timeout=30000 to change it). Each simulated user holds one connection; if a page had two open at once, one is replayed and the other stays in the plan, switched off, with a note.

These plans need a JMeter plugin

Every JMeter that opens or runs the plan needs WebSocket Samplers by Peter Doornbosch; without it JMeter refuses the file. On your own machine, install it from JMeter's Plugins Manager, or put jmeter-websocket-samplers-<version>.jar from Maven Central into lib/ext, and restart JMeter. Load generators added through Atlas have it already; see Adding a Machine for machines added before it was included.

Dynamic values are handled ​

If a request sends something it was given earlier — a CSRF token, a session ID, an item ID from a search result — the recorder finds where that value came from and pulls it out of the live response at run time instead of replaying the recorded one. Without this, a recorded plan usually fails on the second run, when the token has changed.

This covers values wherever they are sent and wherever they came from:

  • in the query, a form, a JSON body or a header;
  • inside the address itself — the cart or order your session created, as in /cart/{id}/items/{id}. Only parts of the address that are clearly generated IDs are touched, and only when your application's API returned them; the fixed parts of an address never are;
  • from a response body, a response header, or a redirect on the way.

Each of these gets a check attached, so if the value ever stops coming back the sample fails loudly rather than quietly posting a stale token.

Errors you meant to get ​

A request that answered with an error while you recorded — "who am I?" returning 401 before you signed in — is part of the flow, not a failure. The plan expects that same status and checks for it, so it doesn't count as an error, while a different code (a 500 where a 401 was recorded) still fails the sample.

Every page is checked by its title ​

When a page you visited had a title, the plan checks the same title comes back on every run, so a login screen or error page served in place of the real one fails the sample instead of counting as a success. If your titles change from run to run (a user name, a date), record with --no-title-assertions.

Adding to an existing plan ​

Point -o at a plan that already exists and the new recording is added to it as another thread group, leaving what's there untouched. A .bak copy is written first.

sh
atlas-rec record https://example.com -o suite.jmx -n "Checkout"
atlas-rec record https://example.com -o suite.jmx -n "Search"

Recording behind a login ​

Reuse a signed-in session — saved when you stop, reloaded next time:

sh
atlas-rec record https://app.example.com -o app.jmx --profile ./session.json

Bring cookies from your own browser — export them and pass --cookies:

sh
atlas-rec record https://app.example.com/home -o app.jmx --cookies ./cookies.json

Options ​

OptionMeaning
-o, --out <file>Where to write. An existing plan is added to; otherwise created
-n, --name <name>Name for the scenario
-t, --threads <n>Number of users — only when creating a new plan
-l, --loops <n>Iterations per user — only when creating a new plan
--profile <file>Save and reuse a signed-in session
--cookies <file>Start already signed in, using exported cookies
--correlations <file>Pin named parameters to a value of your choosing
--no-correlateReplay recorded values as-is
--no-timestampsKeep recorded timestamps instead of using the current time
--no-title-assertionsDon't check that each page returns its recorded title

Check the plan before running it at scale ​

The recorder captures a single pass through your app. Anything that only appears sometimes — a cookie banner, an A/B variant, a retry — is recorded only if it happened while you clicked.

A redirect is recorded twice

When a step redirects, the redirect is followed and the destination is recorded on its own, so that step can hit the destination twice per iteration. Delete the duplicate from the control panel, or from the plan afterwards, if it would skew your numbers.

Record as a first-time visitor

Start from a browser that has never visited the site, or sign out and clear the site's data first. A browser that has been there before can carry things over — a cart it remembers, a stored sign-in token — and the recording then depends on them, while every simulated user starts from nothing.

Think-time pauses are recorded but switched off, so the plan runs flat out until you decide otherwise. Enable the Settings - Sleeps block in the plan and set the durations you want.

The site's address is one setting. Requests to the site you recorded read its host name from the Settings - Host block, so pointing the same plan at another environment means changing that one value. Requests to other sites keep their own address.

Driven by an agent, or a script ​

A recording does not have to be clicked by a person. The same session can be controlled command by command — snapshot to see the page, click, fill, tx new to name the step that follows — which is how an AI assistant records a flow for you, and how a script can automate one.

The browser stays visible throughout and your own clicks are recorded too, so you can take over for a login and hand it back.

sh
atlas-rec start https://shop.example.com -o flow.jmx -n "Checkout"
atlas-rec snapshot
atlas-rec tx new "Search"
atlas-rec click --role button --name "Search"
atlas-rec stop

See Your Own Integration for the full set, and Atlas for AI Agents to let an assistant do it.

Atlas — load testing by CloudBeat · Cookie settings