Testing Pages Behind HTTP Basic Auth

Basic auth is the padlock of staging environments: one server directive, a username and password, and the site is hidden from crawlers and curious visitors. Then the first automated test runs, the browser throws its native credentials prompt, and the test hangs, because that prompt belongs to the browser rather than the page and no selector can reach it. The fix is easy once you know where it goes; here are the three clean options.

How basic auth actually works (thirty seconds)

The server responds with a 401 and a challenge; the browser shows its native prompt; whatever you type is sent back base64-encoded in an Authorization: Basic ... header on every request. Two properties matter for testing. First, the whole exchange is headers rather than DOM, which is why UI automation cannot interact with it. Second, base64 is encoding rather than encryption, so credentials in the header are readable by anything that can see the traffic or the logs; treat them like secrets even though the mechanism feels casual.

Option 1: credentials in the URL

https://user:password@staging.example.com works in most automation contexts and is fine for a quick local check. Its weakness is hygiene: the credentials become part of the URL, which means they surface in shell history, CI logs, test reports, and any screenshot of an address bar. As a committed pattern in a test suite it is a credential leak on a timer, so use it for experiments and choose one of the next two options for anything permanent.

Option 2: let the test framework send the header

Every serious framework can attach the header before the prompt ever appears. In Playwright, pass httpCredentials when creating the browser context and every request carries the authorization silently (check the current docs page for exact syntax as versions move). Cypress and Selenium have their own equivalents. Keep the values in environment variables fed from your CI secrets store; committing them to the repository defeats the padlock. This is the right answer for teams running their own suites, and the details generalize: it is the same discipline as any authentication setup in e2e.

Option 3: platform-level credentials

If an agent runs your tests, basic auth should be configuration rather than code. In TesterArmy you store the credentials once in the project's auth settings, and the agent presents them on every run against that environment, for web and mobile web alike; the docs page is Basic Auth. Nothing appears in flow descriptions, nothing lands in logs, and rotating the staging password is a one-field edit instead of a secrets-store hunt across pipelines.

The mistakes that keep recurring

• Credentials in the repo. A basic-auth password in playwright.config.ts is the most commonly leaked secret in test codebases, precisely because it protects "just staging". Staging is where your unreleased product lives.
• Testing the prompt. The native dialog is browser chrome; there is nothing of your product in it. Assert what loads after authorization, and keep the padlock out of your assertions.
• Confusing the padlock with the product's login. Basic auth guards the environment; your app's sign-in guards accounts. Tests usually need to pass both, in that order, and failures should make clear which layer refused. If the second layer is where your pain lives, especially SSO and one-time codes, that is its own guide: SSO testing in e2e.

FAQ

Why does my e2e test hang on a site with basic auth? The browser is showing its native credentials prompt, which page-level automation cannot see or click. Supply credentials via the framework's HTTP-credentials option or your platform's auth settings instead.

Is it safe to put basic auth credentials in the URL? For a one-off manual check, tolerable. In automation, no: URLs persist in logs, histories, and reports, and the credentials ride along.

Does basic auth replace testing my app's real login? No. It is an environment gate in front of your app. Your product's authentication still needs its own coverage behind it.