v1.8.1
This release adds HTTP traffic recording. Point your application's API base URL at a local Resterm listener and use the application as usual. Resterm forwards the traffic to your API and saves it in a Resterm .http file as runnable requests, mock responses, or both.
Recording from the command line
resterm record --listen 127.0.0.1:9000 \
--upstream https://api.example.com --out captured.http --mode bothChange your application's API base URL to http://127.0.0.1:9000, use the app, then press Ctrl+C.
--upstreamand--outare required.--listendefaults to127.0.0.1:9000.--modeacceptsrequests(default),mocks, orboth.- The output file must be new and its parent directory must exist. Resterm will not overwrite an existing file.
- Ctrl+C gives active requests up to 3 seconds to finish.
- Exit status is 0 on success, 1 when a capture or export was skipped or recording failed, and 2 for bad arguments. HTTP error responses are recorded normally and do not change the exit status on their own.
What gets written
A single POST recorded with --mode both produces this:
# @var file recordedBaseUrl https://api.example.com
### record-000001
# @name record-000001
POST {{recordedBaseUrl}}/v1/orders?limit=20
Authorization: REDACTED
Content-Type: application/json
{"item":"widget","qty":2}
###
### record-000001-mock
# @mock method=POST path=/v1/orders name=record-000001-mock interpolate=false
# @match query={"limit":"20"} json={"item":"widget","qty":2}
HTTP/1.1 201 Created
Content-Type: application/json
{"id":"ord_88","status":"created"}
###Recording inside the TUI
:record start --upstream https://api.example.com
:record list
:record status
:record stop
:record as-request
:record as-mock 1
:record clear
:record listopens the recorded traffic list.j/kscroll,Esccloses. Each row shows the capture ID, method, status, and URL, + the reason if a capture cannot be exported.:record as-requestand:record as-mockinsert recordings into the current.httpor.restfile. Without an ID they insert every completed recording. With an ID, such as:record as-mock 1, they insert that one.- The file must already have a path, and every insertion can be undone with
u. - Save the file after inserting. Recordings count as exported only once the file is saved.
- Recordings stay in memory when you switch files.
:record cleardiscards a stopped session. - Resterm warns before you quit with recording active or captures unsaved.
:q!discards them.
:help recording opens the full reference offline.
Redaction
Saved copies replace the values of known credential headers and known query, form, and JSON fields with REDACTED, and drop cookies entirely.
Field names are matched without case or separators, so client_secret, clientSecret, and CLIENT-SECRET all match. The built-in list covers names such as authorization, token, accesstoken, refreshtoken, apikey, password, secret, clientsecret, session, signature, and code.
Add your own names, repeating the flags as needed:
resterm record --upstream https://api.example.com --out captured.http \
--redact-header X-Company-Key --redact-field privateCredentialTwo things to know:
- Free text and values under names Resterm does not recognize are left unchanged, including tokens and passwords. I recommend to read a recording before you share it.
- Traffic forwarded to the upstream keeps its original credentials. Redaction only affects the saved copy, so your app keeps working while you record.
Replaying captures as mocks
Set recordedBaseUrl to your mock server address and run the file:
# Terminal 1: leave this running
resterm mock captured.http --addr 127.0.0.1:9001
# Terminal 2
resterm run captured.http- Mocks match on method, path, query values that were not redacted, and JSON body fields that were not redacted. Form and text bodies are not used for matching.
- When several mocks match the same request, the first one wins. Send
X-Resterm-Mock: <scenario-name>to pick a specific response. - Resterm does not invent assertions or response sequences. Add
@assertand@expectyourself, then check them withresterm runandresterm mock verify.
_examples/recording.http is a runnable walkthrough that records a local mock server and verifies the result.
What can and cannot be recorded
Supported bodies are empty, JSON, URL-encoded forms, and UTF-8 text. Gzip is decoded in the saved copy only.
Not exportable: binary bodies, multipart, other content encodings, malformed JSON, JSON with duplicate keys, oversized bodies, and bodies that were cut off. Resterm reports why a request or mock could not be exported. Other supported exports remain available, and forwarding continues.
CONNECT tunnels and protocol upgrades are rejected. WebSocket, gRPC, and SSE recording are not currently supported.
A body that would change meaning if written into a request file, for example one whose lines start with # or that contains {{, is saved next to the request file in a resterm-record-* directory. Keep that directory beside the file. Those bodies follow the same redaction rules and are read as literal data, without templates or includes.
Limits and network
Defaults are 1,000 recordings in memory, 64 MiB each for stored recordings and shared capture buffers, 4 MiB per body before and after decoding, and 32 simultaneous captures. Change them with --max-entries, --max-bytes, --body-limit, and --capture-concurrency. Hitting a limit skips a capture or an export. Existing recordings are kept and forwarding continues.
The listener is plain HTTP. The upstream must be a single HTTP(S) origin such as https://api.example.com, with no credentials, path prefix, query, or fragment. TLS uses your system's trusted certificates, and proxy environment variables are ignored. Redirects, CORS headers, cookies, and response URLs are forwarded unchanged, so a redirect can send your app somewhere the recorder never sees.
Fixed
- Keys handled by the stream console or the workflow view no longer also scroll the response pane underneath.
- Scrolling the response pane now keeps stream tail-follow and the cursor position in sync.