cursorflow 2.7.6__py3-none-any.whl → 2.7.7__py3-none-any.whl

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.dist-info → cursorflow-2.7.7.dist-info}/METADATA

@@ -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.dist-info → cursorflow-2.7.7.dist-info}/RECORD

@@ -33,10 +33,10 @@ cursorflow/log_sources/local_file.py,sha256=GVnhsaifIdc41twXwbxRM9-fBeRDsknDpk5I
 cursorflow/log_sources/ssh_remote.py,sha256=_Kwh0bhRpKgq-0c98oaX2hN6h9cT-wCHlqY5NiWVCoY,8388
 cursorflow/rules/__init__.py,sha256=gPcA-IkhXj03sl7cvZV0wwo7CtEkcyuKs4y0F5oQbqE,458
 cursorflow/rules/cursorflow-installation.mdc,sha256=D55pzzDPAVVbE3gAtKPUGoT-2fvB-FI2l6yrTdzUIEo,10208
-cursorflow/rules/cursorflow-usage.mdc,sha256=OYsqF1OKeGP5Bl8yR5TJ92dDXH7C3yp-SKAs9aZfBAw,34744
-cursorflow-2.7.6.dist-info/licenses/LICENSE,sha256=e4QbjAsj3bW-xgQOvQelr8sGLYDoqc48k6cKgCr_pBU,1080
-cursorflow-2.7.6.dist-info/METADATA,sha256=0_8B5N3kBPoAiRTCoz2lIdFrSiMLzAjeBeGYi59GVCs,19844
-cursorflow-2.7.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cursorflow-2.7.6.dist-info/entry_points.txt,sha256=-Ed_n4Uff7wClEtWS-Py6xmQabecB9f0QAOjX0w7ljA,51
-cursorflow-2.7.6.dist-info/top_level.txt,sha256=t1UZwRyZP4u-ng2CEcNHmk_ZT4ibQxoihB2IjTF7ovc,11
-cursorflow-2.7.6.dist-info/RECORD,,
+cursorflow/rules/cursorflow-usage.mdc,sha256=oTp9RTyhZfRjX5DJq-R2lthT2E0nF-5gA-Ao13jjS5A,37490
+cursorflow-2.7.7.dist-info/licenses/LICENSE,sha256=e4QbjAsj3bW-xgQOvQelr8sGLYDoqc48k6cKgCr_pBU,1080
+cursorflow-2.7.7.dist-info/METADATA,sha256=M_sXtrzj4lW1jDIHuRnuPzrotxlv8scA78PdvRQORKg,20838
+cursorflow-2.7.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cursorflow-2.7.7.dist-info/entry_points.txt,sha256=-Ed_n4Uff7wClEtWS-Py6xmQabecB9f0QAOjX0w7ljA,51
+cursorflow-2.7.7.dist-info/top_level.txt,sha256=t1UZwRyZP4u-ng2CEcNHmk_ZT4ibQxoihB2IjTF7ovc,11
+cursorflow-2.7.7.dist-info/RECORD,,