Per-Domain Sessions

This guide explains how TrueAssert manages browser sessions per domain, allowing you to maintain separate authenticated sessions for different domains.

Overview

TrueAssert stores session data per domain, meaning:

• Each project can have multiple sessions (one per domain)

• Sessions are isolated by domain

• Tests automatically use the correct session based on target URL domain

How Per-Domain Sessions Work

Domain Extraction

When saving or loading sessions, TrueAssert extracts the domain from URLs:

• https://example.com/login → domain: example.com

• https://app.example.com/dashboard → domain: app.example.com

• https://subdomain.site.com/page → domain: subdomain.site.com

Session Storage

Session data is stored in the SessionData model:

• Project: OneToOne relationship (one session per project per domain)

• Domain: Domain string (e.g., example.com)

• Data: JSON containing cookies, localStorage, sessionStorage

• Unique Constraint: (project, domain) - one session per project per domain

Session Matching

When loading a session:

1. Extract domain from test's target URL

2. Look up SessionData for project + domain

3. If found: Use that session

4. If not found: No session available (proceed to login)

Use Cases

Multiple Subdomains

If your application uses multiple subdomains:

• app.example.com - Main application

• api.example.com - API endpoints

• admin.example.com - Admin panel

Each can have its own session:

• Session for app.example.com - User session

• Session for admin.example.com - Admin session

Different Environments

If you test multiple environments:

• staging.example.com - Staging environment

• production.example.com - Production environment

Each environment maintains its own session.

Cross-Domain Testing

If you test across different domains:

• example.com - Main site

• auth.example.com - Authentication service

• payments.example.com - Payment service

Each domain can have separate authentication.

Setting Up Per-Domain Sessions

Automatic Domain Detection

Sessions are automatically associated with domains:

1. When login flow executes, domain is extracted from login URL

2. Session is saved with that domain

3. Future tests on same domain reuse that session

Manual Domain Configuration

You typically don't need to manually configure domains:

• Domain is automatically extracted from URLs

• Session matching happens automatically

• No configuration needed

Session Data Structure

JSON Format

Session data is stored as JSON:

{
  "cookies": [
    {
      "name": "sessionid",
      "value": "abc123...",
      "domain": ".example.com",
      "path": "/",
      "secure": true,
      "httpOnly": true,
      "sameSite": "Lax",
      "expirationDate": 1234567890
    }
  ],
  "localStorage": {
    "theme": "dark",
    "user_id": "12345"
  },
  "sessionStorage": {
    "last_page": "/dashboard"
  }
}

Domain in Session Data

The domain field in SessionData:

• Matches the domain of cookies

• Used for session lookup

• Must match test target URL domain

Session Loading Process

During Test Execution

When a test runs with use_predefined_session=True:

1. Extract Domain:

   domain = urlparse(test.target_url).netloc
   # Example: "example.com" from "https://example.com/page"

2. Lookup Session:

   session_data = SessionData.objects.filter(
       project=test.project,
       domain=domain
   ).first()

3. Load Session:

   • If found: Execute LOAD_SESSION command

   • If not found: Test fails with "No session data found"

Domain Matching Rules

Exact Match Required:

• example.com ≠ www.example.com

• app.example.com ≠ example.com

• example.com ≠ example.org

Subdomain Handling:

• Cookies with .example.com domain work for all subdomains

• But SessionData lookup requires exact domain match

• app.example.com session won't match example.com test

Best Practices

Domain Consistency

1. Use Consistent URLs: Use same domain format in all tests

2. Match Login URL: Ensure login URL domain matches test URL domain

3. Check Domain: Verify session domain matches test domain

Session Management

1. Clear When Needed: Clear sessions if domain changes

2. Verify Domain: Check SessionData domain matches expectations

3. Test Domain Matching: Verify sessions load for correct domains

Multi-Domain Testing

1. Separate Sessions: Each domain maintains its own session

2. Independent Authentication: Sessions don't interfere with each other

3. Domain-Specific Tests: Create tests for each domain separately

Troubleshooting

"No session data found for domain"

Problem: Session exists but domain doesn't match.

Possible Causes:

• Test URL uses different domain than login URL

• Domain format mismatch (www vs non-www)

• Subdomain mismatch

Solutions:

1. Check SessionData domain in database

2. Verify test target URL domain

3. Ensure domains match exactly

4. Clear and recreate session with correct domain

Session Not Loading

Problem: Session exists but not being loaded.

Possible Causes:

• Domain mismatch

• Session data corrupted

• Project mismatch

Solutions:

1. Verify domain matches exactly

2. Check SessionData exists for project + domain

3. Clear and recreate session

4. Verify use_predefined_session=True is set

Wrong Session Loaded

Problem: Different domain's session is being used.

Possible Causes:

• Domain extraction incorrect

• Session lookup wrong

• Multiple sessions for same project

Solutions:

1. Verify domain extraction logic

2. Check SessionData domain field

3. Ensure only one session per project per domain

4. Clear incorrect sessions

Related Topics

• Setting Up Login - Configure login

• Session Validation - How validation works

• Running Tests - Execute tests with sessions

• Core Concepts - Session architecture

---

← Back to Documentation | Next: Understanding XPath Selectors →