Session Management

BugBrain automatically caches login sessions to make authenticated tests 5x faster on repeated runs.

How Session Caching Works

User:              BugBrain:
  Click login → Request session
                    ↓
               Acquire browser
                    ↓
               Inject credentials (decrypt)
                    ↓
               Fill login form
                    ↓
               Click Sign In
                    ↓
               Wait for redirect (~8s)
                    ↓
               Extract Playwright storageState
               (cookies + localStorage)
                    ↓
               Save to S3/local filesystem
                    ↓
               Test continues (authenticated)

Run 2: Session Restored

User:              BugBrain:
  Click login → Request session
                    ↓
               Restore cookies + localStorage
               from cache (1 second)
                    ↓
               Navigate to app
                    ↓
               Verify authenticated
                    ↓
               Test continues (authenticated)

Result: Login takes 1 second instead of 8 seconds. 5x faster.

Cache Configuration

Setting	Default	Adjustable	Purpose
Cache TTL	8 hours	Via ENV	How long to keep cached session
Storage	S3 or Local	Via ENV	Where to store session state
Distributed Lock	90 seconds	Via code	Prevent parallel re-auth

Environment Variables

SESSION_CACHE_TTL=28800          # 8 hours in seconds
SESSION_STORAGE_DIR=/sessions    # Local storage path
S3_ENABLED=true                  # Use S3 for storage
AWS_S3_BUCKET=bugbrain-sessions  # S3 bucket name

Distributed Locking

To prevent two workers from re-authenticating the same persona simultaneously:

Worker 1:                Worker 2:
  acquire_lock(persona_id) (success)
                         acquire_lock(persona_id) (blocked)
  ↓ Login...
  ↓ Login succeeds
  ↓ Cache session
  release_lock()
                         ↓ Acquire lock (now available)
                         ↓ Check cache - already exists!
                         ↓ Skip login, use cached session

Lock TTL: 90 seconds (prevents infinite lock if worker crashes) Lock timeout: 30 seconds (poll for lock, max wait)

When Session Cache is Cleared

Sessions are automatically cleared (invalidated) when:

Persona credentials updated — Changed email or password
8 hours have passed — Cache expires
You manually clear — Clear Session button in persona details
Application logs user out — Server invalidates session

Manual Clear

To force a session cache clear:

Go to Personas
Click the persona
Click “Clear Session” button
Next test run will re-authenticate

Useful if:

Session seems corrupted
You want to test fresh login flow
Server-side state changed

Disabling Session Caching

To always use fresh login (disable caching):

Option 1: Disable for a persona

Create a duplicate persona without caching enabled
Use this persona for “fresh login” tests

Option 2: Disable globally (via environment variable)

SESSION_CACHE_ENABLED=false

Multi-Persona Testing

Different personas maintain separate, independent sessions:

Persona: QA Admin
├─ Session: admin_session_xyz
├─ Cache: 8 hours
└─ Expires: 2024-03-08 22:00 UTC

Persona: QA User
├─ Session: user_session_abc
├─ Cache: 8 hours
└─ Expires: 2024-03-08 22:00 UTC

Test 1 uses QA Admin → admin_session_xyz
Test 2 uses QA User → user_session_abc
(both cached independently)

Session Contents

Cached session includes:

{
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123xyz456...",
      "domain": "app.example.com",
      "expires": "2024-03-09T22:00:00Z",
      "httpOnly": true,
      "secure": true
    }
  ],
  "localStorage": {
    "auth_token": "eyJhbGci...",
    "user_id": "12345",
    "preferences": "{...}"
  },
  "sessionStorage": {
    "temp_data": "..."
  }
}

What gets stored:

✅ Cookies (all domains)
✅ localStorage
✅ sessionStorage
❌ IndexedDB (future enhancement)
❌ Service Worker cache (future enhancement)

Performance Impact

Cached vs. fresh login:

Metric	Fresh Login	Cached Session
Time	8-10 seconds	1 second
LLM calls	1 (login decision)	0 (skip login)
LLM cost	~$0.01-0.05	$0
Network calls	10+ (login flow)	1 (verify auth)

Result: Tests are faster and cheaper with session caching.

Storage Backends

Local Filesystem

Default for development
Location: ./sessions/
Structure:
  sessions/
  ├─ org_abc/
  │ ├─ persona_1.json
  │ ├─ persona_2.json
  │ └─ persona_3.json
  └─ org_xyz/
    └─ persona_4.json

Pros: Fast, local, no cloud calls Cons: Lost on server restart, not shared across instances

Amazon S3

Production recommended
Location: s3://bugbrain-sessions/
Structure:
  s3://bugbrain-sessions/
  ├─ org_abc/persona_1.json
  ├─ org_abc/persona_2.json
  └─ org_xyz/persona_4.json

Pros: Persistent, shared across servers, backup Cons: Slight network latency, requires AWS creds

Session Expiry & Refresh

Sessions expire after 8 hours. To extend:

Option 1: Manually clear old session

Click “Clear Session” in Persona settings
Next test creates fresh session (fresh 8 hours)

Option 2: Let it auto-refresh

After 8 hours, cache expires automatically
Next test re-authenticates (cache refreshes)

Security Considerations

Session Isolation

Sessions are isolated per organization:

Org A ├─ Persona 1: session_a_1
      └─ Persona 2: session_a_2

Org B ├─ Persona 3: session_b_1
      └─ Persona 4: session_b_2

(No cross-org session sharing)

Encryption

Sessions are encrypted in transit (HTTPS) and stored encrypted:

In S3:
  ✓ Encryption at rest (AES-256)
  ✓ Encryption in transit (TLS)

In local filesystem:
  ✓ Filesystem permissions (depends on OS)

Access Control

Only the same organization can access its sessions:

User in Org A → Can use Org A sessions
User in Org B → Cannot access Org A sessions
(enforced by org_id FK)

Troubleshooting

Sessions Not Caching

Symptom: Every test run re-authenticates (login takes 8+ seconds)

Causes:

SESSION_CACHE_ENABLED=false (check ENV)
S3 credentials invalid (check AWS setup)
Filesystem permissions denied (check /sessions/)
Session expired (> 8 hours old)

Fix:

Verify ENV: SESSION_CACHE_ENABLED=true
Test S3 connection: Check AWS credentials
Check permissions: ls -la ./sessions/
Manual clear: Click “Clear Session” in persona settings

”Session Already Locked”

Symptom: Two tests for same persona run simultaneously, one fails with lock timeout

Cause: Distributed lock couldn’t be acquired within 30 seconds