Test users

A test user is a saved sign-in identity that Matcha runs as inside your app. When a run signs in, it does so as one of these users, so you never paste credentials into a prompt. Test users belong to a TeaHouse, so a whole team shares them, and Matcha reuses them across runs, tests, and groups.

A run that carries no test user runs signed out (anonymous). Site protection is a separate concern: it opens the deployment before your app loads, while a test user signs in once your app is open. See site protection.

What a test user holds

Each test user lives in a named environment (for example "Staging") and carries the facts Matcha needs to sign in:

A display name, so a person can pick it.
A login identifier: an email, a username, a phone number, or a custom label and value.
The secret: a password, and where relevant a TOTP secret.
An optional description telling an agent when to pick this user over the others.

Coldtea stores the password and TOTP secret as secrets and never returns them to the UI.

Auth methods

A web test user signs in one of three ways:

A password, through the app's own sign-in form.
A password plus a time-based one-time code.
An SSO provider instead of a password form. Google, Microsoft, GitHub, Okta, and Auth0 are supported.

A mobile test user signs in with a password, or a password plus a one-time code. Mobile does not use SSO.

Accounts Matcha owns

Some apps have no shared credential to hand over: they email a login code on every sign-in. For those, let Matcha own the account. It creates one on an inbox it can read, so you supply no login identifier and no password, and it tells you the address it created. On each run, Matcha reads the emailed code and signs in.

Create and list test users

Create and list test users from the Matcha QA screen, or ask an agent to do it. To create a web test user you give it a name, an environment, the address of the app it signs into, the login identifier, and the password. Add a one-time-code secret or an SSO provider if the app needs one, or hand the account to Matcha for an app that emails a login code.

See MCP and local API for the QA tools.

Run as a test user

A run signs in as exactly one saved test user, or as nobody.

A web run must run as a web test user or run signed out.
A mobile run must run as a mobile test user whose platform matches the run, or run signed out.

When you run under a group, the run inherits the group's identity, so you do not pick one every time. A saved test can override its group's identity when a specific flow needs a different account.

Temporary inboxes for a run

Beyond saved test users, Matcha can create disposable email inboxes during a run and read them, for flows that need a fresh address: a sign-up, an invite, a magic link, or a one-time code. Each inbox belongs to that run alone and expires after a day, so a sign-up gets a clean mailbox without touching a real one. You can watch it happen in the run's Tools tab.

Tests and groups: where a group's run-as identity is set and inherited.
Runs and results: the run records which identity it used.