waitless 0.2.0__tar.gz → 0.3.1__tar.gz

{waitless-0.2.0 → waitless-0.3.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Dhiraj Das
+Copyright (c) 2025 Dhiraj Das
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{waitless-0.2.0/waitless.egg-info → waitless-0.3.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: waitless
-Version: 0.2.0
+Version: 0.3.1
 Summary: Eliminate explicit waits in UI automation by detecting true UI stability
-Author-email: Dhiraj Das <dhirajdas.66@gmail.com>
+Author-email: Dhiraj Das <dhirajdas.666@gmail.com>
 License: MIT
-Project-URL: Homepage, https://github.com/godhiraj-code/waitless
+Project-URL: Homepage, https://www.dhirajdas.dev
 Project-URL: Documentation, https://github.com/godhiraj-code/waitless#readme
 Project-URL: Repository, https://github.com/godhiraj-code/waitless.git
 Project-URL: Issues, https://github.com/godhiraj-code/waitless/issues
@@ -30,6 +30,8 @@ Dynamic: license-file
 
 # Waitless
 
+[![CI](https://github.com/godhiraj-code/waitless/actions/workflows/ci.yml/badge.svg)](https://github.com/godhiraj-code/waitless/actions/workflows/ci.yml)
+
 **Zero-wait UI automation stabilization for Selenium**
 
 Eliminate explicit waits and sleeps by automatically detecting true UI stability.
@@ -82,7 +84,7 @@ Automation tests fail because interactions happen while the UI is still changing
 
 Waitless monitors the **entire page** for stability signals:
 
-- ✅ DOM mutation activity (MutationObserver)
+- ✅ DOM mutation activity (MutationObserver, including **Shadow DOM**)
 - ✅ Pending network requests (XHR/fetch interception)
 - ✅ CSS animations and transitions
 - ✅ Layout stability (element movement)
@@ -187,7 +189,7 @@ Sample output:
 
 ### Network Threshold Warning
 
-The default `network_idle_threshold=0` means **all** network requests must complete.
+The default `network_idle_threshold=2` allows some background traffic.
 
 Many apps have background traffic that never stops:
 - Analytics calls
@@ -212,14 +214,15 @@ element = driver.find_element(By.ID, "button")
 original = element.unwrap()  # Gets the real WebElement
 ```
 
-## v0 Limitations
+## v0.3 Limitations
 
 - **Selenium only** - Playwright support planned for v1
 - **Sync only** - No async/await support yet
 - **Main frame only** - iframes not monitored
-- **No Shadow DOM** - MutationObserver doesn't see shadow roots
 - **No Service Workers** - SW network requests not intercepted
 
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
 ## API Reference
 
 ### Functions

{waitless-0.2.0 → waitless-0.3.1}/README.md

@@ -1,5 +1,7 @@
 # Waitless
 
+[![CI](https://github.com/godhiraj-code/waitless/actions/workflows/ci.yml/badge.svg)](https://github.com/godhiraj-code/waitless/actions/workflows/ci.yml)
+
 **Zero-wait UI automation stabilization for Selenium**
 
 Eliminate explicit waits and sleeps by automatically detecting true UI stability.
@@ -52,7 +54,7 @@ Automation tests fail because interactions happen while the UI is still changing
 
 Waitless monitors the **entire page** for stability signals:
 
-- ✅ DOM mutation activity (MutationObserver)
+- ✅ DOM mutation activity (MutationObserver, including **Shadow DOM**)
 - ✅ Pending network requests (XHR/fetch interception)
 - ✅ CSS animations and transitions
 - ✅ Layout stability (element movement)
@@ -157,7 +159,7 @@ Sample output:
 
 ### Network Threshold Warning
 
-The default `network_idle_threshold=0` means **all** network requests must complete.
+The default `network_idle_threshold=2` allows some background traffic.
 
 Many apps have background traffic that never stops:
 - Analytics calls
@@ -182,14 +184,15 @@ element = driver.find_element(By.ID, "button")
 original = element.unwrap()  # Gets the real WebElement
 ```
 
-## v0 Limitations
+## v0.3 Limitations
 
 - **Selenium only** - Playwright support planned for v1
 - **Sync only** - No async/await support yet
 - **Main frame only** - iframes not monitored
-- **No Shadow DOM** - MutationObserver doesn't see shadow roots
 - **No Service Workers** - SW network requests not intercepted
 
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
 ## API Reference
 
 ### Functions

{waitless-0.2.0 → waitless-0.3.1}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "waitless"
-version = "0.2.0"
+version = "0.3.1"
 description = "Eliminate explicit waits in UI automation by detecting true UI stability"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.9"
 authors = [
-    {name = "Dhiraj Das", email = "dhirajdas.66@gmail.com"}
+    {name = "Dhiraj Das", email = "dhirajdas.666@gmail.com"}
 ]
 keywords = [
     "selenium",
@@ -36,7 +36,7 @@ classifiers = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/godhiraj-code/waitless"
+Homepage = "https://www.dhirajdas.dev"
 Documentation = "https://github.com/godhiraj-code/waitless#readme"
 Repository = "https://github.com/godhiraj-code/waitless.git"
 Issues = "https://github.com/godhiraj-code/waitless/issues"

{waitless-0.2.0 → waitless-0.3.1}/waitless/__init__.py

@@ -36,7 +36,7 @@ Disable:
     driver = unstabilize(driver)  # Back to original behavior
 """
 
-__version__ = '0.1.0'
+__version__ = '0.3.1'
 __author__ = 'Dhiraj Das'
 
 # Public API

{waitless-0.2.0 → waitless-0.3.1}/waitless/engine.py

@@ -10,6 +10,21 @@ import threading
 import logging
 from typing import Optional, Dict, Any, TYPE_CHECKING
 
+# Import Selenium exceptions for specific error handling
+try:
+    from selenium.common.exceptions import (
+        WebDriverException,
+        JavascriptException,
+        NoSuchWindowException,
+    )
+    SELENIUM_AVAILABLE = True
+except ImportError:
+    # Fallback for when selenium is not installed
+    WebDriverException = Exception
+    JavascriptException = Exception
+    NoSuchWindowException = Exception
+    SELENIUM_AVAILABLE = False
+
 from .config import StabilizationConfig, DEFAULT_CONFIG
 from .signals import SignalEvaluator, StabilityStatus
 from .instrumentation import (
@@ -86,7 +101,8 @@ class StabilizationEngine:
         """Get current page URL safely."""
         try:
             return self.driver.current_url
-        except Exception:
+        except (WebDriverException, NoSuchWindowException) as e:
+            self._debug(f"Could not get current URL: {e}")
             return ""
     
     def _is_instrumentation_alive(self) -> bool:
@@ -99,7 +115,8 @@ class StabilizationEngine:
         try:
             result = self.driver.execute_script(CHECK_ALIVE_SCRIPT)
             return result is True
-        except Exception:
+        except (JavascriptException, WebDriverException, NoSuchWindowException) as e:
+            self._debug(f"Instrumentation check failed: {e}")
             return False
     
     def _inject_instrumentation(self) -> None:

{waitless-0.2.0 → waitless-0.3.1}/waitless/instrumentation.py

@@ -71,6 +71,7 @@ INSTRUMENTATION_SCRIPT = """
         // Rolling window for mutation rate calculation
         _mutationTimestamps: [],
         _mutationWindowMs: 1000,  // 1 second window for rate calculation
+        _observedShadowRoots: new WeakSet(),
         
         _setupMutationObserver: function() {
             var self = this;
@@ -87,17 +88,77 @@ INSTRUMENTATION_SCRIPT = """
                     self._mutationTimestamps.shift();
                 }
                 
+                // Check for new shadow roots in added nodes
+                mutations.forEach(function(mutation) {
+                    mutation.addedNodes.forEach(function(node) {
+                        if (node.nodeType === 1) { // Element node
+                            self._observeShadowRoots(node);
+                        }
+                    });
+                });
+                
                 self._log('DOM mutation', { count: mutations.length, rate: self.getMutationRate() });
             });
             
-            observer.observe(document.documentElement || document.body, {
+            var config = {
                 childList: true,
                 subtree: true,
                 attributes: true,
                 characterData: true
-            });
+            };
             
+            observer.observe(document.documentElement || document.body, config);
             this._observers.push(observer);
+            
+            // Initial scan for shadow roots
+            this._observeShadowRoots(document);
+        },
+        
+        _observeShadowRoots: function(root) {
+            var self = this;
+            
+            // Function to recursively find and observe shadow roots
+            var walk = function(node) {
+                if (node.shadowRoot && !self._observedShadowRoots.has(node.shadowRoot)) {
+                    self._observedShadowRoots.add(node.shadowRoot);
+                    
+                    var observer = new MutationObserver(function(mutations) {
+                        var now = Date.now();
+                        self.lastMutationTime = now;
+                        self._mutationTimestamps.push(now);
+                        self._log('Shadow DOM mutation', { count: mutations.length });
+                        
+                        // Scan new nodes in shadow DOM for nested shadow roots
+                        mutations.forEach(function(mutation) {
+                            mutation.addedNodes.forEach(function(newNode) {
+                                if (newNode.nodeType === 1) walk(newNode);
+                            });
+                        });
+                    });
+                    
+                    observer.observe(node.shadowRoot, {
+                        childList: true,
+                        subtree: true,
+                        attributes: true,
+                        characterData: true
+                    });
+                    
+                    self._observers.push(observer);
+                    self._log('Observing shadow root', { host: node.tagName });
+                    
+                    // Recurse into the shadow root
+                    walk(node.shadowRoot);
+                }
+                
+                // Traverse children
+                var child = node.firstElementChild;
+                while (child) {
+                    walk(child);
+                    child = child.nextElementSibling;
+                }
+            };
+            
+            walk(root);
         },
         
         // Calculate mutations per second from rolling window
@@ -239,8 +300,26 @@ INSTRUMENTATION_SCRIPT = """
         },
         
         _checkLayoutStability: function() {
-            // Track key interactive elements
-            var elements = document.querySelectorAll('button, a, input, [onclick], [role="button"]');
+            // Track key interactive elements, including those in shadow DOM
+            var elements = [];
+            
+            var collectElements = function(root) {
+                var found = root.querySelectorAll('button, a, input, [onclick], [role="button"]');
+                for (var i = 0; i < found.length; i++) {
+                    elements.push(found[i]);
+                }
+                
+                // Recursively check shadow roots
+                var all = root.querySelectorAll('*');
+                for (var j = 0; j < all.length; j++) {
+                    if (all[j].shadowRoot) {
+                        collectElements(all[j].shadowRoot);
+                    }
+                }
+            };
+            
+            collectElements(document);
+            
             var isShifting = false;
             var self = this;
             

{waitless-0.2.0 → waitless-0.3.1}/waitless/selenium_integration.py

@@ -225,10 +225,25 @@ class SeleniumIntegration:
         Returns:
             StabilizedWebDriver that auto-waits before interactions
             
+        Raises:
+            TypeError: If driver is not a valid WebDriver instance
+            
         Note:
             The returned driver wraps the original but is not a true WebDriver.
             If you need the original for framework integration, use .unwrapped
         """
+        # Validate driver is a WebDriver-like object
+        if driver is None:
+            raise TypeError("driver cannot be None")
+        
+        required_attrs = ['execute_script', 'find_element', 'current_url']
+        missing = [attr for attr in required_attrs if not hasattr(driver, attr)]
+        if missing:
+            raise TypeError(
+                f"driver does not appear to be a valid WebDriver. "
+                f"Missing required attributes: {missing}"
+            )
+        
         driver_id = id(driver)
         
         if driver_id in self._wrapped_drivers:

{waitless-0.2.0 → waitless-0.3.1}/waitless/signals.py

@@ -169,14 +169,26 @@ class SignalEvaluator:
         # Primary: Use mutation rate if available
         if mutation_rate is not None:
             threshold = self.config.mutation_rate_threshold
-            is_stable = mutation_rate <= threshold
+            rate_stable = mutation_rate <= threshold
+            
+            # Also check settle time to ensure we are quiet AFTER a mutation
+            time_since_mutation = (current_time * 1000) - last_mutation
+            threshold_ms = self.config.dom_settle_time * 1000
+            settle_stable = time_since_mutation >= threshold_ms
+            
+            is_stable = rate_stable and settle_stable
+            
+            details = f"Mutation rate: {mutation_rate:.0f}/sec (threshold: {threshold:.0f}/sec)"
+            if not settle_stable:
+                details += f", but only {time_since_mutation:.0f}ms since last mutation (need {threshold_ms:.0f}ms)"
+                
             return Signal(
                 signal_type=SignalType.DOM_MUTATIONS,
                 state=SignalState.STABLE if is_stable else SignalState.UNSTABLE,
                 value=mutation_rate,
                 threshold=threshold,
                 is_mandatory=True,
-                details=f"Mutation rate: {mutation_rate:.0f}/sec (threshold: {threshold:.0f}/sec)",
+                details=details,
             )
         
         # Fallback: Use time since last mutation

{waitless-0.2.0 → waitless-0.3.1/waitless.egg-info}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: waitless
-Version: 0.2.0
+Version: 0.3.1
 Summary: Eliminate explicit waits in UI automation by detecting true UI stability
-Author-email: Dhiraj Das <dhirajdas.66@gmail.com>
+Author-email: Dhiraj Das <dhirajdas.666@gmail.com>
 License: MIT
-Project-URL: Homepage, https://github.com/godhiraj-code/waitless
+Project-URL: Homepage, https://www.dhirajdas.dev
 Project-URL: Documentation, https://github.com/godhiraj-code/waitless#readme
 Project-URL: Repository, https://github.com/godhiraj-code/waitless.git
 Project-URL: Issues, https://github.com/godhiraj-code/waitless/issues
@@ -30,6 +30,8 @@ Dynamic: license-file
 
 # Waitless
 
+[![CI](https://github.com/godhiraj-code/waitless/actions/workflows/ci.yml/badge.svg)](https://github.com/godhiraj-code/waitless/actions/workflows/ci.yml)
+
 **Zero-wait UI automation stabilization for Selenium**
 
 Eliminate explicit waits and sleeps by automatically detecting true UI stability.
@@ -82,7 +84,7 @@ Automation tests fail because interactions happen while the UI is still changing
 
 Waitless monitors the **entire page** for stability signals:
 
-- ✅ DOM mutation activity (MutationObserver)
+- ✅ DOM mutation activity (MutationObserver, including **Shadow DOM**)
 - ✅ Pending network requests (XHR/fetch interception)
 - ✅ CSS animations and transitions
 - ✅ Layout stability (element movement)
@@ -187,7 +189,7 @@ Sample output:
 
 ### Network Threshold Warning
 
-The default `network_idle_threshold=0` means **all** network requests must complete.
+The default `network_idle_threshold=2` allows some background traffic.
 
 Many apps have background traffic that never stops:
 - Analytics calls
@@ -212,14 +214,15 @@ element = driver.find_element(By.ID, "button")
 original = element.unwrap()  # Gets the real WebElement
 ```
 
-## v0 Limitations
+## v0.3 Limitations
 
 - **Selenium only** - Playwright support planned for v1
 - **Sync only** - No async/await support yet
 - **Main frame only** - iframes not monitored
-- **No Shadow DOM** - MutationObserver doesn't see shadow roots
 - **No Service Workers** - SW network requests not intercepted
 
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
 ## API Reference
 
 ### Functions