cursorflow 2.1.5__py3-none-any.whl → 2.2.0__py3-none-any.whl

cursorflow/core/action_validator.py

@@ -0,0 +1,199 @@
+"""
+Action Format Validation
+
+Validates action dictionaries before execution to provide clear error messages.
+"""
+
+from typing import Dict, Any, List, Optional
+
+
+class ActionValidationError(Exception):
+    """Raised when action format is invalid"""
+    pass
+
+
+class ActionValidator:
+    """
+    Validates action format before execution
+    
+    Actions should be dictionaries with a single key indicating the action type,
+    or have an explicit 'type' key.
+    
+    Valid formats:
+        {"click": ".selector"}
+        {"click": {"selector": ".element"}}
+        {"type": "click", "selector": ".element"}
+        {"navigate": "/path"}
+        {"wait": 2}
+    """
+    
+    # CursorFlow-specific action types (not direct Playwright methods)
+    CURSORFLOW_ACTION_TYPES = {
+        'navigate', 'screenshot', 'capture', 'authenticate'
+    }
+    
+    # Common Playwright Page methods (for documentation/validation)
+    COMMON_PLAYWRIGHT_ACTIONS = {
+        'click', 'dblclick', 'hover', 'focus', 'blur',
+        'fill', 'type', 'press', 'select_option', 
+        'check', 'uncheck', 'set_checked',
+        'drag_and_drop', 'tap',
+        'wait', 'wait_for_selector', 'wait_for_timeout', 'wait_for_load_state',
+        'goto', 'reload', 'go_back', 'go_forward',
+        'scroll', 'set_viewport_size', 'bring_to_front',
+        'evaluate', 'evaluate_handle', 'query_selector'
+    }
+    
+    # All known valid actions (CursorFlow + Playwright)
+    # Note: This is not exhaustive - we pass through to Playwright dynamically
+    KNOWN_ACTION_TYPES = CURSORFLOW_ACTION_TYPES | COMMON_PLAYWRIGHT_ACTIONS
+    
+    @classmethod
+    def validate(cls, action: Any) -> Dict[str, Any]:
+        """
+        Validate action format and return normalized action
+        
+        Args:
+            action: The action to validate (should be dict)
+            
+        Returns:
+            Validated and normalized action dict
+            
+        Raises:
+            ActionValidationError: If action format is invalid
+        """
+        # Check if action is a dict
+        if not isinstance(action, dict):
+            raise ActionValidationError(
+                f"Action must be a dictionary, got {type(action).__name__}: {action}\n"
+                f"Expected format: {{'click': '.selector'}} or {{'type': 'click', 'selector': '.element'}}"
+            )
+        
+        # Check if action is empty
+        if not action:
+            raise ActionValidationError(
+                "Action dictionary is empty\n"
+                f"Expected format: {{'click': '.selector'}}"
+            )
+        
+        # Get action type
+        action_type = cls._extract_action_type(action)
+        
+        # Validate action type (permissive - warns for unknown, doesn't block)
+        if action_type not in cls.KNOWN_ACTION_TYPES:
+            # Log warning but allow it (might be valid Playwright method)
+            import logging
+            logger = logging.getLogger(__name__)
+            logger.warning(
+                f"Unknown action type '{action_type}' - will attempt to pass through to Playwright. "
+                f"Common actions: {', '.join(sorted(list(cls.COMMON_PLAYWRIGHT_ACTIONS)[:10]))}... "
+                f"See: https://playwright.dev/python/docs/api/class-page"
+            )
+        
+        return action
+    
+    @classmethod
+    def _extract_action_type(cls, action: dict) -> str:
+        """
+        Extract action type from action dict
+        
+        Supports:
+            {"type": "click", "selector": ".btn"}  # Explicit type key with string value
+            {"click": ".selector"}                  # Action type is the key
+            {"click": {"selector": ".btn"}}        # Action type with config dict
+            {"type": {"selector": "#field"}}       # 'type' as action (typing), not explicit type
+        """
+        # Check if 'type' key exists AND has a string value (explicit type specification)
+        # If type key has a dict value, it's the action itself (typing action)
+        if 'type' in action and isinstance(action['type'], str):
+            return action['type']
+        
+        # Otherwise, first key is the action type
+        keys = list(action.keys())
+        if not keys:
+            raise ActionValidationError("Action has no keys")
+        
+        action_type = keys[0]
+        
+        # First key should be the action type (string)
+        if not isinstance(action_type, str):
+            raise ActionValidationError(
+                f"Action type must be a string, got {type(action_type).__name__}: {action_type}"
+            )
+        
+        return action_type
+    
+    @classmethod
+    def validate_list(cls, actions: Any) -> List[Dict[str, Any]]:
+        """
+        Validate list of actions
+        
+        Args:
+            actions: Should be a list of action dicts
+            
+        Returns:
+            List of validated actions
+            
+        Raises:
+            ActionValidationError: If format is invalid
+        """
+        if not isinstance(actions, list):
+            raise ActionValidationError(
+                f"Actions must be a list, got {type(actions).__name__}: {actions}\n"
+                f"Expected format: [{{'click': '.btn'}}, {{'wait': 2}}]"
+            )
+        
+        if not actions:
+            raise ActionValidationError(
+                "Actions list is empty\n"
+                f"Expected at least one action like: [{{'navigate': '/'}}]"
+            )
+        
+        validated = []
+        for i, action in enumerate(actions):
+            try:
+                validated.append(cls.validate(action))
+            except ActionValidationError as e:
+                raise ActionValidationError(
+                    f"Invalid action at index {i}: {e}"
+                )
+        
+        return validated
+    
+    @classmethod
+    def get_example_actions(cls) -> str:
+        """Get example action formats for help text"""
+        return """
+Action Format Examples:
+
+  Common CursorFlow actions:
+    {"navigate": "/dashboard"}
+    {"click": ".button"}
+    {"screenshot": "page-loaded"}
+  
+  Any Playwright Page method:
+    {"hover": ".menu-item"}
+    {"dblclick": ".editable"}
+    {"press": "Enter"}
+    {"drag_and_drop": {"source": ".item", "target": ".dropzone"}}
+    {"focus": "#input"}
+    {"check": "#checkbox"}
+    {"evaluate": "window.scrollTo(0, 100)"}
+  
+  See full Playwright API:
+    https://playwright.dev/python/docs/api/class-page
+  
+  CursorFlow passes actions directly to Playwright, giving you access
+  to 94+ methods without artificial limitations.
+  
+  Complete workflow:
+    [
+      {"navigate": "/login"},
+      {"fill": {"selector": "#username", "value": "admin"}},
+      {"fill": {"selector": "#password", "value": "pass123"}},
+      {"click": "#submit"},
+      {"wait_for_selector": ".dashboard"},
+      {"screenshot": "logged-in"}
+    ]
+"""
+

cursorflow/core/browser_controller.py

@@ -79,8 +79,8 @@ class BrowserController:
             
             self.playwright = await async_playwright().start()
             
-            # Browser configuration - works for any framework
-            browser_config = {
+            # Browser configuration - smart defaults with pass-through
+            default_browser_config = {
                 "headless": self.config.get("headless", True),
                 "slow_mo": 0 if self.config.get("headless", True) else 100,
                 "args": [
@@ -92,16 +92,42 @@ class BrowserController:
                 ]
             }
             
+            # Pass-through architecture: Merge user options with defaults
+            # Users can override ANY Playwright launch option
+            # See: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch
+            user_browser_options = self.config.get("browser_launch_options", {})
+            
+            # Validate user options (warns about typos, validates types)
+            from .config_validator import ConfigValidator
+            if user_browser_options:
+                user_browser_options = ConfigValidator.validate_browser_options(user_browser_options)
+            
+            browser_config = {**default_browser_config, **user_browser_options}
+            
             self.browser = await self.playwright.chromium.launch(**browser_config)
             
-            # Context configuration
+            # Context configuration - smart defaults with pass-through
             viewport = self.config.get("viewport", {"width": 1440, "height": 900})
-            context_config = {
+            default_context_config = {
                 "viewport": viewport,
                 "ignore_https_errors": True,
                 "record_video_dir": ".cursorflow/artifacts/videos" if self.config.get("record_video") else None
             }
             
+            # Pass-through architecture: Merge user options with defaults
+            # Users can use ANY Playwright context option:
+            # - geolocation, permissions, timezone, locale
+            # - color_scheme, reduced_motion, http_credentials
+            # - user_agent, extra_http_headers, offline
+            # See: https://playwright.dev/python/docs/api/class-browser#browser-new-context
+            user_context_options = self.config.get("context_options", {})
+            
+            # Validate user options (warns about typos, validates types)
+            if user_context_options:
+                user_context_options = ConfigValidator.validate_context_options(user_context_options)
+            
+            context_config = {**default_context_config, **user_context_options}
+            
             self.context = await self.browser.new_context(**context_config)
             self.page = await self.context.new_page()
             
@@ -275,6 +301,9 @@ class BrowserController:
         }
         self.network_requests.append(response_data)
         
+        # Capture response body asynchronously (Phase 1.4: Network Response Body Capture)
+        asyncio.create_task(self._capture_response_body_async(response, response_data))
+        
         # Log failed requests for correlation
         if response.status >= 400:
             self.logger.warning(f"Failed Response: {response.status} {response.url}")
@@ -682,8 +711,47 @@ class BrowserController:
             self.logger.error(f"Browser cleanup failed: {e}")
             return None
     
+    async def _capture_response_body_async(self, response, response_data: Dict):
+        """
+        Async wrapper to capture response body without blocking event handlers
+        
+        Phase 1.4: Network Response Body Capture
+        Captures request/response bodies for complete debugging data
+        """
+        try:
+            # Get response body
+            body = await response.body()
+            decoded_body = body.decode('utf-8', errors='ignore')
+            
+            # Update the response_data dict directly (it's already in self.network_requests)
+            response_data["response_body"] = decoded_body[:5000]  # Capture more for debugging
+            response_data["response_body_size"] = len(decoded_body)
+            response_data["response_body_truncated"] = len(decoded_body) > 5000
+            
+            # Parse JSON responses automatically
+            content_type = response.headers.get("content-type", "")
+            if "application/json" in content_type:
+                try:
+                    import json
+                    response_data["response_body_json"] = json.loads(decoded_body)
+                    
+                    # Log key data for debugging undefined values
+                    self.logger.debug(f"JSON Response from {response.url[:50]}: {len(response_data['response_body_json'])} keys")
+                except json.JSONDecodeError as e:
+                    response_data["json_parse_error"] = str(e)
+                    self.logger.warning(f"Failed to parse JSON response from {response.url}: {e}")
+            
+            # Log error responses
+            if response.status >= 400:
+                error_preview = decoded_body[:200].replace('\n', ' ')
+                self.logger.error(f"Error response ({response.status}) from {response.url}: {error_preview}")
+                    
+        except Exception as e:
+            self.logger.debug(f"Response body capture failed for {response.url}: {e}")
+            response_data["body_capture_error"] = str(e)
+    
     async def _capture_response_body(self, response):
-        """Capture response body for API calls and errors"""
+        """Legacy method - captures response body for specific cases"""
         try:
             body = await response.body()
             decoded_body = body.decode('utf-8', errors='ignore')
@@ -723,6 +791,227 @@ class BrowserController:
                     req["body_capture_error"] = str(e)
                     break
     
+    async def _capture_javascript_context(self) -> Dict[str, Any]:
+        """
+        Phase 2.2: JavaScript Context Capture
+        
+        Captures global JavaScript scope including:
+        - Global functions (enumerate window properties that are functions)
+        - Global variables (enumerate window properties that are not functions)
+        - Specific window objects (configurable list to serialize)
+        """
+        try:
+            # Get list of objects to capture from config
+            capture_objects = self.config.get("capture_window_objects", [])
+            
+            context_data = await self.page.evaluate("""
+                (captureObjects) => {
+                    const context = {
+                        global_functions: [],
+                        global_variables: [],
+                        window_property_count: 0,
+                        window_objects: {}
+                    };
+                    
+                    // Enumerate window properties
+                    const windowProps = Object.getOwnPropertyNames(window);
+                    context.window_property_count = windowProps.length;
+                    
+                    // Categorize by type
+                    windowProps.forEach(prop => {
+                        try {
+                            const value = window[prop];
+                            
+                            // Skip built-in browser objects (too many)
+                            if (prop.startsWith('webkit') || prop.startsWith('moz') || 
+                                prop.startsWith('chrome') || prop === 'constructor') {
+                                return;
+                            }
+                            
+                            if (typeof value === 'function') {
+                                // Skip native functions (toString contains '[native code]')
+                                const funcStr = value.toString();
+                                if (!funcStr.includes('[native code]')) {
+                                    context.global_functions.push(prop);
+                                }
+                            } else if (value !== null && typeof value !== 'undefined' && 
+                                      typeof value !== 'function' && typeof value !== 'object') {
+                                // Primitive global variables
+                                context.global_variables.push({
+                                    name: prop,
+                                    type: typeof value,
+                                    value: String(value).substring(0, 100)  // Truncate long values
+                                });
+                            }
+                        } catch (e) {
+                            // Skip properties that throw on access
+                        }
+                    });
+                    
+                    // Capture specific window objects (configurable)
+                    captureObjects.forEach(objName => {
+                        try {
+                            const obj = window[objName];
+                            if (obj && typeof obj === 'object') {
+                                // Serialize object (handle circular references)
+                                context.window_objects[objName] = JSON.parse(
+                                    JSON.stringify(obj, (key, value) => {
+                                        // Handle circular references
+                                        if (typeof value === 'object' && value !== null) {
+                                            if (key && typeof value === 'object' && Object.keys(value).length > 50) {
+                                                return '[Large Object]';
+                                            }
+                                        }
+                                        // Handle functions
+                                        if (typeof value === 'function') {
+                                            return '[Function]';
+                                        }
+                                        return value;
+                                    })
+                                );
+                            }
+                        } catch (e) {
+                            context.window_objects[objName] = {
+                                error: `Failed to serialize: ${e.message}`
+                            };
+                        }
+                    });
+                    
+                    return context;
+                }
+            """, capture_objects)
+            
+            return context_data
+            
+        except Exception as e:
+            self.logger.error(f"JavaScript context capture failed: {e}")
+            return {
+                "error": str(e),
+                "global_functions": [],
+                "global_variables": [],
+                "window_objects": {}
+            }
+    
+    async def _capture_storage_state(self) -> Dict[str, Any]:
+        """
+        Phase 2.3: Storage State Capture
+        
+        Captures browser storage state:
+        - localStorage
+        - sessionStorage
+        - cookies
+        
+        Masks sensitive keys based on configuration.
+        """
+        try:
+            # Get masking configuration
+            sensitive_keys = self.config.get("sensitive_storage_keys", [
+                "authToken", "apiKey", "sessionId", "password", "secret", "token"
+            ])
+            
+            storage_data = await self.page.evaluate("""
+                (sensitiveKeys) => {
+                    const storage = {
+                        localStorage: {},
+                        sessionStorage: {},
+                        cookies: []
+                    };
+                    
+                    // Capture localStorage
+                    for (let i = 0; i < localStorage.length; i++) {
+                        const key = localStorage.key(i);
+                        const value = localStorage.getItem(key);
+                        
+                        // Mask sensitive keys
+                        const isSensitive = sensitiveKeys.some(pattern => 
+                            key.toLowerCase().includes(pattern.toLowerCase())
+                        );
+                        
+                        storage.localStorage[key] = isSensitive ? '****' : value;
+                    }
+                    
+                    // Capture sessionStorage
+                    for (let i = 0; i < sessionStorage.length; i++) {
+                        const key = sessionStorage.key(i);
+                        const value = sessionStorage.getItem(key);
+                        
+                        const isSensitive = sensitiveKeys.some(pattern =>
+                            key.toLowerCase().includes(pattern.toLowerCase())
+                        );
+                        
+                        storage.sessionStorage[key] = isSensitive ? '****' : value;
+                    }
+                    
+                    // Capture cookies (just names, not values for security)
+                    storage.cookies = document.cookie.split(';').map(c => c.trim().split('=')[0]);
+                    
+                    return storage;
+                }
+            """, sensitive_keys)
+            
+            return storage_data
+            
+        except Exception as e:
+            self.logger.error(f"Storage state capture failed: {e}")
+            return {
+                "error": str(e),
+                "localStorage": {},
+                "sessionStorage": {},
+                "cookies": []
+            }
+    
+    async def _capture_form_state(self) -> Dict[str, Any]:
+        """
+        Phase 2.4: Form State Capture
+        
+        Captures all form field values at time of capture.
+        Automatically masks password fields.
+        """
+        try:
+            form_data = await self.page.evaluate("""
+                () => {
+                    const forms = {};
+                    
+                    // Get all forms on page
+                    document.querySelectorAll('form').forEach(form => {
+                        const formId = form.id || form.name || `form_${forms.length}`;
+                        const formData = {};
+                        
+                        // Get all form inputs
+                        form.querySelectorAll('input, select, textarea').forEach(field => {
+                            const fieldName = field.name || field.id || `field_${field.type}`;
+                            
+                            // Mask password fields
+                            if (field.type === 'password') {
+                                formData[fieldName] = '****';
+                            }
+                            // Checkbox/radio
+                            else if (field.type === 'checkbox' || field.type === 'radio') {
+                                formData[fieldName] = field.checked;
+                            }
+                            // Select dropdowns
+                            else if (field.tagName === 'SELECT') {
+                                formData[fieldName] = field.value;
+                            }
+                            // Text inputs, textareas
+                            else {
+                                formData[fieldName] = field.value;
+                            }
+                        });
+                        
+                        forms[formId] = formData;
+                    });
+                    
+                    return forms;
+                }
+            """)
+            
+            return form_data
+            
+        except Exception as e:
+            self.logger.error(f"Form state capture failed: {e}")
+            return {"error": str(e)}
+    
     def _categorize_http_error(self, status_code: int) -> str:
         """Categorize HTTP errors for better debugging (v2.0 enhancement)"""
         if 400 <= status_code < 500:
@@ -872,6 +1161,9 @@ class BrowserController:
                 "dom_analysis": dom_analysis,
                 "network_data": network_data,
                 "console_data": console_data,
+                "javascript_context": javascript_context,
+                "storage_state": storage_state,
+                "form_state": form_state,
                 "performance_data": performance_data,
                 "page_state": page_state,
                 
@@ -1750,6 +2042,9 @@ class BrowserController:
                                         // v2.0 Enhancement: Accessibility data
                                         accessibility: getAccessibilityData(element),
                                         
+                                        // Phase 2.1: Event Handlers
+                                        event_handlers: getEventHandlers(element),
+                                        
                                         // v2.0 Enhancement: Visual context
                                         visual_context: visualContext,
                                         

cursorflow/core/browser_engine.py

@@ -192,6 +192,19 @@ class BrowserEngine:
     async def _execute_action(self, action: Dict) -> Dict:
         """Execute a single test action"""
         
+        # Validate action format
+        from .action_validator import ActionValidator, ActionValidationError
+        
+        try:
+            action = ActionValidator.validate(action)
+        except ActionValidationError as e:
+            return {
+                'action': 'unknown',
+                'success': False,
+                'error': f"Invalid action format: {e}"
+            }
+        
+        # Extract action type safely
         action_type = action.get('type') or list(action.keys())[0]
         action_config = action.get(action_type, action)