Skip to main content
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

  • 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
  • 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:
ScenarioWithout persistenceWith persistence
10 tests requiring login10 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

  • 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
  • Confirm both tests have requires_login: true
  • Verify both tests use the same credential_id
  • Check if your app has aggressive session timeouts
  • 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