cursorflow 2.7.6__tar.gz → 2.7.7__tar.gz

{cursorflow-2.7.6 → cursorflow-2.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.7.6
+Version: 2.7.7
 Summary: 🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis
 Author-email: GeekWarrior Development <rbush@cooltheory.com>
 License-Expression: MIT
@@ -144,6 +144,44 @@ cursorflow cleanup --all --dry-run
 
 ---
 
+## 🔐 Authentication & Testing Protected Pages
+
+Test authenticated pages with automatic session management:
+
+```bash
+# 1. Configure auth in .cursorflow/config.json
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "username_selector": "#email",
+    "password_selector": "#password",
+    "submit_selector": "#login-button"
+  }
+}
+
+# 2. Login once and save session
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "user"
+
+# 3. Reuse session for protected pages (no re-login!)
+cursorflow test --use-session "user" \
+  --path /dashboard \
+  --screenshot "dashboard"
+```
+
+**Supports:**
+- Form authentication (username/password)
+- Cookie authentication (JWT tokens, session cookies)
+- Header authentication (Bearer tokens, API keys)
+
+**See:** [Complete Authentication Guide](docs/user/USAGE_GUIDE.md#authentication--session-management)
+
+---
+
 ## 🚀 Complete Page Intelligence
 
 Every test captures everything needed for debugging:
@@ -157,7 +195,7 @@ Every test captures everything needed for debugging:
 - **Forms**: All field values at capture time (passwords masked)
 - **Performance**: Load times, memory usage, reliability indicators
 - **Visual**: Screenshots with comprehensive page analysis
-- **Sessions**: Save/restore authenticated browser state (requires auth_config)
+- **Sessions**: Save/restore authenticated browser state (requires auth_config - see Authentication below)
 
 ### **🔄 Hot Reload Intelligence**
 - **Framework auto-detection** (Vite, Webpack, Next.js, Parcel, Laravel Mix)

{cursorflow-2.7.6 → cursorflow-2.7.7}/README.md

@@ -99,6 +99,44 @@ cursorflow cleanup --all --dry-run
 
 ---
 
+## 🔐 Authentication & Testing Protected Pages
+
+Test authenticated pages with automatic session management:
+
+```bash
+# 1. Configure auth in .cursorflow/config.json
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "username_selector": "#email",
+    "password_selector": "#password",
+    "submit_selector": "#login-button"
+  }
+}
+
+# 2. Login once and save session
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "user"
+
+# 3. Reuse session for protected pages (no re-login!)
+cursorflow test --use-session "user" \
+  --path /dashboard \
+  --screenshot "dashboard"
+```
+
+**Supports:**
+- Form authentication (username/password)
+- Cookie authentication (JWT tokens, session cookies)
+- Header authentication (Bearer tokens, API keys)
+
+**See:** [Complete Authentication Guide](docs/user/USAGE_GUIDE.md#authentication--session-management)
+
+---
+
 ## 🚀 Complete Page Intelligence
 
 Every test captures everything needed for debugging:
@@ -112,7 +150,7 @@ Every test captures everything needed for debugging:
 - **Forms**: All field values at capture time (passwords masked)
 - **Performance**: Load times, memory usage, reliability indicators
 - **Visual**: Screenshots with comprehensive page analysis
-- **Sessions**: Save/restore authenticated browser state (requires auth_config)
+- **Sessions**: Save/restore authenticated browser state (requires auth_config - see Authentication below)
 
 ### **🔄 Hot Reload Intelligence**
 - **Framework auto-detection** (Vite, Webpack, Next.js, Parcel, Laravel Mix)

{cursorflow-2.7.6 → cursorflow-2.7.7}/cursorflow/rules/cursorflow-usage.mdc

@@ -963,21 +963,141 @@ cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dash
 cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dashboard"}, {"screenshot": "after"}]'
 ```
 
-## Authentication Testing
+## Authentication & Session Management
 
+### **Critical: Most Real Apps Need Auth**
+
+Testing sophisticated applications requires authentication to access:
+- User dashboards and protected pages
+- Admin panels and settings
+- Role-based features
+- Shopping carts and user data
+- Personalized content
+
+### **Three Authentication Methods**
+
+#### **Method 1: Form Authentication (Automatic)**
+
+Configure in `.cursorflow/config.json`:
+```json
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "username_selector": "#email",
+    "password_selector": "#password",
+    "submit_selector": "#login-button",
+    "success_indicators": ["dashboard", "profile"],
+    "auth_check_selectors": [".user-menu"]
+  }
+}
+```
+
+Then use session management:
 ```bash
-cursorflow test \
-  --base-url http://localhost:3000 \
-  --actions '[
-    {"navigate": "/login"},
-    {"fill": {"selector": "#username", "value": "test@example.com"}},
-    {"fill": {"selector": "#password", "value": "testpass"}},
-    {"click": "#login-button"},
-    {"wait_for": ".dashboard"},
-    {"navigate": "/protected-page"},
-    {"wait_for": "#protected-content"},
-    {"screenshot": "authenticated"}
-  ]'
+# Login once, save session
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "user"
+
+# Reuse session (no re-login!)
+cursorflow test --use-session "user" \
+  --path /dashboard \
+  --screenshot "dashboard"
+```
+
+#### **Method 2: Cookie Authentication**
+
+For JWT tokens, session cookies, or cookies from DevTools:
+```json
+{
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      {
+        "name": "session_token",
+        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+        "domain": "example.com",
+        "path": "/",
+        "httpOnly": true,
+        "secure": true
+      }
+    ]
+  }
+}
+```
+
+#### **Method 3: Header Authentication**
+
+For API tokens and Bearer authentication:
+```json
+{
+  "auth": {
+    "method": "headers",
+    "headers": {
+      "Authorization": "Bearer your-api-token",
+      "X-API-Key": "your-api-key"
+    }
+  }
+}
+```
+
+### **Session Management Benefits**
+
+**Without sessions**: Re-login on every test (slow, server load)
+**With sessions**: Login once, reuse state (fast, efficient)
+
+```bash
+# Save sessions for different roles
+cursorflow test --path /login --save-session "admin"
+cursorflow test --path /login --save-session "user"
+
+# Reuse as needed
+cursorflow test --use-session "admin" --path /admin/settings
+cursorflow test --use-session "user" --path /dashboard
+```
+
+### **Manual Authentication (Complex Flows)**
+
+For 2FA, OAuth, or complex flows, use explicit actions:
+```bash
+cursorflow test --actions '[
+  {"navigate": "/login"},
+  {"fill": {"selector": "#email", "value": "test@example.com"}},
+  {"fill": {"selector": "#password", "value": "testpass"}},
+  {"click": "#login-button"},
+  {"wait_for": "#otp-input"},
+  {"fill": {"selector": "#otp-input", "value": "123456"}},
+  {"click": "#verify-button"},
+  {"wait_for": ".dashboard"},
+  {"screenshot": "authenticated"}
+]' --save-session "2fa-user"
+```
+
+### **Troubleshooting Auth**
+
+**Auth failing?**
+```bash
+# Inspect login form to get correct selectors
+cursorflow inspect --base-url http://localhost:3000 \
+  --path /login \
+  --selector "input[type='email']"
+
+# Test with verbose logging
+cursorflow test --path /login \
+  --save-session "test" \
+  --verbose
+```
+
+**Session not working?**
+```bash
+# Check saved session
+cat .cursorflow/sessions/user_session.json
+
+# Force fresh login
+cursorflow test --use-session "user" --fresh-session
 ```
 
 ## Best Practices

{cursorflow-2.7.6 → cursorflow-2.7.7}/docs/user/USAGE_GUIDE.md

@@ -529,51 +529,731 @@ cursorflow test --base-url http://localhost:3000 \
 --quiet                             # JSON output only
 ```
 
-### **Authenticated Session Management**
+### **Authentication & Session Management**
 
-**Requires auth_config** - Session persistence is designed for testing authenticated pages.
+CursorFlow provides universal authentication support for testing protected pages and features. Session persistence allows you to login once and reuse authentication state across multiple tests.
 
-**Configure authentication in `.cursorflow/config.json`:**
+#### **Why Authentication Matters**
+
+Most real applications have:
+- User dashboards and protected pages
+- Role-based access control
+- Personalized content
+- Shopping carts and user data
+- Admin panels and settings
+
+Without authentication support, you can only test public pages. CursorFlow's authentication enables comprehensive testing of the entire application.
+
+---
+
+#### **Authentication Methods**
+
+CursorFlow supports three universal authentication strategies that work with any web framework.
+
+##### **Method 1: Form Authentication (Most Common)**
+
+For traditional username/password login forms.
+
+**Configuration (`.cursorflow/config.json`):**
 ```json
 {
   "base_url": "http://localhost:3000",
   "auth": {
     "method": "form",
     "username": "test@example.com",
-    "password": "testpass",
+    "password": "testpass123",
     "username_selector": "#email",
     "password_selector": "#password",
-    "submit_selector": "#login-button",
-    "session_storage": ".cursorflow/sessions/"
+    "submit_selector": "button[type='submit']",
+    "session_storage": ".cursorflow/sessions/",
+    "success_indicators": ["dashboard", "profile", "logout"],
+    "auth_check_selectors": [".user-menu", "#user-profile"]
   }
 }
 ```
 
-**Then use session save/restore:**
+**Field Reference:**
+- `method`: `"form"` - Indicates form-based authentication
+- `username`: Your test user's username/email
+- `password`: Your test user's password
+- `username_selector`: CSS selector for username input field
+- `password_selector`: CSS selector for password input field
+- `submit_selector`: CSS selector for login button
+- `session_storage`: Directory to store session files (default: `.cursorflow/sessions/`)
+- `success_indicators`: Keywords that indicate successful auth (optional)
+- `auth_check_selectors`: Elements that only appear when authenticated (optional)
+
+**CLI Usage:**
 ```bash
 # Login once and save session
 cursorflow test --base-url http://localhost:3000 \
   --path /login \
   --save-session "authenticated"
-# AuthHandler logs in, saves cookies + localStorage + sessionStorage
 
-# Reuse saved session (skip login)
+# Reuse saved session (no re-login needed)
 cursorflow test --base-url http://localhost:3000 \
   --path /dashboard \
   --use-session "authenticated"
-# AuthHandler restores saved state, already logged in
+```
+
+##### **Method 2: Cookie Authentication**
 
-# Manage sessions
+For applications that use cookie-based auth (JWT in cookies, session cookies, etc.).
+
+**Configuration:**
+```json
+{
+  "base_url": "https://staging.example.com",
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      {
+        "name": "session_token",
+        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+        "domain": "staging.example.com",
+        "path": "/",
+        "httpOnly": true,
+        "secure": true
+      },
+      {
+        "name": "user_id",
+        "value": "12345",
+        "domain": "staging.example.com",
+        "path": "/"
+      }
+    ],
+    "session_storage": ".cursorflow/sessions/"
+  }
+}
+```
+
+**Cookie Format:**
+- `name`: Cookie name
+- `value`: Cookie value
+- `domain`: Cookie domain (must match your base_url)
+- `path`: Cookie path (default: "/")
+- `httpOnly`: True for HTTP-only cookies
+- `secure`: True for HTTPS-only cookies
+- `sameSite`: "Strict", "Lax", or "None" (optional)
+
+**Use Case:** 
+- Testing with long-lived JWT tokens
+- Using cookies from browser DevTools
+- Bypassing complex OAuth flows
+
+##### **Method 3: Header Authentication**
+
+For API token or Bearer token authentication.
+
+**Configuration:**
+```json
+{
+  "base_url": "https://api.example.com",
+  "auth": {
+    "method": "headers",
+    "headers": {
+      "Authorization": "Bearer sk_test_51HqZ2RKr4...",
+      "X-API-Key": "your-api-key-here",
+      "X-User-ID": "12345"
+    },
+    "session_storage": ".cursorflow/sessions/"
+  }
+}
+```
+
+**Use Case:**
+- API testing with Bearer tokens
+- Custom authentication headers
+- Service-to-service authentication
+
+---
+
+#### **Session Management**
+
+Session persistence allows you to authenticate once and reuse the session across multiple tests, saving time and reducing server load.
+
+##### **Saving Sessions**
+
+```bash
+# Save session with custom name
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "admin-user"
+
+# Session saved to: .cursorflow/sessions/admin-user_session.json
+```
+
+**What gets saved:**
+- All cookies (session cookies, JWT tokens, etc.)
+- localStorage state
+- sessionStorage state
+- Timestamp and authentication method
+
+##### **Reusing Sessions**
+
+```bash
+# Use saved session
+cursorflow test --base-url http://localhost:3000 \
+  --path /protected-page \
+  --use-session "admin-user"
+
+# If session is invalid, CursorFlow automatically:
+# 1. Detects the session is expired
+# 2. Deletes invalid session file
+# 3. Performs fresh authentication
+```
+
+##### **Managing Sessions**
+
+```bash
+# List all saved sessions
 cursorflow sessions list
-cursorflow sessions delete "name"
+
+# Delete a specific session
+cursorflow sessions delete "admin-user"
+
+# Clear all sessions
+cursorflow sessions clear
 ```
 
-**Authentication Methods:**
-- `form` - Username/password form submission
-- `cookies` - Pre-configured cookies
-- `headers` - HTTP header authentication (Bearer tokens, etc.)
+---
+
+#### **Session Validation**
+
+CursorFlow validates authentication using multiple strategies:
+
+**1. Error Indicators** (checks for):
+- `.error`, `.alert-danger`, `.login-error`
+- Text containing: "error", "invalid", "failed", "incorrect"
+
+**2. Success Indicators** (from config):
+- Keywords in page content: "dashboard", "profile", "logout"
+- Configured in `success_indicators` array
+
+**3. URL Changes**:
+- URL no longer contains: `/login`, `/signin`, `/auth`
+
+**4. Auth-Specific Elements** (from config):
+- Elements that only appear when authenticated
+- Configured in `auth_check_selectors` array
+
+**Example validation configuration:**
+```json
+{
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "success_indicators": ["Welcome back", "My Account", "Sign Out"],
+    "auth_check_selectors": [".user-avatar", "#user-menu", ".logout-button"]
+  }
+}
+```
+
+---
+
+#### **Complete Authentication Workflows**
+
+##### **Workflow 1: Testing User Dashboard**
+
+```bash
+# 1. Configure auth in .cursorflow/config.json (one-time setup)
+cat > .cursorflow/config.json << 'EOF'
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "username_selector": "#email",
+    "password_selector": "#password",
+    "submit_selector": "button[type='submit']"
+  }
+}
+EOF
+
+# 2. Login and save session
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "user"
+
+# 3. Test protected pages (using saved session)
+cursorflow test --base-url http://localhost:3000 \
+  --path /dashboard \
+  --use-session "user" \
+  --screenshot "dashboard"
+
+cursorflow test --base-url http://localhost:3000 \
+  --path /settings \
+  --use-session "user" \
+  --screenshot "settings"
+```
+
+##### **Workflow 2: Testing Different User Roles**
+
+```json
+{
+  "environments": {
+    "admin": {
+      "base_url": "http://localhost:3000",
+      "auth": {
+        "method": "form",
+        "username": "admin@example.com",
+        "password": "adminpass",
+        "username_selector": "#email",
+        "password_selector": "#password",
+        "submit_selector": "#login-button"
+      }
+    },
+    "user": {
+      "base_url": "http://localhost:3000",
+      "auth": {
+        "method": "form",
+        "username": "user@example.com",
+        "password": "userpass",
+        "username_selector": "#email",
+        "password_selector": "#password",
+        "submit_selector": "#login-button"
+      }
+    }
+  }
+}
+```
+
+```bash
+# Test admin panel
+cursorflow test --base-url http://localhost:3000 \
+  --path /admin \
+  --save-session "admin" \
+  --config config.json --env admin
+
+# Test user dashboard  
+cursorflow test --base-url http://localhost:3000 \
+  --path /dashboard \
+  --save-session "user" \
+  --config config.json --env user
+```
+
+##### **Workflow 3: Cookie-Based API Testing**
+
+```json
+{
+  "base_url": "https://api.example.com",
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      {
+        "name": "jwt_token",
+        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0...",
+        "domain": "api.example.com",
+        "path": "/",
+        "httpOnly": true,
+        "secure": true,
+        "sameSite": "Strict"
+      }
+    ]
+  }
+}
+```
+
+```bash
+# Test authenticated API endpoint
+cursorflow test --base-url https://api.example.com \
+  --path /v1/user/profile \
+  --screenshot "api-response"
+```
+
+##### **Workflow 4: Header-Based Authentication**
+
+```json
+{
+  "base_url": "https://api.example.com",
+  "auth": {
+    "method": "headers",
+    "headers": {
+      "Authorization": "Bearer your-api-token-here",
+      "X-API-Key": "your-api-key",
+      "X-Client-ID": "cursorflow-test"
+    }
+  }
+}
+```
+
+```bash
+# Test API with bearer token
+cursorflow test --base-url https://api.example.com \
+  --path /v1/protected-resource \
+  --screenshot "protected-data"
+```
 
-**Without auth_config:** Session flags will be ignored (testing public pages doesn't need session persistence).
+---
+
+#### **Python API Authentication**
+
+**Form Authentication:**
+```python
+from cursorflow import CursorFlow
+
+flow = CursorFlow(
+    base_url="http://localhost:3000",
+    auth_config={
+        "method": "form",
+        "username": "test@example.com",
+        "password": "testpass",
+        "username_selector": "#email",
+        "password_selector": "#password",
+        "submit_selector": "#login-button",
+        "success_indicators": ["Dashboard", "Welcome"],
+        "auth_check_selectors": [".user-menu"]
+    }
+)
+
+# CursorFlow handles login automatically
+results = await flow.execute_and_collect([
+    {"navigate": "/dashboard"},
+    {"screenshot": "authenticated-dashboard"}
+])
+```
+
+**Session Reuse:**
+```python
+# Save session
+flow = CursorFlow(
+    base_url="http://localhost:3000",
+    auth_config={...}
+)
+
+results = await flow.execute_and_collect(
+    actions=[{"navigate": "/login"}],
+    session_options={"save_session": True, "session_name": "test-user"}
+)
+
+# Reuse session (much faster!)
+results = await flow.execute_and_collect(
+    actions=[{"navigate": "/dashboard"}],
+    session_options={"reuse_session": True, "session_name": "test-user"}
+)
+```
+
+**Cookie Authentication:**
+```python
+flow = CursorFlow(
+    base_url="https://staging.example.com",
+    auth_config={
+        "method": "cookies",
+        "cookies": [
+            {
+                "name": "session_id",
+                "value": "abc123xyz",
+                "domain": "staging.example.com",
+                "path": "/",
+                "httpOnly": True,
+                "secure": True
+            }
+        ]
+    }
+)
+```
+
+**Header Authentication:**
+```python
+flow = CursorFlow(
+    base_url="https://api.example.com",
+    auth_config={
+        "method": "headers",
+        "headers": {
+            "Authorization": "Bearer your-token",
+            "X-API-Key": "your-key"
+        }
+    }
+)
+```
+
+---
+
+#### **Troubleshooting Authentication**
+
+##### **Common Issues**
+
+**Problem: "Authentication failed"**
+
+**Solution:**
+1. Verify selectors are correct:
+```bash
+# Test without auth to inspect login form
+cursorflow inspect --base-url http://localhost:3000 \
+  --path /login \
+  --selector "input[type='email']"
+```
+
+2. Check credentials are valid
+3. Verify success indicators:
+```json
+{
+  "auth": {
+    "success_indicators": ["dashboard", "profile"],  // Keywords after login
+    "auth_check_selectors": [".user-avatar"]  // Elements only when logged in
+  }
+}
+```
+
+**Problem: "Session not persisting"**
+
+**Solution:**
+1. Verify session directory exists and is writable:
+```bash
+ls -la .cursorflow/sessions/
+```
+
+2. Check session file was created:
+```bash
+cat .cursorflow/sessions/authenticated_session.json
+```
+
+3. Ensure cookies are being saved:
+```json
+{
+  "timestamp": 1234567890,
+  "method": "form",
+  "cookies": [...],  // Should have cookies here
+  "localStorage": {...},
+  "sessionStorage": {...}
+}
+```
+
+**Problem: "Session expires immediately"**
+
+**Solution:**
+- Check if application has aggressive session timeout
+- Use `fresh_session: True` to force new login:
+```bash
+cursorflow test --use-session "user" --fresh-session
+```
+
+##### **Debugging Authentication**
+
+**Enable verbose logging:**
+```bash
+# See detailed auth flow
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "test" \
+  --verbose
+```
+
+**Check what CursorFlow is doing:**
+```
+🔐 Performing fresh authentication...
+Filled username: #email
+Filled password: #password
+Clicked submit: button[type='submit']
+✅ Form authentication successful
+💾 Session saved: test
+```
+
+**Inspect saved session:**
+```bash
+cat .cursorflow/sessions/test_session.json | python3 -m json.tool
+```
+
+---
+
+#### **Advanced Authentication Scenarios**
+
+##### **Multi-Step Authentication (2FA, OAuth)**
+
+For complex auth flows, use explicit actions instead of auto-auth:
+
+```bash
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/login"},
+  {"fill": {"selector": "#email", "value": "test@example.com"}},
+  {"fill": {"selector": "#password", "value": "testpass"}},
+  {"click": "#login-button"},
+  {"wait_for": "#otp-input"},
+  {"fill": {"selector": "#otp-input", "value": "123456"}},
+  {"click": "#verify-button"},
+  {"wait_for": ".dashboard"},
+  {"screenshot": "authenticated"}
+]' --save-session "2fa-user"
+```
+
+##### **Testing Multiple User Roles**
+
+```bash
+# Admin session
+cursorflow test --base-url http://localhost:3000 \
+  --config admin-config.json \
+  --path /admin \
+  --save-session "admin"
+
+# Regular user session
+cursorflow test --base-url http://localhost:3000 \
+  --config user-config.json \
+  --path /dashboard \
+  --save-session "regular-user"
+
+# Test admin-only features
+cursorflow test --use-session "admin" \
+  --path /admin/users \
+  --screenshot "admin-users"
+
+# Test user features
+cursorflow test --use-session "regular-user" \
+  --path /profile \
+  --screenshot "user-profile"
+```
+
+##### **Getting Cookies from Browser**
+
+**From Chrome DevTools:**
+1. Login to your app in Chrome
+2. Open DevTools (F12) → Application → Cookies
+3. Copy cookie values
+4. Add to config:
+
+```json
+{
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      {
+        "name": "session_id",  // From DevTools
+        "value": "copied-value-here",  // From DevTools
+        "domain": "yourapp.com",
+        "path": "/"
+      }
+    ]
+  }
+}
+```
+
+**From Network Tab:**
+1. Login in browser
+2. DevTools → Network → Find login request
+3. Look at Response Headers for `Set-Cookie`
+4. Copy cookie details to config
+
+##### **Environment-Specific Auth**
+
+Different credentials for local/staging/production:
+
+```json
+{
+  "environments": {
+    "local": {
+      "base_url": "http://localhost:3000",
+      "auth": {
+        "method": "form",
+        "username": "dev@example.com",
+        "password": "devpass"
+      }
+    },
+    "staging": {
+      "base_url": "https://staging.example.com",
+      "auth": {
+        "method": "form",
+        "username": "staging@example.com",
+        "password": "stagingpass"
+      }
+    },
+    "production": {
+      "base_url": "https://example.com",
+      "auth": {
+        "method": "cookies",
+        "cookies": [{"name": "prod_token", "value": "..."}]
+      }
+    }
+  }
+}
+```
+
+```bash
+# Test on staging with staging credentials
+cursorflow test --config config.json \
+  --env staging \
+  --path /dashboard
+```
+
+---
+
+#### **Session Management Commands**
+
+```bash
+# List all saved sessions
+cursorflow sessions list
+# Output:
+# admin-user (saved: 2025-10-10 14:23:45)
+# regular-user (saved: 2025-10-10 14:25:12)
+
+# Delete specific session
+cursorflow sessions delete "admin-user"
+
+# Clear all sessions
+cursorflow sessions clear
+
+# View session info
+cursorflow sessions info "admin-user"
+# Output:
+# Session: admin-user
+# Timestamp: 2025-10-10 14:23:45
+# Method: form
+# Cookies: 3
+# Local Storage: 5 items
+# Session Storage: 2 items
+```
+
+---
+
+#### **Security Considerations**
+
+**Storing Credentials:**
+- Never commit `.cursorflow/config.json` with credentials to version control
+- Add to `.gitignore`:
+```bash
+echo ".cursorflow/config.json" >> .gitignore
+echo ".cursorflow/sessions/" >> .gitignore
+```
+
+- Use environment variables for sensitive data:
+```json
+{
+  "auth": {
+    "method": "form",
+    "username": "${TEST_USER}",
+    "password": "${TEST_PASSWORD}"
+  }
+}
+```
+
+**Session Storage:**
+- Session files contain cookies and tokens - keep secure
+- Stored in `.cursorflow/sessions/` (gitignored by default)
+- Delete sessions when done: `cursorflow sessions clear`
+
+**Best Practices:**
+- Use test accounts, not production accounts
+- Rotate test credentials regularly
+- Use short-lived tokens when possible
+- Clear sessions after testing
+
+---
+
+#### **Without Authentication**
+
+Testing public pages doesn't require auth_config:
+
+```bash
+# No auth needed for public pages
+cursorflow test --base-url https://example.com \
+  --path /about \
+  --screenshot "about-page"
+
+# Session flags are ignored without auth_config
+cursorflow test --base-url https://example.com \
+  --path /contact \
+  --save-session "ignored"  # Has no effect
+```
 
 ### **Quick Commands**
 

{cursorflow-2.7.6 → cursorflow-2.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "2.7.6"
+version = "2.7.7"
 description = "🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis"
 authors = [
     {name = "GeekWarrior Development", email = "rbush@cooltheory.com"}