Test accounts and secrets

Add the accounts Re:agent, explorations and tests sign in with, and see how Rehearsal handles their passwords and codes.

Re:agent, the subagents of an exploration and your tests all sign in to your app the way a person would, with a test account. Signing in is part of the flow, so a test signs in again on every run and fails if signing in breaks.

A test account belongs to a project. Use accounts made for testing, because explorations and tests create and change things in your app as the people they sign in as.

Kinds of account Link to Kinds of account

How it signs inWhat you giveUse it for
PasswordA username or an email address, and its password. If your app asks for a code after the password, also where that code comes from.Apps with a sign-in form.
PasswordlessA name. Rehearsal makes an email address for the account.Apps that sign in with a code or a link sent by email.

A flow that signs up needs no account. Each browser and each run of the test signs up with a new address from the test inbox and a password Rehearsal keeps. Rehearsal makes that sign-up account for the project itself, so it is not in the list.

Signing in with a Google account, or through any other company, is not supported yet.

Add an account Link to Add an account

  1. Step 1: Open Test accounts

    Open Settings. In the project's group, which reads Project · Parcel, choose Test accounts. Seeing the page needs the Use Re:agent and View projects permissions.

  2. Step 2: Choose how it signs in

    Press Add account. Under How does it sign in?, pick Password or Passwordless.

  3. Step 3: Fill in the details

    • A password account asks for its Username or email and its Password, which Rehearsal types into your sign-in form. Give it a password of at least 4 characters, because a flow that signs in with a shorter one works in the chat but cannot become a test.
    • This account also needs a code after the password is for an app that asks for one. Pick From an authenticator app and paste the Secret key, or the otpauth address its QR code holds. Or pick Sent by email, and the account gets an address of its own where Rehearsal reads the code.
    • Where it works appears when the project has more than one address across its apps, each shown by its kind and host, such as Production · parcel.example. Leave All environments ticked and the account works on every address of the project, including ones you add later. To keep it to some, untick All environments and tick those.
    • Name is how Re:agent picks the account, such as member. It can be up to 40 characters, and no two accounts in the workspace can have the same one. For a password account it follows the username until you type a name of your own.
    • Role is what your app calls this kind of person, such as admin or member. Left empty, the name is the role. An exploration checks your app as each role, so give two accounts the same role when they are the same kind of person.
  4. Step 4: Save it

    Press Add account. Adding an account needs the Manage projects permission.

A passwordless account shows its address before you add it, such as parcel-member@inbox.rehearsal.dev. Create the user in your app with that address once. If you forget, Re:agent offers to sign the account up when your app says it does not exist, and does it when you agree.

Rehearsal makes that address, and the one for a code Sent by email, from your workspace and the first 12 characters of the account's name. The address stays with that account for good, even after you remove it. So no two accounts with an address can share the first 12 characters of their names, removed accounts included, and the form says "That name is already used in this workspace."

Only a person can add a password account. Re:agent can add a passwordless one in the chat when a flow needs it, and it asks you through a question when it needs an account it cannot make.

From a terminal Link to From a terminal

rehearsal accounts add asks for the same things as the form, one question at a time. You type the password where nobody sees it.

A script or a coding agent cannot type it, so it says where the password is with --password-from: env:NAME for an environment variable, file:<path> for a file, or stdin for what is piped in. No flag takes the password itself.

Terminal
# Answer each questionrehearsal accounts add# From a script, with the password already in TEST_PASSWORDrehearsal accounts add --label member --username member@parcel.example --password-from env:TEST_PASSWORD# Read, change and removerehearsal accounts listrehearsal accounts change member --password-from file:member-password.txtrehearsal accounts remove member

rehearsal accounts change changes only what you name, and the password only when you ask for it. Account commands lists every flag.

How accounts are used Link to How accounts are used

In the chat, Re:agent reads the project's accounts and picks one for each browser, by name. Each browser signs in as one account at most. When Re:agent is not sure which to use, it asks a question that starts with the person's name, such as "member: Which account should it use?", and lists the project's accounts. Someone with Manage projects can add one there too, with Add another account under the list, or Add a test account when the project has none, as Questions from Re:agent shows.

An exploration started from the chat takes the project's accounts that work on the address it explores, up to eight, each as its role. If its first pass meets a sign-in page with no account to use, Re:agent asks Can you add a test account for Parcel? When the project has accounts for that address that the exploration was not given, as when it starts from a terminal without --account, it asks Which test account can I use to sign in to Parcel? From a terminal or a coding agent, name the accounts yourself with --account member.

A test keeps the account its flow was saved with and signs in as it on every run. Each account in the list says when it was last used and how. Signed in today means only that Rehearsal typed the account's password or read its inbox today, not that your app let it in.

Sign-in failed today means Rehearsal had nothing it could type for the account: no username or password, a password it could not read, or no mailbox. It does not mean your app turned the password down. The row keeps saying so until a browser signs in as the account again, or until you give it a new username or password with rehearsal accounts change.

While an exploration runs, it keeps the accounts it signs in as to itself, so a bug check cannot change their data underneath it. A check that needs one of those accounts meanwhile does not start. On the bug itself, Create test is answered with "Rehearsal was busy. Try again in a few minutes." When you asked for the check in the chat, its card there says "A test account this bug needs is in use. Try again when the exploration using it ends."

How secrets stay out Link to How secrets stay out

A password, an authenticator's secret key, and a code or a sign-in link from an email are secrets. This is how Rehearsal handles each of them:

  • Rehearsal saves the password and the secret key encrypted, and never shows them again, not even to you.
  • Rehearsal does not give Re:agent the password. Re:agent types {{password}}, and Rehearsal types the real one, only into a password field and only over HTTPS on your app's own host, a host under it or a sign-in host you allowed. For an app on your computer, plain HTTP is allowed through your own connection.
  • A password field takes only the account's password, so Re:agent cannot type a password from a message into one. Put the password in a test account rather than in the chat.
  • Whatever Re:agent types as the password is written down as {{password}}. The test fills secret('password'), or secret('member-password') when the flow has several people, and Retest types the real value while the test runs, so the test file never holds it. It types the account's email address the same way, with secret('email').
  • A code from an authenticator app is written down as {{authenticator}}. Codes of 4 to 8 digits and links that carry a token become {{code}} and {{link}}, as The test inbox explains. A code in any other format is typed as it is.
  • A run's recording leaves out the moments a secret is typed, and the run's page says "Some moments were left out of the video while sign-in details were typed." The live picture in the chat and the recording of Re:agent's own browser keep every frame, so they show whatever a visible field holds, such as an email address or a code. A password field shows only dots.
  • No question from Re:agent asks for a password or a code. One that would is turned away before you see it.
  • Rehearsal's own logs never record a password, a code or a sign-in link.

Sign-in on another host Link to Sign-in on another host

Some apps sign in on a host of their own, such as a separate sign-in service. When Re:agent reaches a sign-in form there in the chat, it stops and asks Allow login.parcel-auth.example for signing in to parcel.example? with Allow and Not now. Allowing needs Manage projects. An allowed host is listed under that address in Settings, Apps, where Remove takes it away again. A subagent of an exploration does not ask, and carries on with the pages it can reach without signing in there.

Allowing a host lets Re:agent sign in there in the chat, but such a flow cannot become a test yet. A test types the password only on the address where that person's browser started, and a sign-in host is another address, even one under your app's own host. The block in the chat then says "This flow types the password on another site. Tests type it only on the app's own address."

A flow that types an authenticator code cannot become a test either, and its block says "This flow types an authenticator code. Tests cannot read authenticator codes yet." An account whose code is Sent by email works in tests.

Change where an account works Link to Change where an account works

Press Change environments on the account's row. Tick All environments for every address of the project, including ones you add later, or tick only the ones it works on. Then press Save. The button appears when the project has more than one address, or when the account works on an address the project no longer has. Changing it needs Manage projects.

From a terminal, rehearsal accounts change member --environment staging does the same, and --environment every covers every environment again.

Remove an account Link to Remove an account

Press the remove button on the account's row and confirm. Re:agent can no longer sign in as it, its address stops receiving mail, and runs still waiting to start with it are cancelled.

A test that signs in with a removed account can no longer run, and its runs end blocked. Edit in chat cannot change it either, so ask Re:agent to create the test again with another account.

Good to know

In the dashboard, only where an account works can change. When the password changes in your app, give the account the new one with rehearsal accounts change, and its tests sign in with it from their next run. A new account never takes over another account's tests, whatever its name.

Next steps Link to Next steps