Saved logins

Signing in at the start of every test is slow and fragile, especially with single sign-on or two-factor prompts. Save the signed-in session once, and let tests start from it.

Saved logins work for web targets. For native apps, keep the app's own state between runs with use.mobile.appState: preserve; see Mobile testing.

Capture a loginCopy Anchor Link

npx agent-qa auth-state capture --target shop-staging --name admin

agent-qa opens a visible browser at the target's URL. Sign in as you normally would, then press Enter in the terminal. It saves the session, including cookies, local storage and IndexedDB. Press Ctrl+C to cancel.

Names use lowercase letters, digits and hyphens, such as admin or read-only-user.

Use itCopy Anchor Link

Load a saved login in a test or a suite:

use:
  authState: admin

The test then starts already signed in. If the login is missing, the run stops with:

Auth state "admin" for target "shop-staging" was not found or could not be read. Run agent-qa auth-state capture --target shop-staging --name admin.

Keep it freshCopy Anchor Link

Sessions expire. Let a test save the session again when it passes:

use:
  authState:
    name: admin
    load: true
    capture: true

With capture: true, agent-qa saves the browser's session after the test passes, or after every test in a suite passes. A test that signs in from scratch can use load: false and capture: true to create the login for the others.

Manage saved loginsCopy Anchor Link

npx agent-qa auth-state list --target shop-staging
npx agent-qa auth-state remove --target shop-staging --name admin

remove without --name removes every saved login for the target.

Where they liveCopy Anchor Link

Saved logins are files under .agent-qa/auth-states/<target>/, or the folder in services.authState.dir. They are not masked, so treat them like passwords:

• keep them out of git, which the .gitignore from init already does;
• never upload them from CI;
• use test accounts with limited access.

Hooks receive the active login as AGENT_QA_AUTH_STATE_STORAGE_STATE_PATH, so a hook can call your API as the same user.