Bugster Session Persistence - Share Login State Across Tests

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:

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

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.

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

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.

Session is cached

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

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.

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

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

GETTING STARTED

GUIDES

USING THE CLI

HOSTING AND CI/CD

Persist login sessions across tests

How it works

Prerequisites

How session persistence works

config.yaml

Test 1: View profile (user)

Test 2: Edit profile (user)

Test 3: Admin dashboard (admin)

When to use session persistence

Performance benefits

Troubleshooting

Next steps

Add credentials & roles

Manage your tests

How it works

​Prerequisites

​Configure a test to require login

​How session persistence works

​Example: Multiple tests sharing a session

​config.yaml

​Test 1: View profile (user)

​Test 2: Edit profile (user)

​Test 3: Admin dashboard (admin)

​When to use session persistence

​Performance benefits

​Troubleshooting

​Next steps

Add credentials & roles

Manage your tests

Prerequisites

Configure a test to require login

How session persistence works

Example: Multiple tests sharing a session

config.yaml

Test 1: View profile (user)

Test 2: Edit profile (user)

Test 3: Admin dashboard (admin)

When to use session persistence

Performance benefits

Troubleshooting

Next steps