Docs
Login options
To test flows behind login, the agent needs a way in. Pick one option per environment. The agent never uses a real customer account.
Which option to pick
| Option | When to use it | Support |
|---|---|---|
| Agent signs up with a WitnessQA inbox | Easiest. Also tests your sign-up and email confirmation. | Full |
| Test account you provide | Sign-up is complex, manual or invite only. | Full |
| Test account with TOTP | Your app requires an authenticator app for 2FA. | Full |
| SMS 2FA | Not recommended. Turn off 2FA for the test account. | Limited |
| Google or SSO | Not recommended. Add email and password for the test account. | Limited |
Before you start: the environment must be verified. See Verify ownership.
Agent signs up with a WitnessQA inbox
For each run the agent gets its own address, like run-8f2c1e@inbox.witnessqa.com. It signs up like a new
customer, then reads the confirmation email, OTP codes and magic links from that inbox. Public temp-mail services are
not used, because many apps block them.
-
Pick the inbox option
Open the environment, go to Login and pick Sign up with a WitnessQA inbox.
Pick one option per environment. -
Allow the inbox domain if your app filters emails
If your sign-up blocks unknown email domains, allow
inbox.witnessqa.comon staging. If you use a CAPTCHA, turn it off on staging or use your provider's test keys.The inbox settings show the domain to allow. -
Watch the agent read the email
In the run, the inbox step shows the email the agent received and the code or link it used.
Step 6 of a run: the agent read the OTP from its inbox.
Test account you provide
Create a dedicated account for the agent on that environment. Never use a real customer account or your own.
-
Create the account in your app
Sign up as a normal user on staging, or create the user from your admin panel. Give it the role you want tested.
A normal sign-up in your app. Use an address you control. -
Enter the credentials in WitnessQA
Pick Use my test account and enter the email and password. Credentials are stored encrypted, used only for this environment and never shown in reports.
Enter the test account credentials.
Test account with TOTP
If your app asks for a code from an authenticator app, give WitnessQA the TOTP secret. The agent generates the 6 digit code itself, the same way Google Authenticator or 1Password does.
-
Copy the secret when you set up 2FA
While setting up 2FA for the test account, click the link under the QR code, usually Can't scan it?, to see the secret as text.
Most apps show the secret as text under the QR code. -
Paste the secret in WitnessQA
Pick Test account with TOTP, enter the email, password and secret, and click Save and test login. WitnessQA shows the current code so you can check it matches your authenticator app.
The current code is shown so you can compare it with your app.
SMS 2FA
SMS codes go to a real phone, so the agent cannot read them reliably. For the test account on staging, turn off 2FA or switch it to TOTP. If neither is possible, the run stops at the SMS step and marks it as needing a human.
Google or SSO
Google, Microsoft and SSO logins add bot checks and device prompts that break automated runs. Give the test account an email and password login on staging. If your app only has SSO, ask us about a test identity provider during early access.