Skip to content

🗄️ Browser local storage

Configure and upload browser local storage data to ensure your tests run with the necessary application state and user preferences.

Overview

Browser local storage is crucial for testing web applications that rely on client-side data persistence. Wopee.io allows you to upload and configure local storage data that will be available during test execution, ensuring tests run with realistic application states.

What is browser local storage?

Local storage is a web storage mechanism that allows web applications to store data locally within a user's browser. This data includes:

  • User preferences: Theme settings, language choices, display options
  • Authentication tokens: Session tokens, API keys, refresh tokens
  • Application state: Shopping cart contents, form data, user progress
  • Cache data: Frequently accessed information, user-specific configurations

Supported storage types

Wopee.io AI Agent automatically loads data from the data directory. It is based on Playwright's browser context and supports multiple browser storage mechanisms:

localStorage

Key-value pairs stored persistently in the browser.

sessionStorage

Temporary storage that lasts for the duration of the page session.

Cookies

Small pieces of data stored by the browser for specific domains.

IndexedDB

More complex database storage for larger amounts of structured data.

How to upload local storage data: JSON Context File

Upload a complete browser context file to your repository's data directory. The AI testing agent will automatically detect and apply this storage state.

Create a file named auth.json in your data directory (example):

{
  "cookies": [
    {
      "name": "session-username",
      "value": "standard_user",
      "domain": "www.saucedemo.com",
      "path": "/",
      "expires": 1752609084,
      "httpOnly": false,
      "secure": false,
      "sameSite": "Lax"
    }
  ],
  "origins": [
    {
      "origin": "https://www.saucedemo.com",
      "localStorage": [
        {
          "name": "backtrace-guid",
          "value": "b6ff9051-63fb-49f5-9ce9-7706db9c4960"
        },
        {
          "name": "backtrace-last-active",
          "value": "1752608467035"
        }
      ]
    }
  ]
}

File organization in your repository

Repository structure

Place your browser context files in the data directory of your repository:

your-repository/
├── data/
│   └── auth.json          # Authentication context
├── tests/
└── src/

Naming conventions

  • Use file name: auth.json
  • The agent automatically loads the the JSON file

Storage data formats

Origin-based localStorage format

The recommended format organizes storage by domain origin:

{
  "origins": [
    {
      "origin": "https://example.com",
      "localStorage": [
        {
          "name": "user_id",
          "value": "12345"
        },
        {
          "name": "settings",
          "value": "{\"theme\": \"dark\", \"notifications\": true}"
        }
      ]
    }
  ]
}

Cookies configuration

Cookies are specified in an array with detailed properties:

{
  "cookies": [
    {
      "name": "auth_session", // Cookie name
      "value": "encrypted_session_data", // Cookie value
      "domain": ".myapp.com", // Domain scope
      "path": "/", // Path scope
      "expires": 1752609084, // Unix timestamp
      "secure": true, // HTTPS only
      "httpOnly": false, // JavaScript accessible
      "sameSite": "Lax" // SameSite policy
    }
  ]
}

IndexedDB data

Complex structured data for IndexedDB:

{
  "databases": [
    {
      "name": "MyAppDB",
      "version": 1,
      "stores": [
        {
          "name": "users",
          "data": [
            {"id": 1, "name": "John Doe", "email": "john@example.com"},
            {"id": 2, "name": "Jane Smith", "email": "jane@example.com"}
          ]
        }
      ]
    }
  ]
}

Using storage data in tests

Automatic detection and application

When you commit a JSON context file to your repository's data directory:

  1. Automatic detection: The AI agent scans the data directory for JSON files during test initialization
  2. Context loading: When found, the agent logs "Browser storage state found and to be uploaded"
  3. Browser initialization: A new browser context is created with the pre-configured storage state
  4. State persistence: All cookies, localStorage, and sessionStorage remain available throughout the test session
  5. Cross-domain support: Storage data is applied per origin, supporting multi-domain applications

This seamless integration means tests automatically start with your configured authentication, user preferences, and application state.

Practical example: Setting up authentication

  1. Create the context file: Add auth.json to your data directory:
{
  "cookies": [
    {
      "name": "session-username",
      "value": "standard_user",
      "domain": "www.saucedemo.com",
      "path": "/",
      "expires": 1752609084,
      "httpOnly": false,
      "secure": false,
      "sameSite": "Lax"
    }
  ],
  "origins": [
    {
      "origin": "https://www.saucedemo.com",
      "localStorage": [
        {
          "name": "user-session",
          "value": "authenticated"
        },
        {
          "name": "user-role",
          "value": "standard"
        }
      ]
    }
  ]
}

  1. Run your tests: The AI agent will automatically detect this file and initialize the browser with this authentication state

  2. Tests start authenticated: Your tests begin as if the user is already logged in, skipping login steps

Common use cases

Authentication testing

Pre-configure authentication tokens and user sessions:

{
  "localStorage": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "def456ghi789jkl012mno345pqr678stu901",
    "user_profile": "{\"id\": 123, \"role\": \"admin\", \"permissions\": [\"read\", \"write\"]}"
  },
  "cookies": [
    {
      "name": "session_id",
      "value": "secure_session_hash",
      "domain": ".myapp.com",
      "secure": true,
      "httpOnly": true
    }
  ]
}

E-commerce testing

Set up shopping cart and user preferences:

{
  "localStorage": {
    "shopping_cart": "{\"items\": [{\"product_id\": 456, \"quantity\": 2, \"price\": 29.99}], \"total\": 59.98}",
    "user_preferences": "{\"currency\": \"USD\", \"shipping_address\": \"123 Main St\"}",
    "recently_viewed": "[456, 789, 123, 654]",
    "wishlist": "[789, 321, 555]"
  }
}

Application state testing

Configure complex application states:

{
  "localStorage": {
    "app_state": "{\"current_page\": \"dashboard\", \"sidebar_collapsed\": false}",
    "user_settings": "{\"theme\": \"dark\", \"language\": \"en\", \"timezone\": \"UTC\"}",
    "feature_flags": "{\"beta_ui\": true, \"advanced_features\": false}",
    "cache_timestamp": "2024-01-15T10:30:00Z"
  },
  "sessionStorage": {
    "form_data": "{\"step\": 3, \"completed_steps\": [1, 2]}",
    "temp_calculations": "{\"total\": 1250.50, \"tax\": 125.05}"
  }
}

Best practices

Local storage best practices

  • Data consistency: Ensure storage data matches your application's expected format
  • Token validity: Use valid, non-expired authentication tokens
  • Minimal data: Include only necessary data to avoid bloating
  • Security: Avoid real user credentials in test storage data
  • Versioning: Maintain different storage configurations for different test scenarios

Environment-specific configurations

Development environment

{
  "localStorage": {
    "api_endpoint": "https://dev-api.myapp.com",
    "debug_mode": "true",
    "log_level": "debug"
  }
}

Staging environment

{
  "localStorage": {
    "api_endpoint": "https://staging-api.myapp.com",
    "debug_mode": "false",
    "log_level": "info"
  }
}

Production-like testing

{
  "localStorage": {
    "api_endpoint": "https://api.myapp.com",
    "debug_mode": "false",
    "log_level": "error"
  }
}

Troubleshooting

Storage not applied

  • Verify JSON format is valid
  • Check that domain settings match your application
  • Ensure storage keys match application expectations

Authentication issues

  • Validate token format and expiration
  • Check cookie domain and path settings
  • Verify authentication flow compatibility

Data format errors

  • Ensure nested JSON is properly escaped
  • Validate data types match application requirements
  • Check for special characters in values

Performance issues

  • Reduce storage data size if tests are slow
  • Avoid large IndexedDB datasets
  • Clean up unnecessary storage entries

Security considerations

  • Never use real user credentials in test storage data
  • Avoid storing sensitive information in plain text
  • Use test-specific tokens and session data
  • Regularly rotate test authentication data

Need help?

For browser storage configuration issues, contact our support team at help@wopee.io or visit our community discussions.