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

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)
         

cursorflow/core/config_validator.py

@@ -0,0 +1,216 @@
+"""
+Configuration Validation
+
+Validates user-provided configuration against Playwright API.
+Provides clear error messages with links to documentation.
+"""
+
+from typing import Dict, Any, Set
+import logging
+
+
+class ConfigValidationError(Exception):
+    """Raised when configuration is invalid"""
+    pass
+
+
+class ConfigValidator:
+    """
+    Validates CursorFlow and Playwright configuration
+    
+    Strategy: We don't strictly validate - we warn about likely errors
+    and let Playwright do final validation. This keeps us forward-compatible.
+    """
+    
+    # Common browser launch options (for helpful warnings)
+    # See: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch
+    KNOWN_BROWSER_OPTIONS = {
+        'args', 'channel', 'chromium_sandbox', 'devtools', 'downloads_path',
+        'env', 'executable_path', 'firefox_user_prefs', 'handle_sigint',
+        'handle_sigterm', 'handle_sighup', 'headless', 'ignore_default_args',
+        'proxy', 'slow_mo', 'timeout', 'traces_dir'
+    }
+    
+    # Common context options (for helpful warnings)
+    # See: https://playwright.dev/python/docs/api/class-browser#browser-new-context
+    KNOWN_CONTEXT_OPTIONS = {
+        'accept_downloads', 'base_url', 'bypass_csp', 'color_scheme',
+        'device_scale_factor', 'extra_http_headers', 'forced_colors',
+        'geolocation', 'has_touch', 'http_credentials', 'ignore_https_errors',
+        'is_mobile', 'java_script_enabled', 'locale', 'no_viewport',
+        'offline', 'permissions', 'proxy', 'record_har_content',
+        'record_har_mode', 'record_har_omit_content', 'record_har_path',
+        'record_har_url_filter', 'record_video_dir', 'record_video_size',
+        'reduced_motion', 'screen', 'service_workers', 'storage_state',
+        'strict_selectors', 'timezone_id', 'user_agent', 'viewport'
+    }
+    
+    @classmethod
+    def validate_browser_options(cls, options: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validate browser launch options
+        
+        Args:
+            options: User-provided browser options
+            
+        Returns:
+            Validated options (unchanged - just warnings logged)
+        """
+        logger = logging.getLogger(__name__)
+        
+        # Warn about unknown options (might be typos)
+        for key in options.keys():
+            if key not in cls.KNOWN_BROWSER_OPTIONS:
+                logger.warning(
+                    f"Unknown browser option '{key}' - will pass to Playwright anyway. "
+                    f"Check spelling or see: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch"
+                )
+        
+        # Validate specific option types
+        if 'headless' in options and not isinstance(options['headless'], bool):
+            raise ConfigValidationError(
+                f"'headless' must be boolean, got {type(options['headless']).__name__}: {options['headless']}"
+            )
+        
+        if 'timeout' in options and not isinstance(options['timeout'], (int, float)):
+            raise ConfigValidationError(
+                f"'timeout' must be number, got {type(options['timeout']).__name__}: {options['timeout']}"
+            )
+        
+        if 'args' in options and not isinstance(options['args'], list):
+            raise ConfigValidationError(
+                f"'args' must be list of strings, got {type(options['args']).__name__}"
+            )
+        
+        return options
+    
+    @classmethod
+    def validate_context_options(cls, options: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validate browser context options
+        
+        Args:
+            options: User-provided context options
+            
+        Returns:
+            Validated options (unchanged - just warnings logged)
+        """
+        logger = logging.getLogger(__name__)
+        
+        # Warn about unknown options
+        for key in options.keys():
+            if key not in cls.KNOWN_CONTEXT_OPTIONS:
+                logger.warning(
+                    f"Unknown context option '{key}' - will pass to Playwright anyway. "
+                    f"Check spelling or see: https://playwright.dev/python/docs/api/class-browser#browser-new-context"
+                )
+        
+        # Validate specific option types
+        if 'viewport' in options:
+            viewport = options['viewport']
+            if not isinstance(viewport, dict):
+                raise ConfigValidationError(
+                    f"'viewport' must be dict with width/height, got {type(viewport).__name__}"
+                )
+            if 'width' in viewport and not isinstance(viewport['width'], int):
+                raise ConfigValidationError(
+                    f"viewport width must be integer, got {type(viewport['width']).__name__}"
+                )
+            if 'height' in viewport and not isinstance(viewport['height'], int):
+                raise ConfigValidationError(
+                    f"viewport height must be integer, got {type(viewport['height']).__name__}"
+                )
+        
+        if 'geolocation' in options:
+            geo = options['geolocation']
+            if not isinstance(geo, dict) or 'latitude' not in geo or 'longitude' not in geo:
+                raise ConfigValidationError(
+                    f"'geolocation' must be dict with latitude/longitude: "
+                    f"{{'latitude': 40.7128, 'longitude': -74.0060}}"
+                )
+        
+        if 'timezone_id' in options and not isinstance(options['timezone_id'], str):
+            raise ConfigValidationError(
+                f"'timezone_id' must be string like 'America/New_York', got {type(options['timezone_id']).__name__}"
+            )
+        
+        return options
+    
+    @classmethod
+    def get_config_examples(cls) -> str:
+        """Get example configurations for documentation"""
+        return """
+Browser Configuration Examples:
+
+  Enable DevTools (non-headless):
+    {
+      "headless": false,
+      "browser_launch_options": {
+        "devtools": true
+      }
+    }
+  
+  Use specific Chrome channel:
+    {
+      "browser_launch_options": {
+        "channel": "chrome"
+      }
+    }
+  
+  Custom proxy:
+    {
+      "browser_launch_options": {
+        "proxy": {
+          "server": "http://myproxy.com:3128",
+          "username": "user",
+          "password": "pass"
+        }
+      }
+    }
+
+Context Configuration Examples:
+
+  Test in dark mode:
+    {
+      "context_options": {
+        "color_scheme": "dark"
+      }
+    }
+  
+  Test with geolocation:
+    {
+      "context_options": {
+        "geolocation": {"latitude": 40.7128, "longitude": -74.0060},
+        "permissions": ["geolocation"]
+      }
+    }
+  
+  Test offline behavior:
+    {
+      "context_options": {
+        "offline": true
+      }
+    }
+  
+  Custom timezone:
+    {
+      "context_options": {
+        "timezone_id": "America/Los_Angeles"
+      }
+    }
+  
+  HTTP authentication:
+    {
+      "context_options": {
+        "http_credentials": {
+          "username": "admin",
+          "password": "secret"
+        }
+      }
+    }
+
+See Playwright documentation for all available options:
+  Browser: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch
+  Context: https://playwright.dev/python/docs/api/class-browser#browser-new-context
+"""
+