Persist login sessions across tests

Configure tests to share authenticated sessions, eliminating redundant logins and speeding up your test suite.

When you have multiple tests that require authentication, Bugster can log in once and reuse that session across all tests that need it. This eliminates redundant login steps, speeds up your test suite, and makes tests more reliable.

How it works

Tests with requires_login: true share an authenticated session. Bugster logs in once using the specified credential_id, then each subsequent test starts already authenticated—no repeated login flows.

Prerequisites

Before using session persistence, you need:

1. Credentials configured in your config.yaml — see Add credentials, roles & permissions
2. Environment variables set with your login secrets

Configure a test to require login

Add two fields to your test YAML:

name: Dashboard data export
page: /dashboard
page_path: app/dashboard/page.tsx
credential_id: user
requires_login: true
task: Export dashboard data as CSV
steps:
  - Navigate to the dashboard
  - Click the export button
  - Select CSV format
  - Verify the download starts
expected_result: CSV file download should begin automatically

credential_id · string · required

The ID of the credential profile to use for authentication. Must match a credentials[].id in your config.yaml.

requires_login · boolean · required

Set to true to indicate this test needs an authenticated session. Bugster will ensure the user is logged in before the test begins.

How session persistence works

1. First test with requires_login runs

   Bugster detects requires_login: true and credential_id: user. It performs the login flow using the credentials from config.yaml.

2. Session is cached

   After successful authentication, Bugster stores the session (cookies, tokens, local storage) for reuse.

3. Subsequent tests skip login

   Any other test with the same credential_id and requires_login: true will start with the cached session—no login flow needed.

Session persistence works per credential_id. If you have tests using different credentials (e.g., user vs admin), Bugster maintains separate sessions for each.

Sessions are regenerated on each bugster run command. The cached session only persists within a single test run. When you execute bugster run again, Bugster will perform a fresh login for the first test that requires it.

Example: Multiple tests sharing a session

Here’s how a typical test suite might look with session persistence:

config.yaml

project_name: my-app
project_id: my-app-123
base_url: "http://localhost:3000"

credentials:
  - id: user
    username: ${BUGSTER_USERNAME}
    password: ${BUGSTER_PASSWORD}
    
  - id: admin
    username: ${BUGSTER_ADMIN_USERNAME}
    password: ${BUGSTER_ADMIN_PASSWORD}

Test 1: View profile (user)

name: View user profile
page: /profile
credential_id: user
requires_login: true
task: View and verify profile information
steps:
  - Navigate to profile page
  - Verify username is displayed
  - Verify email is displayed
expected_result: Profile page shows correct user information

Test 2: Edit profile (user)

name: Edit user profile
page: /profile/edit
credential_id: user
requires_login: true
task: Update profile display name
steps:
  - Navigate to profile edit page
  - Change display name
  - Save changes
  - Verify success message
expected_result: Profile updates successfully with confirmation message

Test 3: Admin dashboard (admin)

name: Admin user management
page: /admin/users
credential_id: admin
requires_login: true
task: View user list in admin panel
steps:
  - Navigate to admin users page
  - Verify user list is displayed
  - Check pagination works
expected_result: Admin can see and navigate the user list

In this example, Test 1 and Test 2 share the same user session—Bugster logs in once. Test 3 uses a different credential (admin), so it gets its own login session.

When to use session persistence

Use requires_login: true when...

• Your test interacts with authenticated-only pages
• You’re testing features behind a login wall
• You want to verify user-specific data or permissions
• You’re running multiple tests that all need the same authenticated state

Don't use requires_login when...

• The test is for public/unauthenticated pages
• You’re testing the login flow itself
• The test explicitly needs to start logged out

Performance benefits

Session persistence significantly reduces test execution time:

Scenario	Without persistence	With persistence
10 tests requiring login	10 login flows (~30s each)	1 login flow
Total login overhead	~5 minutes	~30 seconds

Pro tip: Group tests by credential_id when running your suite. This maximizes session reuse and minimizes total execution time.

Troubleshooting

Test fails saying user is not logged in

• Verify credential_id matches exactly with a credentials[].id in config.yaml
• Check that environment variables are set correctly in .bugster/.env
• Ensure the login page and flow haven’t changed

Session not persisting between tests

• Confirm both tests have requires_login: true
• Verify both tests use the same credential_id
• Check if your app has aggressive session timeouts

Wrong user in test

• Double-check the credential_id in your test file
• Verify environment variables point to the correct credentials
• Ensure you’re not mixing up credential IDs between environments

Next steps

Add credentials & roles

Set up multiple credential profiles for different user roles

Manage your tests

Learn how to organize and run your test suite effectively