Custom HTTP headers

You can configure mabl browser tests to pass custom HTTP headers with each request. Custom HTTP headers are most often used to make requests from mabl test runs recognizable to your application’s security or routing layers, so that they aren’t treated like general bot traffic:

• Bypass bot protection - bypass captcha, reCAPTCHA, Cloudflare bot blocking, or other similar restrictions on test environments.
• Skip extra authentication steps - bypass additional MFA prompts or security challenges for unrecognized clients.
• Toggle feature flags or test feature branches - force a specific application experience or test experimental variants.
• Route requests to a specific environment or backend - direct traffic to a specific environment, backend cluster, or geographic region.

This article explains how to set up mabl tests with custom HTTP headers.

Server-side configuration

Before you add headers to mabl tests, you’ll need to coordinate with your security or DevOps team to set up header rules for your app:

1. Decide on a header name, such as X-Mabl-Bypass, and a secure value.
2. Create a rule in your application or WAF that implements the correct behavior when this header is present.
3. For sensitive functionality, such as auth bypass, ensure the rule is restricted to non-production environments or allowlisted to mabl’s static IP range.

Some hosting platforms and security services generate the header names and values for you instead, and those values can expire. When you get new values, update the headers in your mabl tests.

Add custom HTTP headers to your mabl tests

After configuring custom headers and rules for your application, you can add the headers to mabl tests:

• Plan runs
• Ad hoc cloud runs
• Trainer and local Desktop runs
• Local CLI runs
• Set a header from a test step

Plan runs

To specify custom HTTP headers for plan runs, edit the plan in the mabl app. Scroll to the Browser device settings section, click on Additional settings, and toggle on Send custom HTTP headers.

Add the key-value pair(s) you created on the server side.

Adding a custom HTTP header

Headers apply to all browser tests within a plan that runs in the cloud, whether that be on a schedule, on deployment as a deployment event, or triggered manually.

Ad hoc cloud runs

You can attach HTTP headers to ad hoc cloud runs triggered from the mabl app, CLI, or MCP:

• mabl app - add custom HTTP headers from the ad hoc run panel before starting the run.
• mabl CLI - use mabl tests run-cloud with the http-headers flag
• mabl MCP - tell your AI client which HTTP headers you want to apply to a cloud run

HTTP headers applied to ad hoc cloud runs do not get saved to the test. You must add them again the next time you want the test to use them.

Trainer and local Desktop runs

To apply custom HTTP headers during training sessions and local runs, update your settings from the mabl app menu bar: Edit > Preferences > HTTP headers.

Preferences menu

Select the HTTP headers option on the left and add any extra headers as needed. To turn off a header without removing it, uncheck the corresponding checkbox under the “Enabled” column.

Adding custom HTTP headers in the Preferences menu

Custom HTTP headers configured in the Preferences menu will apply to local test runs and Trainer playback for your specific instance of the mabl Desktop App. If other teammates need to use these headers for local Desktop runs, they’ll need to configure their own headers in the preferences menu.

Local CLI runs

Local CLI runs do not inherit headers from the Desktop or plan settings. To apply custom HTTP headers during local CLI runs, including tests triggered --from-plan-id, use the --http-headers flag. For example:

mabl tests run --id {test-id} --http-headers x-header:foo

Set a header from a test step

The options above fix a header's value before the run starts. To send a header from a specific point in a browser test, add a Set HTTP header step. From that step on, the browser sends the header on every request it makes for the rest of the test, including page loads, scripts, images, fetch and XHR calls, and new tabs. The step is saved with the test, so it applies wherever the test runs.

1. Open the test in the mabl Trainer or in quick edit.
2. Click + (Add step) > HTTP header.
3. Enter the Header name and Header value. Both fields accept variables with the {{@variable_name}} syntax.
4. Click OK.

Because the value accepts variables, the step can send a value your test only learns as it runs. For example, call your login API in an API step, save the returned session token to a variable, and send it as {{@token}} on every browser request that follows.

• Other custom headers - Headers from the plan, the ad hoc run, Desktop preferences, or the CLI still apply alongside the step.
• Changing the value - Add another Set HTTP header step with the same header name later in the test. The new value replaces the old one. Header names are case-insensitive.
• Logs - The header value doesn't appear in run logs or test output.
• mabl CLI - To run a test with this step from the mabl CLI, use version 2.141.10 or later.

You can also ask the mabl agent to add the step while it builds a test, for example: "After the login API call, send the returned token as the x-session-token header on every request."