Session Validation

This guide explains how TrueAssert validates and reuses authenticated sessions to speed up test execution.

Overview

Session validation is the "fast path" that allows tests to skip the full login process when a valid authenticated session already exists. This significantly speeds up test execution.

How Session Validation Works

The Validation Flow

When a test with login_required=True runs:

1. Check for Session Data:

   • TrueAssert checks if SessionData exists for the project's domain

   • If no session exists → Proceed to full login

   • If session exists → Attempt validation

2. Load Session:

   • Execute LOAD_SESSION command

   • Browser navigates to real domain (not data: URL)

   • Session data (cookies, localStorage, sessionStorage) is injected

3. Execute Validation Steps:

   • Execute last 2 steps from login test:

     • Step 6: GOTO to authenticated page

     • Step 7: WAIT for confirmation element

   • If both steps succeed → Session is valid

   • If either step fails → Session is invalid

4. Decision:

   • Valid Session: Skip full login, proceed with main test

   • Invalid Session: Discard session, execute full login

Why Session Validation Exists

Benefits

• Faster Execution: Skips 5 login steps (username, password, click, etc.)

• Reduced Load: Less stress on authentication system

• Better UX: Tests run faster for users

• Cost Savings: Fewer authentication requests

When It's Used

Session validation is attempted when:

• Test has login_required=True

• SessionData exists for project's domain

• Login test is READY

Validation Steps

Step 6: GOTO to Authenticated Page

This step navigates to a page that requires authentication:

• Example: https://example.com/dashboard

• Purpose: Verify we can access authenticated content

• If fails: Session is invalid

Step 7: WAIT for Confirmation Element

This step waits for an element that confirms authentication:

• Example: //div[@id='user-menu'] or //a[contains(text(), 'Logout')]

• Purpose: Verify we're actually logged in

• If fails: Session is invalid

Why These Steps?

These steps are chosen because:

• They're fast (just navigation + wait)

• They're reliable (confirmation element should always exist when logged in)

• They're sufficient (if we can access authenticated page and see confirmation, we're logged in)

Session Validation vs Full Login

Session Validation (Fast Path)

When Used: Session exists and is valid

Steps Executed:

1. LOAD_SESSION

2. GOTO (to authenticated page)

3. WAIT (for confirmation)

Time: ~2-3 seconds

Result: was_login_needed=False, is_actual_login_happened=False

Full Login (Slow Path)

When Used: No session or validation failed

Steps Executed:

1. CLEAR_BROWSER

2. GOTO (to login page)

3. FILL (username)

4. FILL (password)

5. CLICK (login button)

6. WAIT (for login confirmation)

7. GOTO (to authenticated page)

8. WAIT (for confirmation)

9. SAVE_SESSION

Time: ~10-15 seconds

Result: was_login_needed=True, is_actual_login_happened=True

Understanding the Flow

First Run (No Session)

Test Starts
  ↓
Check SessionData → None found
  ↓
Full Login Required
  ↓
Execute all 7 login steps
  ↓
SAVE_SESSION
  ↓
Session saved to database
  ↓
Execute main test

Second Run (Session Exists)

Test Starts
  ↓
Check SessionData → Found
  ↓
Session Validation Attempt
  ↓
LOAD_SESSION
  ↓
GOTO authenticated page → Success
  ↓
WAIT for confirmation → Success
  ↓
Session Valid! Skip login
  ↓
Execute main test

Third Run (Session Expired)

Test Starts
  ↓
Check SessionData → Found
  ↓
Session Validation Attempt
  ↓
LOAD_SESSION
  ↓
GOTO authenticated page → Success
  ↓
WAIT for confirmation → FAIL (element not found)
  ↓
Session Invalid! Discard session
  ↓
Full Login Required
  ↓
Execute all 7 login steps
  ↓
SAVE_SESSION (new session)
  ↓
Execute main test

Tracking Login Behavior

Login Tracking Fields

TestExecution and DraftingAttempt have two boolean fields:

was_login_needed:

• True: Full login was required (no session or validation failed)

• False: Session validation succeeded, login skipped

is_actual_login_happened:

• True: Full login steps were executed (username/password entered)

• False: Only session validation happened (no username/password)

Example Scenarios

Scenario 1: First Run

• was_login_needed=True (no session existed)

• is_actual_login_happened=True (full login executed)

Scenario 2: Second Run (Session Valid)

• was_login_needed=False (session was valid)

• is_actual_login_happened=False (only validation, no login)

Scenario 3: Third Run (Session Expired)

• was_login_needed=True (validation failed)

• is_actual_login_happened=True (full login executed again)

Troubleshooting

Validation Always Fails

Problem: Session validation fails even with valid session.

Possible Causes:

1. Confirmation Element Changed: The element used for validation no longer exists

2. Session Expired: Cookies expired on server

3. Domain Mismatch: Session domain doesn't match test URL domain

4. GOTO URL Changed: Authenticated page URL changed

Solutions:

1. Update login test validation steps (last 2 steps)

2. Clear session data and create new session

3. Verify domain matches test target URL

4. Update GOTO URL in login test

Validation Succeeds But Test Fails

Problem: Session validation passes but main test fails.

Possible Causes:

• Session is valid but insufficient permissions

• Test needs different authentication level

• Session is for different user

Solutions:

• Check if session has correct permissions

• Verify test requirements match session

• Clear session and re-authenticate with correct user

Session Not Being Reused

Problem: Full login happens every time, session not reused.

Possible Causes:

1. Session validation steps are incorrect

2. Confirmation element selector is wrong

3. Session data not being saved

Solutions:

1. Review login test validation steps

2. Update confirmation element selector

3. Check that SAVE_SESSION executed successfully

4. Verify SessionData exists in database

Best Practices

Validation Steps

1. Use Stable Selectors: Confirmation element should have stable selector (ID, data-testid)

2. Test Manually: Verify validation steps work manually

3. Update When Needed: If page structure changes, update validation steps

Session Management

1. Monitor Reuse: Check was_login_needed to see if sessions are being reused

2. Clear When Needed: Clear sessions if authentication changes

3. Verify Domain: Ensure session domain matches test domain

Debugging

1. Check Tracking Fields: Review was_login_needed and is_actual_login_happened

2. Review Logs: Check controller logs for validation attempts

3. Test Validation Steps: Manually test GOTO + WAIT steps

Related Topics

• Setting Up Login - Configure login flow

• Per-Domain Sessions - Domain-specific sessions

• Running Tests - Execute tests with session management

• Core Concepts - Session management architecture

---

← Back to Documentation | Next: Per-Domain Sessions →