Session Management

This guide explains how to configure authentication flows for your tests using TrueAssert's session management system.

Overview

TrueAssert's session management allows you to:

• Automatically handle login flows for tests

• Reuse authenticated sessions across test runs

• Store browser session data (cookies, localStorage, sessionStorage)

• Skip login when session is still valid

When to Use Session Management

Use session management when:

• Your tests require authentication

• You want to avoid logging in for every test run

• You need to test authenticated user flows

• You want faster test execution (session reuse)

Setting Up Login

Step 1: Configure Project Login Settings

1. Navigate to Project Settings → Login (Project Settings Login)

2. Fill in the login form:

   • Login URL: The URL where users log in (e.g., https://example.com/login)

   • Login Username: Username for authentication

   • Login Password: Password for authentication

3. Click "Save"

Step 2: Generate Login Test

After saving login settings:

1. TrueAssert automatically creates a Login Test for your project

2. The login test has is_system_test=True (hidden from main test list)

3. Status starts as DRAFTING

4. Background processor generates login steps automatically

Step 3: Review Login Test

1. Go to Project Settings → Login

2. Click "Review Login" button

3. Review the generated login steps:

   • GOTO to login page

   • FILL username field

   • FILL password field

   • CLICK login button

   • WAIT for confirmation element

   • GOTO authenticated page

   • WAIT for confirmation element

4. Verify steps are correct

5. Click "Finish Review" to mark test as READY

Step 4: Use in Tests

When creating a test:

1. Check "Login Required" checkbox

2. Test will automatically use login flow

3. Session will be saved after first successful login

4. Future runs will reuse session if still valid

Login Test Structure

The login test follows a specific 7-step structure:

1. GOTO - Navigate to login page

2. FILL - Enter username

3. FILL - Enter password

4. CLICK - Click login button

5. WAIT - Wait for login confirmation element

6. GOTO - Navigate to authenticated page (e.g., dashboard)

7. WAIT - Wait for confirmation element on authenticated page

Important: The last 2 steps (GOTO + WAIT) are used for session validation.

How Login Flow Works

During Test Execution

When a test with login_required=True runs:

1. Session Validation (first attempt):

   • Check if SessionData exists for project's domain

   • If exists, execute LOAD_SESSION command

   • Execute validation steps (last 2 steps from login test)

   • If validation succeeds: Skip full login, proceed with test

   • If validation fails: Proceed to full login

2. Full Login (if validation fails or no session):

   • Execute CLEAR_BROWSER command

   • Execute all 7 login test steps

   • Execute SAVE_SESSION command

   • Save session data to database

   • Proceed with main test

Session Data Storage

Session data is stored in the SessionData model:

• OneToOne relationship with Project

• Domain field for per-domain storage

• Data field (JSON) containing:

  • cookies: All browser cookies

  • localStorage: Browser localStorage data

  • sessionStorage: Browser sessionStorage data

Session Persistence

• Sessions persist until manually cleared

• Sessions are domain-specific

• One session per project per domain

• Sessions are reused across test executions

Login Test Requirements

Status Requirements

The login test must be READY before it can be used:

• DRAFTING: Still being generated (not ready)

• REVIEW: Steps generated, needs review (not ready)

• READY: Ready for execution ✅

Step Requirements

The login test must have:

• At least 7 steps (as described above)

• Last step must be WAIT (for confirmation element)

• Second-to-last step must be GOTO (to authenticated page)

Validation Steps

The last 2 steps are used for session validation:

• Step 6: GOTO to authenticated page

• Step 7: WAIT for confirmation element

These steps verify that the loaded session is still valid.

Troubleshooting

"No login test found"

Problem: Login test doesn't exist for project.

Solution:

1. Go to Project Settings → Login

2. Configure login credentials

3. Click "Save"

4. Wait for login test to be generated

5. Review and finish review

"Login test is not ready"

Problem: Login test exists but status is not READY.

Solution:

1. Go to Project Settings → Login

2. Click "Review Login"

3. Verify login steps are correct

4. Click "Finish Review"

5. Ensure status is READY

Login Flow Fails

Problem: Login steps fail during execution.

Possible Causes:

• Login URL incorrect

• Username/password incorrect

• Selectors changed (page structure changed)

• Confirmation element not found

Solution:

1. Check error messages in test execution

2. Review login test steps

3. Update selectors if needed

4. Verify credentials are correct

Session Validation Always Fails

Problem: Session validation fails even with valid session.

Possible Causes:

• Session expired (cookies expired)

• Confirmation element changed

• Domain mismatch

Solution:

1. Clear session data

2. Re-run test to create new session

3. Update validation steps if needed

Best Practices

Login Test Setup

1. Use Stable Selectors: Ensure login test uses stable selectors (IDs, data-testid)

2. Test Manually First: Verify login flow works manually before automating

3. Review Steps Carefully: Check that all steps are correct before marking READY

4. Update When Needed: If login page changes, update login test

Session Management

1. Clear Sessions Periodically: Clear old sessions if authentication changes

2. Monitor Session Validity: Check if sessions are being reused (faster execution)

3. Domain Matching: Ensure session domain matches test target URL domain

4. Test Session Reuse: Verify that second run uses session validation

Test Configuration

1. Use Login Required: Check "Login Required" for tests needing authentication

2. Don't Mix Options: Don't use both "Login Required" and "Use Predefined Session"

3. Verify After Changes: Re-run tests after updating login settings

Related Topics

• Session Validation - How session reuse works

• Per-Domain Sessions - Managing sessions across domains

• Running Tests - Execute tests with login

• Debugging Failed Tests - Fix login issues

---

← Back to Documentation | Next: Session Validation →