[AUTHENTICATION]

Overview

Many apps require authentication to reach the pages you want to test. GetWired supports three methods, from safest to simplest:

1. Cookie / localStorage injection — inject session tokens directly, no credentials needed
2. Environment variable references — reference secrets from your shell or CI, never stored in config
3. Login flow automation — fill a login form automatically before tests run

Security Principles

Method 1: Cookie Injection (Recommended)

The safest approach. Log into your app manually, copy the session cookie, and tell GetWired to inject it. Your actual username and password never touch GetWired.

Step 1: Find your session cookie

Open your app in a browser, log in, then open DevTools → Application → Cookies. Copy the session cookie name and value (e.g. session_id).

Step 2: Add to config

// .getwired/config.json
{
  "authentication": {
    "cookies": [
      {
        "name": "session_id",
        "value": "$SESSION_TOKEN",
        "path": "/"
      }
    ]
  }
}

The $SESSION_TOKEN reference means GetWired reads the value from your environment at runtime — it is never saved to disk.

Step 3: Set the env var and run

export SESSION_TOKEN="abc123..."
getwired test

Method 2: localStorage Injection

Some apps (especially SPAs) store auth tokens in localStorage instead of cookies. Same idea — inject the token, skip the login.

// .getwired/config.json
{
  "authentication": {
    "localStorage": {
      "auth_token": "$AUTH_TOKEN",
      "refresh_token": "$REFRESH_TOKEN"
    }
  }
}

export AUTH_TOKEN="eyJhbGci..."
export REFRESH_TOKEN="dGhpcyBp..."
getwired test

Method 3: Login Flow Automation

If you need GetWired to actually fill in a login form, provide a loginUrl and credentials. Always use env var references for the values.

// .getwired/config.json
{
  "authentication": {
    "loginUrl": "http://localhost:3000/login",
    "credentials": {
      "username": "$TEST_USER",
      "password": "$TEST_PASSWORD"
    }
  }
}

export TEST_USER="testuser@example.com"
export TEST_PASSWORD="s3cure-t3st-passw0rd"
getwired test

GetWired will navigate to the login URL, find common form fields (email/username, password), fill them, submit, wait for the page to load, then proceed with testing.

CI/CD Example

In CI, set secrets through your platform's secrets manager. Here's a GitHub Actions example:

# .github/workflows/test.yml
- name: Run GetWired
  env:
    SESSION_TOKEN: ${{ secrets.TEST_SESSION_TOKEN }}
  run: getwired test

The secret is injected at runtime by GitHub Actions, never stored in your repo.

Combining Methods

You can combine cookies, localStorage, and login flow in the same config. GetWired applies them in order:

1. Opens the login URL (or your app URL)
2. Injects cookies
3. Injects localStorage
4. Fills and submits the login form (if credentials are set)
5. Navigates to your app and starts testing

Full Config Reference

{
  "authentication": {
    "cookies": [
      {
        "name": "session_id",   // cookie name (required)
        "value": "$ENV_VAR",    // value or $ENV reference (required)
        "domain": ".example.com", // optional
        "path": "/",              // optional, defaults to /
        "secure": true,           // optional
        "httpOnly": false         // optional
      }
    ],
    "localStorage": {
      "key": "$ENV_VAR"         // key-value pairs
    },
    "loginUrl": "http://...",   // URL of login page
    "credentials": {
      "username": "$TEST_USER",
      "password": "$TEST_PASS"
    }
  }
}