Complete reference for the bru.ctx object available inside every Bruno App.
Before your App code runs, Bruno injects a global window.bru into the guest page. All interaction with Bruno happens through bru.ctx.
Your App │ bru.ctx │ Bruno
Instead of using fetch() directly, your App calls bru.ctx.submitRequest() or bru.ctx.runRequest(). Bruno then interpolates variables, runs pre/post scripts, executes assertions and tests, records the timeline, and updates the response pane — exactly as if you pressed Send.
bru.ctx data arrives asynchronously after page load. Reading bru.ctx.http.response, bru.ctx.variables.resolved, or any other state field at the top level or inside DOMContentLoaded returns null or empty values.Always do the first render inside bru.ctx.onInit. React to later changes via the on*Change callbacks.
Shared surface
These fields and methods are available in both request-level and collection-level Apps.
Field
Type
Description
bru.ctx.theme
{ name, mode, config }
mode is 'light' | 'dark', also mirrored as a light / dark class on document.body. config is the full resolved theme object (colors, tokens, etc.).
bru.ctx.variables.resolved
Record<string, any>
Merged, read-only snapshot of all variables: global env → active env → collection vars → runtime vars (later keys win).
bru.ctx.variables.runtime.set(name, value)
function
Persists a runtime variable on the active collection for the session. Same scope as bru.setVar in scripts.
bru.ctx.log(...args)
function
Logs to the App’s own console and forwards to Bruno’s host console as [app] ….
bru.ctx.onInit
(bru) => void
Assigned by your code. Called once when the initial state arrives. The argument is bru (not ctx) — access state via bru.ctx.* inside the callback.
bru.ctx.onThemeChange
(theme) => void
Assigned by your code. Called when the theme changes.
bru.ctx.onVariablesChange
(variables) => void
Assigned by your code. Called when any merged variable changes.
Reading theme
// Check light/darkconst isDark = bru.ctx.theme.mode === 'dark';// Read a specific tokenconst primaryColor = bru.ctx.theme.config.colors.primary;// Or use the body class added automaticallydocument.body.classList.contains('dark'); // true in dark mode
bru.ctx.variables.runtime.set('token', loginRes.data.token);// Now {{token}} resolves in all subsequent requests
Request-level App
These fields are only available on request-level Apps. They do not exist on collection Apps.
Field
Type
Description
bru.ctx.http.response
Response | null
The latest response for this request, from any source (Send button, runner, or the App itself).
bru.ctx.http.onResponseChange
(response) => void
Assigned by your code. Fired whenever a new response arrives.
bru.ctx.assertions
Assertion[]
Results of the latest assertion run for this request.
bru.ctx.tests
Test[]
Results of the latest test run for this request.
bru.ctx.onAssertionsChange
(assertions) => void
Assigned by your code. Fired when assertion results update.
bru.ctx.onTestsChange
(tests) => void
Assigned by your code. Fired when test results update.
bru.ctx.submitRequest(options?)
(options?) => Promise<Response>
Sends the parent request through the full Bruno pipeline. See Overrides.
Sending the parent request
// Simple sendconst res = await bru.ctx.submitRequest();console.log(res.status, res.data);// Send with runtime variable overridesconst res = await bru.ctx.submitRequest({ runtimeVariables: { userId: '42' }});
The request must reference {{userId}} in its URL, body, params, or headers. Bruno interpolates the variable — it does not search-and-replace literal strings.
type Test = { uid: string, description: string, status: 'pass' | 'fail', error?: string}
Overrides
Both submitRequest and runRequest accept an optional options object:
{ runtimeVariables: { key: 'value', // … }}
How overrides work:
Values are injected as ephemeral runtime variables for that single send only.
They take precedence over all other variable scopes (global env, active env, collection vars, persistent runtime vars).
The request must reference them using {{name}} syntax — Bruno interpolates the variable at runtime. Hard-coded literal strings in the request body are not matched or replaced.
Overrides do not persist. To persist a value across requests, use bru.ctx.variables.runtime.set(name, value).
Tips
bru.ctx.theme is an object, not a string.
Use bru.ctx.theme.mode for the light/dark switch. The mode is also mirrored as a light / dark class on document.body.onInit receives bru, not ctx.
The callback signature is (bru) => void. Access all state as bru.ctx.* inside it.
// Correctbru.ctx.onInit = (bru) => { console.log(bru.ctx.variables.resolved);};// Also works (bru is the same global)bru.ctx.onInit = () => { console.log(bru.ctx.variables.resolved);};
Overrides are nested under runtimeVariables.
Flat top-level keys on the options object are ignored.
// Correctbru.ctx.submitRequest({ runtimeVariables: { id: '1' } });// Wrong — id is silently ignoredbru.ctx.submitRequest({ id: '1' });
Pathnames are absolute filesystem paths.listRequests returns paths like /Users/me/collections/myapi/users/get-user.bru. They are stable as long as the file is not moved or renamed.No bru.ctx.http or bru.ctx.submitRequest on collection Apps.
Those fields are request-level only. Accessing them on a collection App returns undefined.No bru.ctx.listRequests or bru.ctx.runRequest on request Apps.
Those methods are collection-level only.Variable precedence.bru.ctx.variables.runtime.set and runtimeVariables overrides both write to the runtime scope, which sits at the top of Bruno’s precedence chain: global env → active env → collection vars → runtime vars.