@assertrx/dino 1.0.0

package/skills/playwright-cli/storage-and-auth.md

@@ -0,0 +1,487 @@
+# Storage and Authentication
+
+> **When to use**: Managing cookies, localStorage, sessionStorage, browser storage state, saving and restoring authentication, or testing storage-dependent features.
+> **Prerequisites**: [core-commands.md](core-commands.md) for basic CLI usage
+
+## Quick Reference
+
+```bash
+# Save all browser state (cookies + localStorage) to file
+playwright-cli state-save auth.json
+
+# Restore state in a new session
+playwright-cli state-load auth.json
+
+# Quick cookie operations
+playwright-cli cookie-list
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# localStorage
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-get theme
+playwright-cli localstorage-clear
+
+# sessionStorage
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-clear
+```
+
+## Storage State (Save & Restore)
+
+The most powerful feature — save the entire browser state (cookies + localStorage for all origins) to a JSON file, then restore it later to skip login flows.
+
+### Save Storage State
+
+```bash
+# Save to auto-generated filename (storage-state-{timestamp}.json)
+playwright-cli state-save
+
+# Save to specific file
+playwright-cli state-save auth.json
+playwright-cli state-save ./states/admin-session.json
+```
+
+### Restore Storage State
+
+```bash
+# Load state from file
+playwright-cli state-load auth.json
+
+# Navigate after loading — cookies and localStorage are already set
+playwright-cli goto https://app.example.com/dashboard
+# Already authenticated!
+```
+
+### Storage State File Format
+
+The saved JSON contains both cookies and localStorage:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "expires": 1735689600,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" },
+        { "name": "user_id", "value": "12345" },
+        { "name": "auth_token", "value": "jwt.token.here" }
+      ]
+    }
+  ]
+}
+```
+
+## Authentication Pattern
+
+The most common workflow — log in once, save state, reuse across sessions.
+
+### Step 1: Log In and Save
+
+```bash
+playwright-cli open https://app.example.com/login
+playwright-cli snapshot
+
+playwright-cli fill e1 "admin@example.com"
+playwright-cli fill e2 "secure-password"
+playwright-cli click e3
+
+# Wait for redirect to confirm login succeeded
+playwright-cli run-code "async page => {
+  await page.waitForURL('**/dashboard');
+  return 'Login successful: ' + page.url();
+}"
+
+# Save the authenticated state
+playwright-cli state-save auth.json
+playwright-cli close
+```
+
+### Step 2: Reuse Auth State
+
+```bash
+# New session — skip login entirely
+playwright-cli open https://app.example.com
+playwright-cli state-load auth.json
+playwright-cli goto https://app.example.com/dashboard
+# Already logged in as admin!
+
+playwright-cli snapshot    # See the dashboard
+```
+
+### Multi-Role Authentication
+
+```bash
+# Save state for each role
+playwright-cli open https://app.example.com/login
+playwright-cli fill e1 "admin@example.com"
+playwright-cli fill e2 "admin-pass"
+playwright-cli click e3
+playwright-cli state-save admin-auth.json
+playwright-cli close
+
+playwright-cli open https://app.example.com/login
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "user-pass"
+playwright-cli click e3
+playwright-cli state-save user-auth.json
+playwright-cli close
+
+# Now use them
+playwright-cli -s=admin open https://app.example.com
+playwright-cli -s=admin state-load admin-auth.json
+playwright-cli -s=admin goto https://app.example.com/admin
+
+playwright-cli -s=user open https://app.example.com
+playwright-cli -s=user state-load user-auth.json
+playwright-cli -s=user goto https://app.example.com/profile
+```
+
+### OAuth / SSO Authentication
+
+For OAuth flows that involve redirects and popups:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.goto('https://app.example.com/login');
+
+  // Click 'Login with Google'
+  const [popup] = await Promise.all([
+    page.waitForEvent('popup'),
+    page.click('button:text(\"Login with Google\")')
+  ]);
+
+  // Fill credentials in the popup
+  await popup.fill('input[type=email]', 'user@gmail.com');
+  await popup.click('#identifierNext');
+  await popup.fill('input[type=password]', 'password');
+  await popup.click('#passwordNext');
+
+  // Wait for popup to close and main page to redirect
+  await popup.waitForEvent('close');
+  await page.waitForURL('**/dashboard');
+
+  // Save authenticated state
+  await page.context().storageState({ path: 'oauth-auth.json' });
+  return 'OAuth login complete';
+}"
+```
+
+## Cookies
+
+### List All Cookies
+
+```bash
+playwright-cli cookie-list
+```
+
+### Filter by Domain
+
+```bash
+playwright-cli cookie-list --domain=example.com
+```
+
+### Filter by Path
+
+```bash
+playwright-cli cookie-list --path=/api
+```
+
+### Get a Specific Cookie
+
+```bash
+playwright-cli cookie-get session_id
+playwright-cli cookie-get __cf_bm
+```
+
+### Set a Cookie
+
+```bash
+# Basic cookie
+playwright-cli cookie-set session abc123
+
+# Cookie with full options
+playwright-cli cookie-set session abc123 \
+  --domain=example.com \
+  --path=/ \
+  --httpOnly \
+  --secure \
+  --sameSite=Lax
+
+# Cookie with expiration (Unix timestamp)
+playwright-cli cookie-set remember_me token123 --expires=1735689600
+```
+
+### Delete a Cookie
+
+```bash
+playwright-cli cookie-delete session_id
+playwright-cli cookie-delete __cf_bm
+```
+
+### Clear All Cookies
+
+```bash
+playwright-cli cookie-clear
+```
+
+### Advanced: Multiple Cookies at Once
+
+```bash
+playwright-cli run-code "async page => {
+  await page.context().addCookies([
+    {
+      name: 'session_id',
+      value: 'sess_abc123',
+      domain: 'example.com',
+      path: '/',
+      httpOnly: true,
+      secure: true,
+      sameSite: 'Strict'
+    },
+    {
+      name: 'preferences',
+      value: JSON.stringify({ theme: 'dark', lang: 'en' }),
+      domain: 'example.com',
+      path: '/'
+    },
+    {
+      name: 'tracking_opt_out',
+      value: 'true',
+      domain: '.example.com',
+      path: '/'
+    }
+  ]);
+}"
+```
+
+### Advanced: Read All Cookies Programmatically
+
+```bash
+playwright-cli run-code "async page => {
+  const cookies = await page.context().cookies();
+  return cookies.map(c => ({
+    name: c.name,
+    value: c.value.substring(0, 20) + '...',
+    domain: c.domain,
+    httpOnly: c.httpOnly,
+    secure: c.secure,
+    expires: new Date(c.expires * 1000).toISOString()
+  }));
+}"
+```
+
+## Local Storage
+
+### List All Items
+
+```bash
+playwright-cli localstorage-list
+```
+
+### Get a Value
+
+```bash
+playwright-cli localstorage-get theme
+playwright-cli localstorage-get auth_token
+```
+
+### Set a Value
+
+```bash
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-set language en-US
+
+# Set JSON values (quote the JSON)
+playwright-cli localstorage-set user_settings '{"theme":"dark","fontSize":14,"sidebar":true}'
+```
+
+### Delete an Item
+
+```bash
+playwright-cli localstorage-delete auth_token
+```
+
+### Clear All
+
+```bash
+playwright-cli localstorage-clear
+```
+
+### Advanced: Bulk Operations
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    localStorage.setItem('token', 'jwt_abc123');
+    localStorage.setItem('user_id', '12345');
+    localStorage.setItem('user_name', 'Jane Doe');
+    localStorage.setItem('preferences', JSON.stringify({
+      theme: 'dark',
+      notifications: true,
+      language: 'en'
+    }));
+    localStorage.setItem('onboarding_complete', 'true');
+  });
+}"
+```
+
+### Advanced: Read All localStorage
+
+```bash
+playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    const items = {};
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      items[key] = localStorage.getItem(key);
+    }
+    return items;
+  });
+}"
+```
+
+## Session Storage
+
+Session storage is per-tab and cleared when the tab closes.
+
+### List All Items
+
+```bash
+playwright-cli sessionstorage-list
+```
+
+### Get / Set / Delete
+
+```bash
+playwright-cli sessionstorage-get form_step
+playwright-cli sessionstorage-set form_step 3
+playwright-cli sessionstorage-set form_data '{"name":"Jane","email":"jane@example.com"}'
+playwright-cli sessionstorage-delete form_step
+playwright-cli sessionstorage-clear
+```
+
+## IndexedDB
+
+IndexedDB requires `run-code` for access:
+
+### List Databases
+
+```bash
+playwright-cli run-code "async page => {
+  return await page.evaluate(async () => {
+    const databases = await indexedDB.databases();
+    return databases.map(db => ({ name: db.name, version: db.version }));
+  });
+}"
+```
+
+### Delete a Database
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(dbName => {
+    indexedDB.deleteDatabase(dbName);
+  }, 'myDatabase');
+  return 'Database deleted';
+}"
+```
+
+### Read Data from an Object Store
+
+```bash
+playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open('myDatabase');
+      request.onsuccess = () => {
+        const db = request.result;
+        const tx = db.transaction('myStore', 'readonly');
+        const store = tx.objectStore('myStore');
+        const getAll = store.getAll();
+        getAll.onsuccess = () => resolve(getAll.result);
+        getAll.onerror = () => reject(getAll.error);
+      };
+      request.onerror = () => reject(request.error);
+    });
+  });
+}"
+```
+
+## Common Patterns
+
+### Token Refresh Testing
+
+```bash
+# Set an expired token to test refresh logic
+playwright-cli localstorage-set auth_token "expired-jwt-token"
+playwright-cli localstorage-set token_expiry "1609459200"
+
+# Navigate to trigger token refresh
+playwright-cli goto https://app.example.com/dashboard
+
+# Check if token was refreshed
+playwright-cli localstorage-get auth_token
+```
+
+### Feature Flag Testing
+
+```bash
+# Enable a feature flag via localStorage
+playwright-cli localstorage-set feature_flags '{"newCheckout":true,"darkMode":true,"betaFeatures":false}'
+
+# Reload to apply
+playwright-cli reload
+playwright-cli snapshot
+```
+
+### Clear Everything and Start Fresh
+
+```bash
+playwright-cli cookie-clear
+playwright-cli localstorage-clear
+playwright-cli sessionstorage-clear
+playwright-cli reload
+```
+
+### Save and Restore Roundtrip
+
+```bash
+# Set up state manually
+playwright-cli open https://example.com
+playwright-cli cookie-set session abc123 --domain=example.com
+playwright-cli localstorage-set user john
+playwright-cli localstorage-set theme dark
+
+# Save everything
+playwright-cli state-save my-session.json
+
+# Later — restore state in a new session
+playwright-cli open https://example.com
+playwright-cli state-load my-session.json
+playwright-cli reload
+# Cookies and localStorage are restored
+```
+
+## Security Notes
+
+- **Never commit auth state files** — add `*.auth-state.json` and `auth.json` to `.gitignore`
+- **Delete state files after use** — `rm auth.json` when done with automation
+- **Use environment variables for credentials** — never hardcode passwords in scripts
+- **In-memory sessions are safer** — default sessions don't persist to disk, reducing exposure
+- **Rotate saved states** — auth tokens expire; regenerate state files regularly
+- **Avoid saving state on shared machines** — storage state files contain session tokens and personal data