Login and Authentication
When a test runs as a User that has authentication configured, msg.ZenTestAI logs in automatically at the start of the test. This page explains the authentication modes available, the fields they need, and what happens at runtime.
Authentication modes
The Authentication section of a User offers five modes. Pick the one that matches the application under test:
| Mode | Use when… |
|---|---|
| None | The application has no login (public pages). |
| Password (Basic Auth) | Standard user-name + password login (the most common case). A Variant dropdown chooses how the credentials are delivered. |
| OAuth + TOTP | Login with a time-based one-time password (Google Authenticator / Microsoft Authenticator style). |
| HOTP | Counter-based one-time password (token increments with each use), optionally with a PIN. |
| Yubikey OTP | Simulation of a hardware Yubikey token using an AES key and public/private identifiers. |
For end-to-end tests, keep the login as simple as the application allows. Every extra factor costs time on every test run and is a frequent source of flakiness.
Mode details
None
No login step is performed. The test starts directly on its Start URL. Use this mode for public-facing pages, or when you intentionally want to bypass authentication.
You can also force a login-less run by switching Login required off on the General tab of a specific test, even if the assigned User is otherwise authenticated.
Password (Basic Auth)
The bread-and-butter mode. You provide a User ID and a Password, and a Variant dropdown chooses how the credentials reach the application:
| Variant | Behavior |
|---|---|
| Login Page | A real login form on the application's login page. The AI agent locates the fields, types the credentials, and clicks the submit button. |
| HTTP Headers (Basic) | Credentials are sent in the browser's native HTTP Authorization header (the small browser-native dialog that pops up on top-level HTTP basic auth). |
| HTTP Headers (Bearer) | Credentials are sent as a bearer token in the Authorization header. |
| NTLM Auth | Windows NTLM authentication, performed silently without a login page. |
| NTLM Auth + Login Page | NTLM authentication followed by an additional login form, for applications that combine both. |
Variants that send credentials in HTTP headers attach them to every request the browser makes during the test. If your test then calls an external API, the basic-auth credentials would be sent to that API too. Prefer the Login Page variant whenever the application offers a real form.
OAuth + TOTP
Username + password, plus a TOTP Secret (the shared secret you see when setting up two-factor authentication in the target application). Setup:
- Sign in to the target application with the User you want to use for testing.
- Add a new authenticator device (Authenticator app / TOTP).
- You will get a QR code or a secret key. Copy the secret key (or decode the QR code) and paste it into the TOTP Secret field on the User.
- Click the refresh button next to the secret to generate the current one-time password.
- Enter that one-time password back in the target application to confirm the device.
From then on, every test run will look up the TOTP secret, generate the current code, and feed it to the AI agent for the second factor.
msg.ZenTestAI expects the configured TOTP device to be the only (or first) one on the User account — the AI agent does not pick a device from a list of multiple authenticators.
HOTP
Like TOTP, but counter-based. Tokens stay valid until used; the counter increments after each use. In addition to User ID, Password and HOTP Secret you may need to provide a PIN if your authentication provider requires one.
The User editor includes a small edit button next to the secret that lets you manually adjust the HOTP counter — useful when it drifts out of sync with the target system.
Every time you press the refresh button to preview a token, the counter advances. If the counter on msg.ZenTestAI and the counter on the authentication provider get out of sync, login will fail; use the edit button to realign them.
Yubikey OTP
Simulates a hardware Yubikey. You need three Yubikey-specific values from your provisioning:
- Yubikey AES Key (128-bit AES key in hex)
- Yubikey Public ID (the public identifier prefix)
- Yubikey Private ID (the private identifier, 6 bytes hex)
…plus the User ID and Password. An optional PIN is available when the provider requires it.
How the login runs at execution time
When a test starts and Login required is enabled on the test (it is, by default, whenever the assigned User has any authentication mode other than None), msg.ZenTestAI:
- Injects a login step as Step 0 of the test execution.
- Navigates to the test's start URL (or the URL the Application Settings point to for that host).
- Looks for a shortcut login strategy matching the host (msg.ZenTestAI ships with deterministic strategies for several common identity providers). If one matches, it is used.
- Otherwise, a dedicated login agent inspects the page, identifies the user/password (and OTP) fields, fills them in with the User's credentials, and clicks through any "Next" / "Sign in" buttons until login completes.
- If the login does not complete within ~30 seconds, msg.ZenTestAI retries once (with a fresh browser context). If the second attempt also fails, the test execution fails.
A few important properties of this flow:
- The login step is always first — it cannot be moved mid-test.
- Two-factor codes are detected automatically: the login agent looks for an OTP field on the page and, if found, fetches the next code from the User's TOTP/HOTP/Yubikey secret. No extra switch needed.
- Per-host customization (timeouts, "Step 0: Execute before login", "Step 0: Execute after login" steps) lives in Additional Functions → Application Settings, not on the User. Use it to inject deterministic steps that the AI shouldn't have to figure out.
Do not put credentials inside test steps or snippets. msg.ZenTestAI does not encrypt step text; the User's encrypted secret storage is the only safe place for them.
Login reuse between tests
Logging in is one of the slowest things a test can do, so msg.ZenTestAI caches the post-login state and reuses it across runs when possible:
- The cache is keyed by User + host.
- Cached entries live for 10 minutes, after which they expire and a fresh login is performed on the next run.
- Both cookies and localStorage captured after login are restored on reuse.
Reuse is automatic — there is no toggle. If a cache hit produces unexpected behavior because your application keeps state in a long-lived session, the simplest workarounds are to wait out the 10 minutes, change the User's password (which invalidates the cached secret hash), or use a different User per run.
If the application persists data in cookies or localStorage across logins (e.g. a stateful shopping cart), reusing the cached session can leak state between tests. Design tests to be independent — assume nothing about local-storage contents at start.
Multi-user scenarios
A test case has exactly one User. The login is always the first step. To exercise scenarios that span multiple actors:
- Across tests — split the flow into several tests, each with its own User, and chain them with an execution plan. Use Remember steps and parameter bindings to pass context (e.g. an order ID) from one test to the next.
- Within one test — wrap the secondary login in a snippet with Login required enabled and the Isolated toggle on. The snippet runs in its own browser context with its own login, and the original session is restored when the snippet returns. See Test-Case Definition → Snippets.
Need a different authentication scenario?
If your application uses an authentication flow that doesn't fit into one of the modes above (SAML, custom SSO, certificate-based, …), contact msg.ZenTestAI support at hello@zentest.ai — we are happy to help.