cursorflow 2.7.5__tar.gz → 2.7.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.7.5
+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.5 → 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.5 → cursorflow-2.7.7}/cursorflow/core/query_engine.py

@@ -420,29 +420,90 @@ class QueryEngine:
         
         # Phase 1: Enhanced DOM filtering
         
-        # Filter by selector (improved matching)
+        # Filter by selector (improved matching with correct field paths and priority)
         if 'selector' in filters or 'select' in filters:
             selector = filters.get('selector') or filters.get('select')
-            # Remove leading dot if present (e.g., ".class" -> "class")
-            selector_clean = selector.lstrip('.')
             
-            filtered_elements = [
-                el for el in filtered_elements
+            # Detect selector type
+            is_id_selector = selector.startswith('#')
+            is_class_selector = selector.startswith('.')
+            
+            # Remove leading dot or hash if present (e.g., ".class" -> "class", "#id" -> "id")
+            selector_clean = selector.lstrip('.#')
+            
+            # Determine if this looks like a simple tag name (no special characters)
+            is_simple_tag = selector.isalpha() and not is_id_selector and not is_class_selector
+            
+            result_elements = []
+            for el in filtered_elements:
+                matched = False
+                
+                # Priority 1: ID selector (#id) - only check ID field
+                if is_id_selector:
+                    if selector_clean == el.get('id', ''):
+                        result_elements.append(el)
+                    continue
+                
+                # Priority 2: Class selector (.class) - only check className
+                if is_class_selector:
+                    if el.get('className'):
+                        class_names = str(el.get('className')).split()
+                        if selector_clean in class_names:
+                            result_elements.append(el)
+                    # Backward compatibility: Check classes array (old format)
+                    elif selector_clean in el.get('classes', []):
+                        result_elements.append(el)
+                    continue
+                
+                # Priority 3: For simple alphanumeric selectors, check tagName, ID, and className
+                # This handles ambiguous cases like "page" (could be tag or ID)
+                if is_simple_tag:
+                    # Check tag name match (exact, case insensitive)
+                    if selector.lower() == el.get('tagName', '').lower():
+                        result_elements.append(el)
+                        continue
+                    
+                    # Check ID match (exact)
+                    if selector_clean == el.get('id', ''):
+                        result_elements.append(el)
+                        continue
+                    
+                    # Class name match (whole word match to avoid "a" matching "navbar")
+                    if el.get('className'):
+                        class_names = str(el.get('className')).split()
+                        if selector_clean in class_names:
+                            result_elements.append(el)
+                            continue
+                    
+                    # Backward compatibility: Check classes array (old format)
+                    if selector_clean in el.get('classes', []):
+                        result_elements.append(el)
+                    
+                    # Don't fall through to selector string checks for simple tags
+                    continue
+                
+                # Priority 2: For complex selectors, check selector strings and attributes
                 if (
-                    # Check nested uniqueSelector
+                    # Check selectors.unique_css (current format)
+                    (selector in el.get('selectors', {}).get('unique_css', '')) or
+                    # Check selectors.css (current format)  
+                    (selector in el.get('selectors', {}).get('css', '')) or
+                    # Check selectors.xpath
+                    (selector in el.get('selectors', {}).get('xpath', '')) or
+                    # Check ID (exact match or contains for partial IDs)
+                    (el.get('id') and selector_clean in str(el.get('id'))) or
+                    # Check className (can be string or None)
+                    (el.get('className') and selector_clean in str(el.get('className'))) or
+                    # Backward compatibility: Check nested uniqueSelector (old format)
                     (selector in el.get('selectors', {}).get('uniqueSelector', '')) or
-                    # Check top-level uniqueSelector (old format)
+                    # Backward compatibility: Check top-level uniqueSelector (old format)
                     (selector in el.get('uniqueSelector', '')) or
-                    # Check tagName
-                    (selector in el.get('tagName', '')) or
-                    # Check ID
-                    (selector == el.get('id', '')) or
-                    # Check className string
-                    (el.get('className') and selector_clean in el.get('className', '')) or
-                    # Check classes array (old format)
+                    # Backward compatibility: Check classes array (old format)
                     (selector_clean in el.get('classes', []))
-                )
-            ]
+                ):
+                    result_elements.append(el)
+            
+            filtered_elements = result_elements
         
         # Filter by attributes
         if 'with_attr' in filters:
@@ -460,18 +521,18 @@ class QueryEngine:
                 if el.get('accessibility', {}).get('role') == role
             ]
         
-        # Filter by visibility
+        # Filter by visibility (use correct nested path)
         if 'visible' in filters and filters['visible']:
             filtered_elements = [
                 el for el in filtered_elements
-                if el.get('visual_context', {}).get('isVisible', True)
+                if el.get('visual_context', {}).get('visibility', {}).get('is_visible', False)
             ]
         
-        # Filter by interactivity
+        # Filter by interactivity (use correct nested path)
         if 'interactive' in filters and filters['interactive']:
             filtered_elements = [
                 el for el in filtered_elements
-                if el.get('accessibility', {}).get('isInteractive', False)
+                if el.get('accessibility', {}).get('is_interactive', False)
             ]
         
         # Filter elements with errors (from console errors)
@@ -958,6 +1019,10 @@ class QueryEngine:
         elif format == "csv":
             return self._to_csv(data, data_type)
         
+        elif format == "dict" or format == "raw":
+            # Return raw dictionary (useful for programmatic access)
+            return data
+        
         else:
             return data
     

{cursorflow-2.7.5 → 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