Testing pages behind a login

Personas can start signed in, or sign in themselves as part of every run. Use test accounts on a staging site, never real customer accounts.

1. Add the account

In .personaqa/config.yaml:

auth:
  strategy: storage_state       # or login_mission, see below
  accounts:
    default:
      email: ${PERSONAQA_USER_EMAIL}
      password: ${PERSONAQA_USER_PASSWORD}

${NAME} is read from an environment variable when the config loads, so passwords stay out of the repository; ${NAME:-fallback} supplies a default. Export the variables in your shell, or set them as CI secrets.

You can define several accounts (default, admin, new-customer) and choose one per mission with account: admin. Missions without account use default when auth is switched on.

2. Add a sign-in mission

.personaqa/missions/login.yaml:

id: login
goal: Sign in with your account details.
start_url: /login
account: default
success:
  any:
    - url_contains: /account

Pick a success rule that only passes once signed in. Personas see the account’s email and password in their brief.

3. Choose a strategy

Strategy What happens Use when
storage_state A saved login is loaded into every persona’s browser, so they start signed in You are testing what happens after sign-in, and want runs to be quick
login_mission Each persona signs in first using the sign-in mission. Once its success rule passes, the browser moves them to their real mission The sign-in journey itself is worth testing, or saved logins expire too quickly

Saved login (storage_state)

Create the saved login once:

/personaqa:auth default

A neutral helper signs in with the account, the browser saves the cookies and storage to .personaqa/auth/default.json, and the config is switched to storage_state. It also makes sure .personaqa/auth/ is gitignored: the file holds a live login and must never be committed.

Sites with CAPTCHA, single sign-on or two-factor codes cannot be signed into automatically. Sign in yourself in the browser window this opens, then close it:

npx playwright codegen --save-storage=.personaqa/auth/default.json https://staging.your-app.test

For several accounts, give each its own file:

auth:
  strategy: storage_state
  accounts:
    default: { email: "${USER_EMAIL}", password: "${USER_PASSWORD}", storage_state: .personaqa/auth/default.json }
    admin: { email: "${ADMIN_EMAIL}", password: "${ADMIN_PASSWORD}", storage_state: .personaqa/auth/admin.json }

Saved logins expire. When personas start landing on the sign-in page, run /personaqa:auth again.

Sign-in first (login_mission)

auth:
  strategy: login_mission
  login_mission: login
  accounts:
    default:
      email: ${PERSONAQA_USER_EMAIL}
      password: ${PERSONAQA_USER_PASSWORD}

Every persona’s brief starts with “First you need to sign in”. Sign-in steps count towards the step and time limits, and problems with the sign-in page show up in the report like any other.

In CI

For login_mission, set the account variables as secrets. For storage_state, either run /personaqa:auth at the start of the job (it needs the same secrets) or store the saved login file as an encrypted secret and write it to .personaqa/auth/ before the run.

Checking

/personaqa:validate

reports a login_mission that does not exist. A missing saved login is reported when a run starts, with the command to create it.


Back to top

MIT licence. Personas are simulated users: confirm findings before acting on them.

This site uses Just the Docs, a documentation theme for Jekyll.