Run Collection
run_collectionRun Bruno collections with parallel execution, isolated group contexts, data-driven iterations, and full test reporting.
Instructions
Execute requests in a Bruno collection and run test scripts. HOW TO RUN A SUBSET: requests takes an ORDERED list of entries, each a .yml/.bru request file or a directory (which expands to every request under it, recursively). Absolute, or relative to collectionPath. Order is yours and duplicates are allowed — naming the same request twice runs it twice. Omit requests to run the whole collection. GROUPS: pass groups instead when one call needs more than one identity or configuration. Each group owns its OWN variable store and cookie jar, so nothing a group sets — a bru.setVar, a session cookie — is visible to any other group. That is what makes running the same five requests as alice and as bob in one call safe. Passing both requests and groups is REJECTED rather than resolved for you. ITERATIONS: data or dataFile runs a group once per row of a table, with the row bound as variables — one call to check the same requests against 50 accounts, or one login against 50 credential pairs. Each row is reported as its own group, with the same name, its own index and an iterationIndex, because each row IS a separate group: it gets that isolation, so two rows differing only in a password authenticate separately instead of one silently reusing the other's token. Rows are independent, so a failing row does not stop the rows after it. Ceiling of 1000 rows per scope. PARALLELISM: parallel on the RUN fans the groups out against each other; parallel on a GROUP fans that group's own requests out. A group is serial unless it says otherwise, whatever the run does. seq no longer constrains execution — it is the default order and the reporting order only, so two requests in one parallel group genuinely run at the same time and may contend on the store they share. A group can also WAIT for another: startAfter holds it until the named group has completed a given number of its requests, which is how you get a listener connected before a trigger fires without a bru.sleep tuned to whatever the latency was the day it was written. It needs parallel on the run, chains are allowed, and cycles or gates that could never open are refused before anything runs; if the group being waited on ends early, the waiting group reports that as its error instead of starting. RESULTS are group-shaped: groups[] each carry their own summary, results, capturedVariableNames and capturedVariables, and the top-level summary is the run. Warnings about the run as a whole are top-level, not per group — a captureVariables name is reported as unset only when NO group set it, since a group's store is isolated and lacking a name there says nothing on its own. There is no top-level results array, in the no-groups case either. A group that crashed outright reports error and counts as one failure in the run summary. Each result includes the response body (response_body, response_content_type, response_body_truncated) by default — disable with includeResponseBody=false or cap the size with maxResponseBodyBytes. Each result also carries response_headers by default, no test script needed (set includeResponseHeaders=false to leave them out, and maxResponseHeaderBytes to bound one value): credential-named values are masked, and set-cookie is a LIST — one entry per cookie — whose entries keep every attribute (HttpOnly, Secure, SameSite, Path, Max-Age) and withhold only the cookie value, so a cookie-flag or HSTS check is one call. includeResponseBody=false does not suppress headers; it bounds the body only. A websocket result carries response_headers too, holding the handshake response (the 101) — the only place a session cookie or an agreed sec-websocket-protocol is visible for that transport; a gRPC result reports its own metadata under the grpc detail instead. Within a group, requests run in the order given; a directory expands by seq, scoped to its own folder, with subfolders before that directory's own loose requests, ties broken by filename. A request file that cannot be parsed is skipped when it was DISCOVERED — by running the whole collection, or by expanding a directory: the count is parseErrors and each skipped file is named with its reason in parseFailures. A file you NAMED yourself is different: you asked for that specific request and there is no partial answer to it, so it fails the group that named it, reported as that group's error, and the other groups still run. A named request that does not exist is reported in that group's missingRequests rather than failing anything, so you can see which subset ran. TRANSPORTS: http, graphql, grpc and websocket requests all run; any other kind is refused per-request with status 0 and a named reason, leaving the rest of the group alone. A gRPC result carries a grpc detail — the gRPC status code (0 is OK, and is NOT the refusal sentinel: status 0 with an error and no grpc detail is a refusal), the method, and redacted metadata. A WebSocket result carries a websocket detail — the transcript, stop_reason naming what ended the session (count, timeout, bytes, closed or error), and truncated, which is true for the three that cut a session short. Frame contents are recorded only if you ask for them, via websocket.includePayloads. ASSERTING ON A TRANSPORT: on a websocket result res.getBody() IS the transcript array — the frames, handed over as a structure — and res.getStatus() is ALWAYS 0, because a session has no status. The outcome is res.getStopReason() (equally res.stopReason, and res.statusText, which carries the same string), res.getCloseCode() for the code the peer closed with (null when it sent no close frame — the ordinary case for a session stopped by its own bound), and res.getSessionTruncated() for whether the recording stops short of the session. Each returns exactly what the websocket detail of the same result reports, so an assertion cannot pass against an outcome the result denies. A test written against res.getStatus() on a websocket asserts on a constant and cannot fail. On a gRPC result res.getStatus() is the gRPC code, res.statusText the server details or the code name, and res.getBody() the parsed message. SIMULTANEITY IS PER CALL: groups plus parallel are the only way to make two things happen at the same moment. Two separate run_collection calls are not serialised by this server, but nothing here decides when the second one starts — that is the caller's scheduling, and a client that issues tool calls one at a time produces runs seconds or tens of seconds apart, which no single result shows. If a test needs one identity listening while another triggers, put both in ONE call as parallel groups; the wall-clock gap between separate calls is not something this server can close. Each result carries the path of the request file it came from, so a failure can be read back or re-run by name. STOPPING EARLY: bail stops the run at the first request that fails or whose tests fail, so a chain of dependent requests reports one cause instead of one failure plus every consequence of it. Everything after it comes back with skipped: true and skipReason: "bail", counted in summary.skipped and in neither passed nor failed, and the run carries a bail object naming the reason, the request it stopped at and how many were skipped. Nothing cancels a request already in flight, so with parallel the requests that had already started still finish and are reported normally. REPORT FILES: pass report to also write the run to disk — JUnit XML for CI, HTML for a person — at a path inside the collection; the files written come back under reports. Outbound requests are SSRF-filtered: targets resolving to private, loopback, link-local or otherwise reserved addresses are refused unless the server operator has allowlisted them, and a refusal is reported per-request as an "SSRF blocked" error with status 0.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bail | No | Stop at the first request that errors or fails a test, instead of running the rest. Bruno's CLI calls this --bail. Use it when the requests depend on each other: without it, a failed login is followed by every request that needed its token failing too, which is four failures to read for one cause. What it stops is bounded by what has already started. Requests not yet started are skipped — in the failing group and in every group after it — and each comes back as a result with skipped:true rather than being left out, so you can see which ones still need running. Requests already in flight are NOT cancelled, so with parallel:true or a parallel group this skips the tail rather than the remainder, and the run says so in its warnings. A skipped request counts in summary.skipped and in neither passed nor failed. Where the run stopped is reported in the result's bail field. Default: false. | |
| data | No | Rows every group iterates over, as the group-level data but applied to all of them. A group that gives its own data or dataFile REPLACES this rather than adding to it, the same rule environment follows. With no groups given, the run is one group and these rows are its iterations. Mutually exclusive with dataFile. | |
| groups | No | Run the same collection under more than one identity or configuration in one call. Each group owns its OWN variable store and cookie jar: nothing a group sets is visible to any other group, in either direction, at any parallel setting. Groups are reported in the order given. The same request may appear in several groups. Cannot be combined with requests; omit both to run the whole collection as one group. | |
| report | No | Write the run to a file, in addition to returning it here. Name at least one format. Paths are CONFINED TO THE COLLECTION: a path resolving outside it is refused, with the reason as a run warning, because writing wherever a caller points is a far bigger authorization than running its requests — copy the file afterwards if your pipeline collects it elsewhere. Missing parent directories inside the collection are created, and an existing report is overwritten. The result reports each file written under reports, with its absolute path and size; a report that could not be written never fails the run, it adds a warning naming the format and the reason. A report holds what the results hold — response bodies included, response headers masked exactly as they are here — so it lands on disk with whatever the run saw. | |
| dataFile | No | A CSV inside the collection whose rows every group iterates over. Same rules as the group-level dataFile, and likewise replaced by a group that names its own rows. Ceiling of 1000 rows, because every row runs every request in the group and a spreadsheet passed by mistake is an outbound request storm; slice the file and run it in parts. | |
| parallel | No | Fan out. At the run level this runs the GROUPS concurrently; a group's own requests are serial unless that group sets its own parallel. With no groups given the run is one group, so parallel here runs every selected request concurrently. Reporting order is the listed order regardless. Default: false. | |
| requests | No | The requests to run, IN THE ORDER GIVEN. Each entry is a .yml or .bru request file, or a directory, which expands to every request under it, recursively. Absolute, or relative to collectionPath. Get paths from list_requests or get_collection_stats. Duplicates are allowed: naming the same request twice runs it twice. Omit to run every request in the collection; an empty [] is a selection of nothing and runs nothing. Cannot be combined with groups. An entry naming nothing is reported in missingRequests rather than failing the run, so you can see which subset ran. | |
| cookieJar | No | Keep cookies from each response and send them on later requests in the same run, so a login carries into the requests after it. Scoped to the group — nothing crosses from one group to another, at any parallel setting — held in memory, never written to disk, and matched by host/path/expiry — a cookie set by one host is not sent to another. Precedence, per cookie name: a Cookie header the request writes itself WINS over the jar, and the jar only adds names the request did not set, so a request that pins a specific credential keeps it and a run that relies on the jar is unaffected. This diverges from Bruno's CLI, where the stored value wins the clash; a warning names any cookie whose stored value was dropped. Default: true, matching Bruno's CLI. Set false to send only the Cookie headers a request writes itself. | |
| variables | No | Variables for this run only, as {name: value}. They override the environment file and work without one. Held in memory and never written to any file — this is the only correct way to supply a secret, because neither Bruno file format stores a secret value. Referenced as {{name}} in urls, headers, bodies and auth. A request-level vars:pre-request entry or a bru.setVar in a script still overrides these, matching Bruno's --env-var precedence. | |
| websocket | No | Bounds for websocket requests in this run. Applies to every websocket request in the call; there is no per-request form. Omit and the defaults below apply. A session always ends on one of these bounds or on the peer closing, and nothing is held open past the call. Each transcript entry carries its frame type ("text", "binary", "ping", "pong" or "close"), the authored title of a message the session sent, and, on a close frame, the close_code the peer gave — 1000 is an ordinary goodbye, 1006 a peer that vanished, 1008 a refusal, 1011 a server error. Control frames do not count toward maxMessages. A binary frame's payload is base64; bytes is the true wire size for every kind. A subprotocol is not a bound and is not set here: author it as a Sec-WebSocket-Protocol header on the request, comma-separated for more than one, and it is negotiated at the handshake — the one the server agreed to comes back in that result's response_headers. | |
| environment | No | Environment name to use (e.g. "dev", "staging"). Get available names from get_collection_stats. | |
| collectionPath | Yes | Absolute path to collection root directory. Use the path returned by list_collections. | |
| collectionRoot | No | The collection that collectionPath belongs to, when running a subfolder of one: environments and the collection- and folder-level scripts are resolved from here. Must be collectionPath itself or an ancestor of it — a root that does not contain the collection is rejected, because its root scripts would then run against these requests. | |
| maxConcurrency | No | Ceiling on requests in flight across the whole run. Omit to derive one from this machine's cores and memory, held below capacity. 0 lifts it entirely, at your own risk. Applies to THIS run and is given back when it ends, so it neither re-caps another run already in flight nor outlives the call that asked for it. A ceiling below the number of requests you meant to run at once silently serialises them, so reproducing a race needs a value at least as large as the number of racers. | |
| captureVariables | No | Names of variables set by bru.setVar during the run whose values you want back, e.g. ["token"]. A script that captures a value out of a response — bru.setVar("token", res.body.token) — makes it available to later requests as {{token}}, and this is the only way to see it yourself; without it the value exists only inside the run. Every name a script set is listed in capturedVariableNames on every run, so run once to see what is there and then ask for the one you need. Values are only returned for names you list here, and they are returned verbatim. Nothing is captured from the environment file or from variables you supplied — only what a script set. | |
| includeResponseBody | No | Include the response body of each request in the results. Default: true. | |
| maxResponseBodyBytes | No | Maximum response body size (bytes) to return per request; longer bodies are truncated and response_body_truncated is set. Default: 10240. | |
| includeResponseHeaders | No | Include the response headers of each request in the results, credential values masked. Default: true, which is what every run did before this option existed. Turn it OFF for a run whose results you read in bulk: a header map is small for one response and not for thirty, and a run of a few dozen requests can spend more of its output on the same headers repeated per result than on anything you asked about. A test script is unaffected either way — res.getHeader() always reads the real headers, as res.body always carries the full body while response_body is gated by includeResponseBody. | |
| maxResponseHeaderBytes | No | Maximum size (bytes) of one header VALUE to return; a longer value is cut and response_headers_truncated is set on that result. Default: 2048. Per value, not per map, so this changes how much of a long value comes back and never which headers are reported — the names are the part worth reading, and dropping a header to save bytes would take its name with it. set-cookie is a list and each cookie is capped on its own. |