Custom HTTP headers

You can configure mabl browser tests to pass custom HTTP headers with each request in plan runs and in local ad hoc runs. 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.

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

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.

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.

Trainer and local Desktop runs

To apply custom HTTP headers during training sessions and local runs, open the Preferences menu: Edit > Preferences.

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.

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