waitless 0.1.0__tar.gz → 0.2.0__tar.gz

waitless-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{waitless-0.1.0 → waitless-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waitless
-Version: 0.1.0
+Version: 0.2.0
 Summary: Eliminate explicit waits in UI automation by detecting true UI stability
 Author-email: Dhiraj Das <dhirajdas.66@gmail.com>
 License: MIT
@@ -22,9 +22,11 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: selenium>=4.0; extra == "dev"
+Dynamic: license-file
 
 # Waitless
 
@@ -93,12 +95,12 @@ When you interact, waitless ensures the page is truly ready.
 from waitless import stabilize, StabilizationConfig
 
 config = StabilizationConfig(
-    timeout=5,                    # Max wait time (seconds)
-    dom_settle_time=0.1,          # DOM quiet period needed
-    network_idle_threshold=0,     # Max pending requests (0 = all must complete)
-    animation_detection=True,     # Wait for animations to finish
-    strictness='normal',          # 'strict' | 'normal' | 'relaxed'
-    debug_mode=True               # Enable logging
+    timeout=10,                    # Max wait time (seconds)
+    mutation_rate_threshold=50,    # mutations/sec considered stable (allows animations)
+    network_idle_threshold=2,      # Max pending requests (allows background traffic)
+    animation_detection=True,      # Track CSS animations (non-blocking in normal mode)
+    strictness='normal',           # 'strict' | 'normal' | 'relaxed'
+    debug_mode=True                # Enable logging
 )
 
 driver = stabilize(driver, config=config)

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

@@ -65,12 +65,12 @@ When you interact, waitless ensures the page is truly ready.
 from waitless import stabilize, StabilizationConfig
 
 config = StabilizationConfig(
-    timeout=5,                    # Max wait time (seconds)
-    dom_settle_time=0.1,          # DOM quiet period needed
-    network_idle_threshold=0,     # Max pending requests (0 = all must complete)
-    animation_detection=True,     # Wait for animations to finish
-    strictness='normal',          # 'strict' | 'normal' | 'relaxed'
-    debug_mode=True               # Enable logging
+    timeout=10,                    # Max wait time (seconds)
+    mutation_rate_threshold=50,    # mutations/sec considered stable (allows animations)
+    network_idle_threshold=2,      # Max pending requests (allows background traffic)
+    animation_detection=True,      # Track CSS animations (non-blocking in normal mode)
+    strictness='normal',           # 'strict' | 'normal' | 'relaxed'
+    debug_mode=True                # Enable logging
 )
 
 driver = stabilize(driver, config=config)

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "waitless"
-version = "0.1.0"
+version = "0.2.0"
 description = "Eliminate explicit waits in UI automation by detecting true UI stability"
 readme = "README.md"
 license = {text = "MIT"}

{waitless-0.1.0 → waitless-0.2.0}/waitless/config.py

@@ -22,18 +22,16 @@ class StabilizationConfig:
                  Consider lowering to 5s for faster feedback loops.
         
         dom_settle_time: Time (seconds) DOM must be quiet to be considered stable.
-                         Default 0.1s (100ms).
+                         Default 0.1s (100ms). This is a FALLBACK - mutation rate
+                         is the primary check for DOM stability.
+        
+        mutation_rate_threshold: Maximum mutations per second for DOM to be stable.
+                                 Default 50/sec. This allows animated sites (typewriter
+                                 effects ~30/sec) while catching loading bursts (100+/sec).
         
         network_idle_threshold: Maximum pending requests allowed for stability.
-                                Default 0 (all requests must complete).
-                                
-                                ⚠️ WARNING: Many apps have background traffic:
-                                - Analytics calls
-                                - Long polling  
-                                - Feature flags
-                                - WebSocket heartbeats
-                                
-                                If your tests timeout frequently, try setting this to 1-2.
+                                Default 2 (allows background analytics/polling).
+                                Set to 0 for strict mode if all requests must complete.
         
         animation_detection: Whether to wait for CSS animations/transitions.
                              Default True. Disable for apps with infinite animations.
@@ -42,9 +40,9 @@ class StabilizationConfig:
                           Default True in 'strict' mode.
         
         strictness: Overall strictness level.
-                    - 'strict': All signals must be stable (recommended)
-                    - 'normal': DOM + Network only (faster)
-                    - 'relaxed': DOM only (fastest, least reliable)
+                    - 'strict': All signals must be stable (recommended for CI)
+                    - 'normal': DOM + Network only (default)
+                    - 'relaxed': DOM only (fastest)
         
         debug_mode: Enable verbose logging for troubleshooting.
                     Default False.
@@ -58,7 +56,8 @@ class StabilizationConfig:
     
     timeout: float = 10.0
     dom_settle_time: float = 0.1
-    network_idle_threshold: int = 0
+    mutation_rate_threshold: float = 50.0  # mutations/sec - allows animations
+    network_idle_threshold: int = 2  # Allow background traffic
     animation_detection: bool = True
     layout_stability: bool = True
     strictness: StrictnessLevel = 'normal'
@@ -118,6 +117,7 @@ class StabilizationConfig:
         current = {
             'timeout': self.timeout,
             'dom_settle_time': self.dom_settle_time,
+            'mutation_rate_threshold': self.mutation_rate_threshold,
             'network_idle_threshold': self.network_idle_threshold,
             'animation_detection': self.animation_detection,
             'layout_stability': self.layout_stability,

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

@@ -53,6 +53,7 @@ class StabilizationEngine:
         
 
         self._last_status: Optional[StabilityStatus] = None
+        self._last_browser_state: Optional[Dict[str, Any]] = None
         self._last_blocking_factors: Dict[str, Any] = {}
         self._timeline: list = []
         
@@ -175,6 +176,7 @@ class StabilizationEngine:
             status = self.evaluator.evaluate(browser_state, current_time)
             last_status = status
             self._last_status = status
+            self._last_browser_state = browser_state  # Store for diagnostics
             
             if status.is_stable:
                 self._debug(f"UI stable after {elapsed:.2f}s")
@@ -260,7 +262,7 @@ class StabilizationEngine:
                 'network_idle_threshold': self.config.network_idle_threshold,
                 'animation_detection': self.config.animation_detection,
             },
-            'last_status': self._last_status.to_dict() if self._last_status else None,
+            'last_status': self._last_browser_state,  # Raw browser state with mutation_rate, etc.
             'blocking_factors': self._last_blocking_factors,
             'timeline': self._timeline[-50:],
             'instrumented': self._instrumented,

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

@@ -68,11 +68,26 @@ INSTRUMENTATION_SCRIPT = """
         
         // ===== MUTATION OBSERVER =====
         
+        // Rolling window for mutation rate calculation
+        _mutationTimestamps: [],
+        _mutationWindowMs: 1000,  // 1 second window for rate calculation
+        
         _setupMutationObserver: function() {
             var self = this;
             var observer = new MutationObserver(function(mutations) {
-                self.lastMutationTime = Date.now();
-                self._log('DOM mutation', { count: mutations.length });
+                var now = Date.now();
+                self.lastMutationTime = now;
+                
+                // Add to rolling window
+                self._mutationTimestamps.push(now);
+                
+                // Remove old timestamps outside the window
+                var cutoff = now - self._mutationWindowMs;
+                while (self._mutationTimestamps.length > 0 && self._mutationTimestamps[0] < cutoff) {
+                    self._mutationTimestamps.shift();
+                }
+                
+                self._log('DOM mutation', { count: mutations.length, rate: self.getMutationRate() });
             });
             
             observer.observe(document.documentElement || document.body, {
@@ -85,6 +100,23 @@ INSTRUMENTATION_SCRIPT = """
             this._observers.push(observer);
         },
         
+        // Calculate mutations per second from rolling window
+        getMutationRate: function() {
+            var now = Date.now();
+            var cutoff = now - this._mutationWindowMs;
+            
+            // Count mutations in the last second
+            var count = 0;
+            for (var i = 0; i < this._mutationTimestamps.length; i++) {
+                if (this._mutationTimestamps[i] > cutoff) {
+                    count++;
+                }
+            }
+            
+            // Return rate per second
+            return count;
+        },
+        
         // ===== NETWORK INTERCEPTORS =====
         
         _setupNetworkInterceptors: function() {
@@ -246,6 +278,7 @@ INSTRUMENTATION_SCRIPT = """
                 stable: this.isStable(),
                 pending_requests: this.pendingRequests,
                 last_mutation_time: this.lastMutationTime,
+                mutation_rate: this.getMutationRate(),  // mutations per second
                 active_animations: this.activeAnimations + this.activeTransitions,
                 layout_shifting: this.layoutShifting,
                 pending_request_details: this.pendingRequestDetails.slice(),

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

@@ -116,14 +116,74 @@ class StabilizedWebDriver:
         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)
+        """
+        Find element with automatic waiting.
+        
+        This method:
+        1. Waits for page stability first
+        2. Tries to find the element
+        3. If element not found, retries until timeout
+        
+        This eliminates the need for explicit WebDriverWait in test code.
+        """
+        import time
+        from selenium.common.exceptions import NoSuchElementException
+        
+        timeout = self._engine.config.timeout
+        poll_interval = self._engine.config.poll_interval
+        start_time = time.time()
+        last_exception = None
+        
+        while (time.time() - start_time) < timeout:
+            # Wait for page stability first
+            try:
+                self._engine.wait_for_stability()
+            except Exception:
+                pass  # Continue trying to find element
+            
+            # Try to find the element
+            try:
+                element = self._driver.find_element(*args, **kwargs)
+                return StabilizedWebElement(element, self._engine)
+            except NoSuchElementException as e:
+                last_exception = e
+                # Element not found - wait and retry
+                time.sleep(poll_interval)
+        
+        # Timeout reached - raise the last exception
+        if last_exception:
+            raise last_exception
+        raise NoSuchElementException(f"Element not found within {timeout}s: {args}")
     
     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]
+        """
+        Find elements with automatic waiting.
+        
+        Similar to find_element but returns list (may be empty).
+        """
+        import time
+        
+        timeout = self._engine.config.timeout
+        poll_interval = self._engine.config.poll_interval
+        start_time = time.time()
+        
+        while (time.time() - start_time) < timeout:
+            # Wait for stability first
+            try:
+                self._engine.wait_for_stability()
+            except Exception:
+                pass
+            
+            # Try to find elements
+            elements = self._driver.find_elements(*args, **kwargs)
+            if elements:
+                return [StabilizedWebElement(el, self._engine) for el in elements]
+            
+            # No elements found - wait and retry
+            time.sleep(poll_interval)
+        
+        # Return empty list if nothing found
+        return []
     
     @property
     def unwrapped(self) -> 'WebDriver':

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

@@ -154,11 +154,34 @@ class SignalEvaluator:
         )
     
     def _evaluate_dom(self, state: Dict[str, Any], current_time: float) -> Signal:
-        """Evaluate DOM mutation activity."""
+        """
+        Evaluate DOM mutation activity using MUTATION RATE.
+        
+        Key insight: Animated sites have steady ~30-50 mutations/sec (typewriter, particles).
+        Loading bursts have 100+ mutations/sec. We consider stable when rate is LOW, not zero.
+        
+        Primary check: mutation_rate <= threshold (50/sec default)
+        Fallback: time since last mutation (for older browsers)
+        """
+        mutation_rate = state.get('mutation_rate')
         last_mutation = state.get('last_mutation_time', 0)
-        time_since_mutation = (current_time * 1000) - last_mutation  # Convert to ms
-        threshold_ms = self.config.dom_settle_time * 1000
         
+        # Primary: Use mutation rate if available
+        if mutation_rate is not None:
+            threshold = self.config.mutation_rate_threshold
+            is_stable = mutation_rate <= threshold
+            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)",
+            )
+        
+        # Fallback: Use time since last mutation
+        time_since_mutation = (current_time * 1000) - last_mutation
+        threshold_ms = self.config.dom_settle_time * 1000
         is_stable = time_since_mutation >= threshold_ms
         
         return Signal(
@@ -187,9 +210,15 @@ class SignalEvaluator:
         )
     
     def _evaluate_animations(self, state: Dict[str, Any]) -> Signal:
-        """Evaluate CSS animation/transition activity."""
+        """
+        Evaluate CSS animation/transition activity.
+        
+        Only mandatory in 'strict' mode. In 'normal' and 'relaxed' modes,
+        animations are cosmetic and don't block interaction.
+        """
         active = state.get('active_animations', 0)
-        is_mandatory = self.config.strictness != 'relaxed'
+        # Only mandatory in strict mode - animations are usually cosmetic
+        is_mandatory = self.config.strictness == 'strict'
         is_stable = active == 0
         
         return Signal(

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waitless
-Version: 0.1.0
+Version: 0.2.0
 Summary: Eliminate explicit waits in UI automation by detecting true UI stability
 Author-email: Dhiraj Das <dhirajdas.66@gmail.com>
 License: MIT
@@ -22,9 +22,11 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: selenium>=4.0; extra == "dev"
+Dynamic: license-file
 
 # Waitless
 
@@ -93,12 +95,12 @@ When you interact, waitless ensures the page is truly ready.
 from waitless import stabilize, StabilizationConfig
 
 config = StabilizationConfig(
-    timeout=5,                    # Max wait time (seconds)
-    dom_settle_time=0.1,          # DOM quiet period needed
-    network_idle_threshold=0,     # Max pending requests (0 = all must complete)
-    animation_detection=True,     # Wait for animations to finish
-    strictness='normal',          # 'strict' | 'normal' | 'relaxed'
-    debug_mode=True               # Enable logging
+    timeout=10,                    # Max wait time (seconds)
+    mutation_rate_threshold=50,    # mutations/sec considered stable (allows animations)
+    network_idle_threshold=2,      # Max pending requests (allows background traffic)
+    animation_detection=True,      # Track CSS animations (non-blocking in normal mode)
+    strictness='normal',           # 'strict' | 'normal' | 'relaxed'
+    debug_mode=True                # Enable logging
 )
 
 driver = stabilize(driver, config=config)

{waitless-0.1.0 → waitless-0.2.0}/waitless.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+LICENSE
 README.md
 pyproject.toml
 waitless/__init__.py