Testing Behind Bot Protection

Cloudflare, AWS WAF, Akamai, and similar services protect sites by challenging or blocking traffic that doesn't look like a regular visitor. DontBreak's cloud browsers are real Chrome and Firefox instances, but they run in a data center (AWS us-east-1, on IP addresses that change from run to run) — so a strict bot-protection setup may challenge or block them before your test even starts. DontBreak's Test Traffic describes exactly what that traffic looks like. The symptom is usually a test that fails on its very first step: the screenshot shows a "Verify you are human" interstitial or an access-denied page instead of your site.

The fix is not to sneak past your own protection — it's to let your own testing traffic in. Since you're testing a site you control, you can add a narrow exception, and the cleanest way is a secret custom header. There's no fixed IP list to allow-list, and allowing the browser's user agent would let every visitor with the same browser through.

Custom request headers

Every test can send extra HTTP headers with every request to your site:

Open test settings

Open Test → Settings and go to the Authentication tab.

Enable Custom Request Headers

Toggle Custom Request Headers and add a header — for example, name X-DontBreak-Bypass with a long random value. Header values are encrypted at rest and never shown again after saving; a blank value on later edits keeps the stored one.

Add a matching skip rule on your site

Configure your WAF or bot-protection service to skip challenges when the request carries your secret header (recipes below).

For a whole environment, set the headers once on the test suite instead: new tests created in the suite inherit them, and Apply headers to all existing tests in this suite propagates them (and later rotations of the secret) to every member test in one save.

Custom headers are sent by test runs on every browser and screen size, and the editor uses them too while you build the test. They go only to your site's own domain and its subdomains (for example api.example.com when the test starts on www.example.com); third-party services the page loads, such as a payment provider or analytics, never see them. Headers also cover other setups than bot protection — a Authorization: Bearer … token for a header-authed staging environment, a feature-flag or debug header, or ngrok-skip-browser-warning for tunnel-hosted previews.

A few header names are reserved

Browser-managed and connection-level headers (Host, Content-Length, Cookie, and similar) can't be overridden. To pre-set a cookie, use the Set Cookie step instead — see Interactions.

Cloudflare: skip rule

In the Cloudflare dashboard for your zone:

Go to Security → WAF → Custom rules and create a rule.
Expression: any(http.request.headers["x-dontbreak-bypass"][*] eq "your-secret-value") (header names are matched lowercase).
Action: Skip, and tick the features to skip — at minimum Bot Fight Mode / Super Bot Fight Mode and Managed Challenge.

If you use Turnstile on specific pages, a skip rule won't remove the widget itself — test those flows on an environment where Turnstile runs in testing mode (Cloudflare provides always-pass test site keys).

AWS WAF (CloudFront, ALB)

CloudFront itself doesn't block bots — blocking comes from an attached AWS WAF web ACL (often with the Bot Control managed rule group). To let test traffic through:

In the WAF console, open your web ACL and add a rule above the Bot Control rule group.
Match condition: header x-dontbreak-bypass equals your secret value.
Action: Allow (rules are evaluated top-down, so an early Allow short-circuits Bot Control).

Other options

Basic auth instead — if your staging environment is simply behind HTTP basic auth rather than a bot wall, use the built-in basic authentication support.
Test a preview environment — point your tests at a staging or preview environment with a fixed URL that isn't behind the production bot wall, and trigger them from CI (via the GitHub Action) after each deploy there.
Rotate the secret — treat the header value like a password: long, random, and rotated if it leaks. Saving a new value in test settings replaces the old one.

DontBreak does not evade bot detection

Custom headers are a cooperation mechanism for sites you own or are authorized to test. DontBreak doesn't spoof fingerprints or route through residential proxies to defeat bot protection on sites that haven't let it in — and won't.

In the editor

The editor sends the same custom headers as test runs, so once your skip rule is in place the editor's browser gets through as well. If a challenge still shows up while you build a test (for example before you've added the header), complete it by hand and carry on: pick the next action or check, point at the element, and test the step.

Next steps

Connecting Your Site — URLs, basic auth, staging vs. production
Test Settings — everything else in the settings dialog
Common Errors — diagnosing failed first steps
DontBreak's Test Traffic — where runs come from and how to report unwanted traffic