waitless 0.1.0__py3-none-any.whl

waitless/instrumentation.py

@@ -0,0 +1,328 @@
+"""
+JavaScript instrumentation for browser-side stability monitoring.
+"""
+
+INSTRUMENTATION_SCRIPT = """
+(function() {
+    // Avoid re-initialization
+    if (window.__waitless__ && window.__waitless__._initialized) {
+        return window.__waitless__;
+    }
+    
+    window.__waitless__ = {
+        _initialized: true,
+        _version: '0.1.0',
+        
+        // State tracking
+        pendingRequests: 0,
+        lastMutationTime: Date.now(),
+        activeAnimations: 0,
+        activeTransitions: 0,
+        layoutShifting: false,
+        
+        // Timeline for diagnostics (circular buffer)
+        timeline: [],
+        _maxTimelineEntries: 100,
+        
+        // Request tracking for diagnostics
+        pendingRequestDetails: [],
+        
+        // Configuration (updated from Python)
+        config: {
+            trackLayout: true,
+            trackAnimations: true,
+        },
+        
+        // Lifecycle
+        _observers: [],
+        _originalFetch: null,
+        _originalXHROpen: null,
+        _originalXHRSend: null,
+        
+        // ===== INITIALIZATION =====
+        
+        init: function() {
+            this._setupMutationObserver();
+            this._setupNetworkInterceptors();
+            this._setupAnimationTracking();
+            if (this.config.trackLayout) {
+                this._setupLayoutTracking();
+            }
+            this._log('Waitless instrumentation initialized');
+            return this;
+        },
+        
+        // ===== LOGGING =====
+        
+        _log: function(message, data) {
+            var entry = {
+                time: Date.now(),
+                message: message,
+                data: data || null
+            };
+            this.timeline.push(entry);
+            if (this.timeline.length > this._maxTimelineEntries) {
+                this.timeline.shift();
+            }
+        },
+        
+        // ===== MUTATION OBSERVER =====
+        
+        _setupMutationObserver: function() {
+            var self = this;
+            var observer = new MutationObserver(function(mutations) {
+                self.lastMutationTime = Date.now();
+                self._log('DOM mutation', { count: mutations.length });
+            });
+            
+            observer.observe(document.documentElement || document.body, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+                characterData: true
+            });
+            
+            this._observers.push(observer);
+        },
+        
+        // ===== NETWORK INTERCEPTORS =====
+        
+        _setupNetworkInterceptors: function() {
+            var self = this;
+            
+            // Intercept fetch
+            this._originalFetch = window.fetch;
+            window.fetch = function(input, init) {
+                var url = typeof input === 'string' ? input : input.url;
+                self._requestStarted(url, 'fetch');
+                
+                return self._originalFetch.apply(window, arguments)
+                    .then(function(response) {
+                        self._requestEnded(url, 'fetch', response.status);
+                        return response;
+                    })
+                    .catch(function(error) {
+                        self._requestEnded(url, 'fetch', 'error');
+                        throw error;
+                    });
+            };
+            
+            // Intercept XMLHttpRequest
+            this._originalXHROpen = XMLHttpRequest.prototype.open;
+            this._originalXHRSend = XMLHttpRequest.prototype.send;
+            
+            XMLHttpRequest.prototype.open = function(method, url) {
+                this._waitless_url = url;
+                this._waitless_method = method;
+                return self._originalXHROpen.apply(this, arguments);
+            };
+            
+            XMLHttpRequest.prototype.send = function() {
+                var xhr = this;
+                var url = xhr._waitless_url || 'unknown';
+                
+                self._requestStarted(url, 'xhr');
+                
+                xhr.addEventListener('loadend', function() {
+                    self._requestEnded(url, 'xhr', xhr.status);
+                });
+                
+                return self._originalXHRSend.apply(this, arguments);
+            };
+        },
+        
+        _requestStarted: function(url, type) {
+            this.pendingRequests++;
+            this.pendingRequestDetails.push({
+                url: url,
+                type: type,
+                startTime: Date.now()
+            });
+            this._log('Request started', { url: url, type: type, pending: this.pendingRequests });
+        },
+        
+        _requestEnded: function(url, type, status) {
+            this.pendingRequests = Math.max(0, this.pendingRequests - 1);
+            
+            // Remove from pending details
+            var idx = this.pendingRequestDetails.findIndex(function(r) {
+                return r.url === url && r.type === type;
+            });
+            if (idx > -1) {
+                this.pendingRequestDetails.splice(idx, 1);
+            }
+            
+            this._log('Request ended', { url: url, type: type, status: status, pending: this.pendingRequests });
+        },
+        
+        // ===== ANIMATION TRACKING =====
+        
+        _setupAnimationTracking: function() {
+            var self = this;
+            
+            // CSS Animations
+            document.addEventListener('animationstart', function(e) {
+                self.activeAnimations++;
+                self._log('Animation started', { name: e.animationName });
+            }, true);
+            
+            document.addEventListener('animationend', function(e) {
+                self.activeAnimations = Math.max(0, self.activeAnimations - 1);
+                self._log('Animation ended', { name: e.animationName });
+            }, true);
+            
+            document.addEventListener('animationcancel', function(e) {
+                self.activeAnimations = Math.max(0, self.activeAnimations - 1);
+                self._log('Animation cancelled', { name: e.animationName });
+            }, true);
+            
+            // CSS Transitions
+            document.addEventListener('transitionstart', function(e) {
+                self.activeTransitions++;
+                self._log('Transition started', { property: e.propertyName });
+            }, true);
+            
+            document.addEventListener('transitionend', function(e) {
+                self.activeTransitions = Math.max(0, self.activeTransitions - 1);
+                self._log('Transition ended', { property: e.propertyName });
+            }, true);
+            
+            document.addEventListener('transitioncancel', function(e) {
+                self.activeTransitions = Math.max(0, self.activeTransitions - 1);
+                self._log('Transition cancelled', { property: e.propertyName });
+            }, true);
+        },
+        
+        // ===== LAYOUT TRACKING =====
+        
+        _setupLayoutTracking: function() {
+            var self = this;
+            this._lastPositions = new Map();
+            this._layoutCheckInterval = null;
+            
+            // Periodic layout stability check
+            this._layoutCheckInterval = setInterval(function() {
+                self._checkLayoutStability();
+            }, 50);
+        },
+        
+        _checkLayoutStability: function() {
+            // Track key interactive elements
+            var elements = document.querySelectorAll('button, a, input, [onclick], [role="button"]');
+            var isShifting = false;
+            var self = this;
+            
+            elements.forEach(function(el) {
+                var rect = el.getBoundingClientRect();
+                var key = el.id || el.className || el.tagName;
+                var lastPos = self._lastPositions.get(el);
+                
+                if (lastPos) {
+                    var dx = Math.abs(rect.left - lastPos.left);
+                    var dy = Math.abs(rect.top - lastPos.top);
+                    if (dx > 1 || dy > 1) {
+                        isShifting = true;
+                    }
+                }
+                
+                self._lastPositions.set(el, {
+                    left: rect.left,
+                    top: rect.top,
+                    width: rect.width,
+                    height: rect.height
+                });
+            });
+            
+            if (this.layoutShifting !== isShifting) {
+                this.layoutShifting = isShifting;
+                this._log('Layout stability changed', { shifting: isShifting });
+            }
+        },
+        
+        // ===== PUBLIC API =====
+        
+        getStatus: function() {
+            return {
+                stable: this.isStable(),
+                pending_requests: this.pendingRequests,
+                last_mutation_time: this.lastMutationTime,
+                active_animations: this.activeAnimations + this.activeTransitions,
+                layout_shifting: this.layoutShifting,
+                pending_request_details: this.pendingRequestDetails.slice(),
+                timeline: this.timeline.slice(-20)
+            };
+        },
+        
+        isStable: function() {
+            if (this.pendingRequests > 0) return false;
+            
+            var timeSinceLastMutation = Date.now() - this.lastMutationTime;
+            if (timeSinceLastMutation < 100) return false;
+            
+            return true;
+        },
+        
+        isAlive: function() {
+            return this._initialized === true;
+        },
+        
+        // Cleanup (for testing)
+        destroy: function() {
+            this._observers.forEach(function(obs) {
+                obs.disconnect();
+            });
+            
+            if (this._originalFetch) {
+                window.fetch = this._originalFetch;
+            }
+            if (this._originalXHROpen) {
+                XMLHttpRequest.prototype.open = this._originalXHROpen;
+            }
+            if (this._originalXHRSend) {
+                XMLHttpRequest.prototype.send = this._originalXHRSend;
+            }
+            if (this._layoutCheckInterval) {
+                clearInterval(this._layoutCheckInterval);
+            }
+            
+            this._initialized = false;
+            this._log('Waitless instrumentation destroyed');
+        }
+    };
+    
+    return window.__waitless__.init();
+})();
+"""
+
+# Script to check if instrumentation is alive
+CHECK_ALIVE_SCRIPT = """
+return window.__waitless__ && window.__waitless__.isAlive && window.__waitless__.isAlive();
+"""
+
+# Script to get current stability status
+GET_STATUS_SCRIPT = """
+if (window.__waitless__ && window.__waitless__.getStatus) {
+    return window.__waitless__.getStatus();
+}
+return null;
+"""
+
+# Script to get full timeline for diagnostics
+GET_TIMELINE_SCRIPT = """
+if (window.__waitless__) {
+    return {
+        timeline: window.__waitless__.timeline,
+        pending_request_details: window.__waitless__.pendingRequestDetails
+    };
+}
+return null;
+"""
+
+# Script to update configuration
+UPDATE_CONFIG_SCRIPT = """
+if (window.__waitless__) {
+    window.__waitless__.config = Object.assign(window.__waitless__.config, arguments[0]);
+    return true;
+}
+return false;
+"""

waitless/selenium_integration.py

@@ -0,0 +1,296 @@
+"""
+Selenium WebDriver integration layer.
+
+Provides transparent stabilization for Selenium interactions through
+the wrapper pattern (safer than monkey-patching).
+
+Note: Wrapped elements behave like WebElements but are not identical.
+This may affect equality checks or isinstance() calls in test code.
+"""
+
+import functools
+import logging
+from typing import Optional, Any, List, Dict, TYPE_CHECKING
+from weakref import WeakValueDictionary
+
+from .config import StabilizationConfig, DEFAULT_CONFIG
+from .engine import StabilizationEngine
+
+
+if TYPE_CHECKING:
+    from selenium.webdriver.remote.webdriver import WebDriver
+    from selenium.webdriver.remote.webelement import WebElement
+
+
+logger = logging.getLogger('waitless')
+
+
+_stabilized_drivers: WeakValueDictionary = WeakValueDictionary()
+
+
+class StabilizedWebElement:
+    """
+    Wrapper around WebElement that auto-waits for stability before interactions.
+    
+    This wrapper:
+    - Intercepts click(), send_keys(), submit(), clear() to wait for stability
+    - Delegates all other attributes/methods to the underlying element
+    - Preserves the original element for direct access if needed
+    
+    IMPORTANT: This wrapper is NOT a WebElement subclass.
+    - isinstance(wrapped, WebElement) will return False
+    - Equality checks may behave unexpectedly
+    - Use .unwrap() to get the original element if needed
+    """
+    
+    INTERACTION_METHODS = {'click', 'send_keys', 'submit', 'clear'}
+    
+    def __init__(self, element: 'WebElement', engine: StabilizationEngine):
+        self._element = element
+        self._engine = engine
+    
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the underlying element."""
+        attr = getattr(self._element, name)
+        if name in self.INTERACTION_METHODS and callable(attr):
+            return self._create_stabilized_method(attr, name)
+        
+        return attr
+    
+    def _create_stabilized_method(self, method: callable, name: str) -> callable:
+        """Create a wrapper that stabilizes before calling the method."""
+        @functools.wraps(method)
+        def stabilized_method(*args, **kwargs):
+            if self._engine.config.debug_mode:
+                logger.debug(f"[waitless] Stabilizing before {name}()")
+            
+            self._engine.wait_for_stability()
+            return method(*args, **kwargs)
+        
+        return stabilized_method
+    
+    @property
+    def wrapped_element(self) -> 'WebElement':
+        """Access the underlying WebElement directly."""
+        return self._element
+    
+    def unwrap(self) -> 'WebElement':
+        """Get the original WebElement (alias for wrapped_element)."""
+        return self._element
+    
+    def __repr__(self) -> str:
+        return f"<StabilizedWebElement wrapping {self._element}>"
+    
+    def __eq__(self, other: Any) -> bool:
+        """Compare underlying elements for equality."""
+        if isinstance(other, StabilizedWebElement):
+            return self._element == other._element
+        return self._element == other
+    
+    def __hash__(self) -> int:
+        return hash(self._element)
+
+
+class StabilizedWebDriver:
+    """
+    Wrapper around WebDriver that returns stabilized elements.
+    
+    This wrapper:
+    - Wraps find_element/find_elements to return StabilizedWebElement
+    - Triggers stabilization before get() navigation
+    - Preserves all other WebDriver functionality
+    """
+    
+    def __init__(self, driver: 'WebDriver', engine: StabilizationEngine):
+        self._driver = driver
+        self._engine = engine
+    
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the underlying driver."""
+        attr = getattr(self._driver, name)
+        if name == 'find_element':
+            return self._stabilized_find_element
+        elif name == 'find_elements':
+            return self._stabilized_find_elements
+        
+        return attr
+    
+    def _stabilized_find_element(self, *args, **kwargs) -> StabilizedWebElement:
+        """Find element and wrap it for stabilization."""
+        element = self._driver.find_element(*args, **kwargs)
+        return StabilizedWebElement(element, self._engine)
+    
+    def _stabilized_find_elements(self, *args, **kwargs) -> List[StabilizedWebElement]:
+        """Find elements and wrap them for stabilization."""
+        elements = self._driver.find_elements(*args, **kwargs)
+        return [StabilizedWebElement(el, self._engine) for el in elements]
+    
+    @property
+    def unwrapped(self) -> 'WebDriver':
+        """Access the underlying WebDriver directly."""
+        return self._driver
+    
+    def wait_for_stability(self, timeout: Optional[float] = None):
+        """Manually trigger stabilization."""
+        return self._engine.wait_for_stability(timeout)
+    
+    def __repr__(self) -> str:
+        return f"<StabilizedWebDriver wrapping {self._driver}>"
+
+
+class SeleniumIntegration:
+    """
+    Main integration class for Selenium.
+    
+    Provides the stabilize() and unstabilize() functions.
+    """
+    
+    def __init__(self):
+        self._engines: Dict[int, StabilizationEngine] = {}
+        self._original_drivers: Dict[int, 'WebDriver'] = {}
+        self._wrapped_drivers: Dict[int, StabilizedWebDriver] = {}
+    
+    def stabilize(
+        self,
+        driver: 'WebDriver',
+        config: Optional[StabilizationConfig] = None
+    ) -> StabilizedWebDriver:
+        """
+        Enable automatic stabilization for a WebDriver.
+        
+        Args:
+            driver: Selenium WebDriver instance
+            config: Optional configuration overrides
+            
+        Returns:
+            StabilizedWebDriver that auto-waits before interactions
+            
+        Note:
+            The returned driver wraps the original but is not a true WebDriver.
+            If you need the original for framework integration, use .unwrapped
+        """
+        driver_id = id(driver)
+        
+        if driver_id in self._wrapped_drivers:
+            existing = self._wrapped_drivers[driver_id]
+            if config:
+                existing._engine.config = config
+            return existing
+        
+        effective_config = config or DEFAULT_CONFIG
+        engine = StabilizationEngine(driver, effective_config)
+        wrapped = StabilizedWebDriver(driver, engine)
+        
+        self._engines[driver_id] = engine
+        self._original_drivers[driver_id] = driver
+        self._wrapped_drivers[driver_id] = wrapped
+        
+        if effective_config.debug_mode:
+            logger.info(f"[waitless] Stabilization enabled for driver {driver_id}")
+        
+        return wrapped
+    
+    def unstabilize(self, driver: 'WebDriver') -> 'WebDriver':
+        """
+        Disable stabilization and return the original driver.
+        
+        Args:
+            driver: Either the original driver or a StabilizedWebDriver
+            
+        Returns:
+            The original unwrapped WebDriver
+        """
+        if isinstance(driver, StabilizedWebDriver):
+            original = driver.unwrapped
+            driver_id = id(original)
+        else:
+            original = driver
+            driver_id = id(driver)
+        
+        self._engines.pop(driver_id, None)
+        self._original_drivers.pop(driver_id, None)
+        self._wrapped_drivers.pop(driver_id, None)
+        
+        logger.info(f"[waitless] Stabilization disabled for driver {driver_id}")
+        
+        return original
+    
+    def get_engine(self, driver: 'WebDriver') -> Optional[StabilizationEngine]:
+        """Get the engine for a driver (for diagnostics)."""
+        if isinstance(driver, StabilizedWebDriver):
+            return driver._engine
+        return self._engines.get(id(driver))
+    
+    def is_stabilized(self, driver: 'WebDriver') -> bool:
+        """Check if a driver is currently stabilized."""
+        if isinstance(driver, StabilizedWebDriver):
+            return True
+        return id(driver) in self._wrapped_drivers
+
+
+_integration = SeleniumIntegration()
+
+
+def stabilize(
+    driver: 'WebDriver',
+    config: Optional[StabilizationConfig] = None
+) -> StabilizedWebDriver:
+    """
+    Enable automatic stabilization for a WebDriver.
+    
+    This is the main entry point for waitless.
+    
+    Example:
+        from waitless import stabilize
+        
+        driver = webdriver.Chrome()
+        driver = stabilize(driver)  # Now auto-waits!
+        
+        driver.find_element(By.ID, "button").click()  # Auto-stabilizes
+    
+    Args:
+        driver: Selenium WebDriver instance
+        config: Optional StabilizationConfig for customization
+        
+    Returns:
+        StabilizedWebDriver that auto-waits before interactions
+    """
+    return _integration.stabilize(driver, config)
+
+
+def unstabilize(driver: 'WebDriver') -> 'WebDriver':
+    """
+    Disable stabilization and return the original driver.
+    
+    Example:
+        driver = unstabilize(driver)  # Back to normal
+    """
+    return _integration.unstabilize(driver)
+
+
+def wait_for_stability(
+    driver: 'WebDriver',
+    timeout: Optional[float] = None
+) -> None:
+    """
+    Manually wait for UI stability.
+    
+    Use this for explicit stabilization without wrapping interactions.
+    
+    Example:
+        wait_for_stability(driver)
+        driver.find_element(By.ID, "button").click()
+    """
+    if isinstance(driver, StabilizedWebDriver):
+        driver.wait_for_stability(timeout)
+    else:
+        engine = StabilizationEngine(driver)
+        engine.wait_for_stability(timeout)
+
+
+def get_diagnostics(driver: 'WebDriver') -> Optional[Dict[str, Any]]:
+    """Get diagnostic information for a stabilized driver."""
+    engine = _integration.get_engine(driver)
+    if engine:
+        return engine.get_diagnostics()
+    return None