Cookie & Header Authentication

Test-Lab can inject cookies and HTTP headers before running tests, allowing you to test authenticated areas without the AI agent needing to log in manually.

Use Cases

• Session cookies - Test logged-in user flows
• Auth tokens - Access protected API endpoints
• Feature flags - Test specific feature variations
• Bypass tokens - Skip CAPTCHA or rate limiting during tests

Cookie Hierarchy

Cookies can be configured at three levels, with later levels overriding earlier ones:

Project cookies → Test Plan cookies → Runtime cookies (API)

Cookie Configuration

Required Fields

Domain Patterns

The domain field determines which URLs receive the cookie:

Examples

Wildcard domain (recommended):

{
  "name": "auth_token",
  "value": "eyJhbGciOiJIUzI1NiIs...",
  "domain": ".myapp.com"
}

This cookie will be sent to myapp.com, www.myapp.com, api.myapp.com, etc.

Specific subdomain:

{
  "name": "admin_session",
  "value": "admin_xyz789",
  "domain": ".admin.myapp.com"
}

This cookie will only be sent to admin.myapp.com and its subdomains.

Configuring in the Dashboard

Project-Level Cookies

1. Go to Projects in the admin dashboard
2. Click Edit on your project
3. Expand Advanced Settings
4. Add cookies under the Cookies section
5. Click Save

All test plans in this project will inherit these cookies.

Test Plan-Level Cookies

1. Go to Test Plans in the admin dashboard
2. Click Edit on your test plan
3. Expand Advanced Settings
4. Add cookies (these override project cookies with the same name)
5. Click Save

Configuring via API

Pass cookies at runtime when triggering tests:

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanId": 123,
    "cookies": [
      {
        "name": "session",
        "value": "dynamic_token_from_ci",
        "domain": ".myapp.com"
      }
    ]
  }'

Runtime cookies override any cookies configured in the dashboard.

CI/CD Integration

Generate fresh auth tokens in your CI pipeline and pass them to Test-Lab:

GitHub Actions Example

- name: Get auth token
  id: auth
  run: |
    TOKEN=$(curl -X POST https://myapp.com/api/login \
      -d '{"email":"test@example.com","password":"${{ secrets.TEST_PASSWORD }}"}' \
      | jq -r '.token')
    echo "token=$TOKEN" >> $GITHUB_OUTPUT

- name: Run Test-Lab tests
  run: |
    curl -X POST https://test-lab.ai/api/v1/run \
      -H "Authorization: Bearer ${{ secrets.TESTLAB_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "testPlanId": 123,
        "buildId": "${{ github.sha }}",
        "cookies": [
          {
            "name": "auth_token",
            "value": "${{ steps.auth.outputs.token }}",
            "domain": ".myapp.com"
          }
        ]
      }'

Troubleshooting

Cookies not working?

1. Check the domain - Use .example.com (with leading dot) for subdomains
2. Verify the cookie name - Must match exactly what your app expects
3. Check for typos in value - Copy-paste to avoid errors
4. Test manually first - Verify the cookie works in your browser's DevTools

Test still shows login page?

• Your app may require additional cookies (e.g., CSRF tokens)
• The cookie may have expired server-side
• Check if your app validates other headers or conditions

Header Authentication

HTTP headers are useful for API authentication or when your app expects tokens in request headers rather than cookies.

Use Cases

• Bearer tokens - Authorization: Bearer <token>
• API keys - X-API-Key: <key>
• Custom auth headers - Any header your app expects

Header Configuration

Headers are simple name-value pairs:

Header Hierarchy

Like cookies, headers can be configured at three levels:

Project headers → Test Plan headers → Runtime headers (API)

More specific levels override less specific ones.

Configuring in the Dashboard

Project-Level Headers

1. Go to Projects in the admin dashboard
2. Click Edit on your project
3. Expand Advanced Settings
4. Add headers under the HTTP Headers section
5. Click Save

Test Plan-Level Headers

1. Go to Test Plans in the admin dashboard
2. Click Edit on your test plan
3. Expand Advanced Settings
4. Add headers (these override project headers with the same name)
5. Click Save

Configuring via API

Pass headers at runtime when triggering tests:

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanId": 123,
    "headers": [
      {
        "name": "Authorization",
        "value": "Bearer dynamic_token_from_ci"
      }
    ]
  }'

Using Credentials in Headers

Reference stored credentials to avoid hardcoding sensitive values:

{
  "name": "Authorization",
  "value": "Bearer {{credentials.api_token}}"
}

See Credentials for more on secure value injection.

Common Header Patterns

Bearer token:

{
  "name": "Authorization",
  "value": "Bearer {{credentials.auth_token}}"
}

API key:

{
  "name": "X-API-Key",
  "value": "{{credentials.api_key}}"
}

Basic auth:

{
  "name": "Authorization",
  "value": "Basic {{credentials.basic_auth}}"
}

Next Steps