waitless 0.3.2__tar.gz → 1.0.1__tar.gz

{waitless-0.3.2/waitless.egg-info → waitless-1.0.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: waitless
-Version: 0.3.2
+Version: 1.0.1
 Summary: Eliminate explicit waits in UI automation by detecting true UI stability
 Author-email: Dhiraj Das <dhirajdas.666@gmail.com>
-License: MIT
+License-Expression: MIT
 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
@@ -11,7 +11,6 @@ Project-URL: Issues, https://github.com/godhiraj-code/waitless/issues
 Keywords: selenium,automation,testing,ui-testing,wait,stability,flaky-tests
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -23,18 +22,21 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: selenium>=4.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: selenium>=4.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
 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**
+**Automatic UI stabilization for Selenium**
+
+Reduce explicit waits and sleeps by automatically evaluating multiple UI stability signals.
+
 
-Eliminate explicit waits and sleeps by automatically detecting true UI stability.
 
 ## Installation
 
@@ -88,6 +90,9 @@ Waitless monitors the **entire page** for stability signals:
 - ✅ Pending network requests (XHR/fetch interception)
 - ✅ CSS animations and transitions
 - ✅ Layout stability (element movement)
+- ✅ WebSocket/SSE activity (opt-in)
+- ✅ Framework hooks (React/Angular/Vue, opt-in)
+- ✅ Same-origin iframe load readiness (opt-in; not full child-frame signal injection)
 
 When you interact, waitless ensures the page is truly ready.
 
@@ -160,7 +165,7 @@ try:
     driver.find_element(By.ID, "slow-button").click()
 except StabilizationTimeout as e:
     diagnostics = get_diagnostics(driver)
-    print_report(engine)  # Print detailed report
+    print_report(diagnostics)  # Print detailed report
 ```
 
 ### CLI Doctor Command
@@ -214,11 +219,52 @@ element = driver.find_element(By.ID, "button")
 original = element.unwrap()  # Gets the real WebElement
 ```
 
-## v0.3.2 Limitations
+## v1.0.0 New Features
+
+- **WebSocket/SSE Awareness** - Track WebSocket and Server-Sent Events activity
+- **Framework Adapters** - React, Angular, Vue hooks for framework-specific settling
+- **iframe Support** - Monitor same-origin iframes
+- **Performance Benchmarks** - Built-in benchmark suite
+
+```python
+# Enable new v1.0 features
+config = StabilizationConfig(
+    track_websocket=True,         # WebSocket monitoring
+    track_sse=True,               # SSE monitoring
+    framework_hooks=['react'],    # React adapter
+    track_iframes=True,           # iframe monitoring
+)
+```
+
+## Performance
+
+| Metric | Typical Value |
+|--------|---------------|
+| Instrumentation injection | Environment-dependent; run `python -m benchmarks.overhead_test` |
+| Per-poll overhead | Environment-dependent; run the bundled benchmark |
+| Poll interval (default) | 50ms |
+| Typical stabilization | 50-200ms after activity |
+
+### Navigation Handling
+
+Wrapped `get()`, `refresh()`, `back()`, and `forward()` wait after Selenium's
+synchronous navigation call returns. For SPA route changes initiated by page
+JavaScript, Waitless validates/re-injects instrumentation on the next wait:
+
+1. Checks `__waitless__.isAlive()` before each wait
+2. Detects URL changes via `driver.current_url`
+3. Re-injects if instrumentation is missing
+
+This does not observe routes continuously, and cross-origin iframe internals remain
+outside the browser same-origin boundary.
+
+`find_elements()` keeps Selenium's immediate-empty lookup semantics: after the
+page-stability wait, it performs one lookup and returns `[]` when there are no matches.
+
+## Current Limitations
 
-- **Selenium only** - Playwright support planned for v1
+- **Selenium only** - Playwright support planned
 - **Sync only** - No async/await support yet
-- **Main frame only** - iframes not monitored
 - **No Service Workers** - SW network requests not intercepted
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.

{waitless-0.3.2 → waitless-1.0.1}/README.md

@@ -2,9 +2,11 @@
 
 [![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**
+**Automatic UI stabilization for Selenium**
+
+Reduce explicit waits and sleeps by automatically evaluating multiple UI stability signals.
+
 
-Eliminate explicit waits and sleeps by automatically detecting true UI stability.
 
 ## Installation
 
@@ -58,6 +60,9 @@ Waitless monitors the **entire page** for stability signals:
 - ✅ Pending network requests (XHR/fetch interception)
 - ✅ CSS animations and transitions
 - ✅ Layout stability (element movement)
+- ✅ WebSocket/SSE activity (opt-in)
+- ✅ Framework hooks (React/Angular/Vue, opt-in)
+- ✅ Same-origin iframe load readiness (opt-in; not full child-frame signal injection)
 
 When you interact, waitless ensures the page is truly ready.
 
@@ -130,7 +135,7 @@ try:
     driver.find_element(By.ID, "slow-button").click()
 except StabilizationTimeout as e:
     diagnostics = get_diagnostics(driver)
-    print_report(engine)  # Print detailed report
+    print_report(diagnostics)  # Print detailed report
 ```
 
 ### CLI Doctor Command
@@ -184,11 +189,52 @@ element = driver.find_element(By.ID, "button")
 original = element.unwrap()  # Gets the real WebElement
 ```
 
-## v0.3.2 Limitations
+## v1.0.0 New Features
+
+- **WebSocket/SSE Awareness** - Track WebSocket and Server-Sent Events activity
+- **Framework Adapters** - React, Angular, Vue hooks for framework-specific settling
+- **iframe Support** - Monitor same-origin iframes
+- **Performance Benchmarks** - Built-in benchmark suite
+
+```python
+# Enable new v1.0 features
+config = StabilizationConfig(
+    track_websocket=True,         # WebSocket monitoring
+    track_sse=True,               # SSE monitoring
+    framework_hooks=['react'],    # React adapter
+    track_iframes=True,           # iframe monitoring
+)
+```
+
+## Performance
+
+| Metric | Typical Value |
+|--------|---------------|
+| Instrumentation injection | Environment-dependent; run `python -m benchmarks.overhead_test` |
+| Per-poll overhead | Environment-dependent; run the bundled benchmark |
+| Poll interval (default) | 50ms |
+| Typical stabilization | 50-200ms after activity |
+
+### Navigation Handling
+
+Wrapped `get()`, `refresh()`, `back()`, and `forward()` wait after Selenium's
+synchronous navigation call returns. For SPA route changes initiated by page
+JavaScript, Waitless validates/re-injects instrumentation on the next wait:
+
+1. Checks `__waitless__.isAlive()` before each wait
+2. Detects URL changes via `driver.current_url`
+3. Re-injects if instrumentation is missing
+
+This does not observe routes continuously, and cross-origin iframe internals remain
+outside the browser same-origin boundary.
+
+`find_elements()` keeps Selenium's immediate-empty lookup semantics: after the
+page-stability wait, it performs one lookup and returns `[]` when there are no matches.
+
+## Current Limitations
 
-- **Selenium only** - Playwright support planned for v1
+- **Selenium only** - Playwright support planned
 - **Sync only** - No async/await support yet
-- **Main frame only** - iframes not monitored
 - **No Service Workers** - SW network requests not intercepted
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.

{waitless-0.3.2 → waitless-1.0.1}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "waitless"
-version = "0.3.2"
+version = "1.0.1"
 description = "Eliminate explicit waits in UI automation by detecting true UI stability"
 readme = "README.md"
-license = {text = "MIT"}
+license = "MIT"
 requires-python = ">=3.9"
 authors = [
     {name = "Dhiraj Das", email = "dhirajdas.666@gmail.com"}
@@ -24,7 +24,6 @@ keywords = [
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.9",
@@ -34,6 +33,9 @@ classifiers = [
     "Topic :: Software Development :: Testing",
     "Topic :: Software Development :: Quality Assurance",
 ]
+dependencies = [
+    "selenium>=4.0",
+]
 
 [project.urls]
 Homepage = "https://www.dhirajdas.dev"
@@ -47,7 +49,7 @@ waitless = "waitless.__main__:main"
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
-    "selenium>=4.0",
+    "build>=1.0",
 ]
 
 [tool.setuptools.packages.find]

{waitless-0.3.2 → waitless-1.0.1}/waitless/__init__.py

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

{waitless-0.3.2 → waitless-1.0.1}/waitless/__main__.py

@@ -72,11 +72,16 @@ def run_doctor(args):
     else:
         # Show usage instructions
         print("+-" + "-" * 66 + "-+")
-        print("|" + "WAITLESS DOCTOR".center(66) + "|")
+        print("|" + "WAITLESS DOCTOR v1.0".center(66) + "|")
         print("+-" + "-" * 66 + "-+")
         print("|".ljust(67) + "|")
         print("| The doctor command analyzes stability diagnostics.".ljust(67) + "|")
         print("|".ljust(67) + "|")
+        print("| v1.0 FEATURES:".ljust(67) + "|")
+        print("|   - WebSocket/SSE tracking (track_websocket, track_sse)".ljust(67) + "|")
+        print("|   - Framework adapters (framework_hooks=['react','angular','vue'])".ljust(67) + "|")
+        print("|   - iframe monitoring (track_iframes)".ljust(67) + "|")
+        print("|".ljust(67) + "|")
         print("| USAGE OPTIONS:".ljust(67) + "|")
         print("|".ljust(67) + "|")
         print("| 1. From a diagnostic file:".ljust(67) + "|")
@@ -90,7 +95,8 @@ def run_doctor(args):
         print("|    try:".ljust(67) + "|")
         print("|        driver.find_element(...).click()".ljust(67) + "|")
         print("|    except StabilizationTimeout as e:".ljust(67) + "|")
-        print("|        print_report(engine)  # Print diagnostic report".ljust(67) + "|")
+        print("|        diagnostics = get_diagnostics(driver)".ljust(67) + "|")
+        print("|        print_report(diagnostics)".ljust(67) + "|")
         print("|".ljust(67) + "|")
         print("| 3. Export diagnostics for CI:".ljust(67) + "|")
         print("|".ljust(67) + "|")

waitless-1.0.1/waitless/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""
+Waitless Framework Adapters
+
+This module provides optional framework-specific hooks for detecting
+when React, Angular, or Vue have finished settling their internal work.
+"""
+
+from .base import FrameworkAdapter, get_adapter, get_available_adapters
+from .react import ReactAdapter
+from .angular import AngularAdapter
+from .vue import VueAdapter
+
+__all__ = [
+    'FrameworkAdapter',
+    'get_adapter',
+    'get_available_adapters',
+    'ReactAdapter',
+    'AngularAdapter', 
+    'VueAdapter',
+]

waitless-1.0.1/waitless/adapters/angular.py

@@ -0,0 +1,137 @@
+"""
+Angular framework adapter for detecting Angular-specific settling work.
+
+Detects Angular by looking for ng-version attribute or NgZone.
+Monitors NgZone stability to detect when Angular has finished its work.
+"""
+
+from .base import FrameworkAdapter
+
+
+class AngularAdapter(FrameworkAdapter):
+    """
+    Adapter for Angular framework.
+    
+    Hooks into Angular's NgZone to detect when all async tasks have completed
+    and Angular is in a stable state.
+    """
+    
+    @property
+    def name(self) -> str:
+        return 'angular'
+    
+    @property
+    def detection_script(self) -> str:
+        return """
+        (function() {
+            // Check for Angular version attribute
+            if (document.querySelector('[ng-version]')) return true;
+            
+            // Check for Angular global (older versions)
+            if (window.ng) return true;
+            
+            // Check for getAllAngularRootElements
+            if (window.getAllAngularRootElements) return true;
+            
+            return false;
+        })();
+        """
+    
+    @property
+    def instrumentation_script(self) -> str:
+        return """
+        (function() {
+            if (!window.__waitless__) return false;
+            if (window.__waitless__._angularHooked) return true;
+            
+            window.__waitless__.framework = window.__waitless__.framework || {};
+            window.__waitless__.framework.angular = {
+                isStable: true,
+                lastStableTime: Date.now(),
+                pendingTasks: 0
+            };
+            
+            // Try to get NgZone from Angular's testability API
+            var testability = window.getAllAngularTestabilities && window.getAllAngularTestabilities();
+            if (testability && testability.length > 0) {
+                testability.forEach(function(t) {
+                    t.whenStable(function() {
+                        var angular = window.__waitless__ && window.__waitless__.framework && window.__waitless__.framework.angular;
+                        if (angular) {
+                            angular.isStable = true;
+                            angular.lastStableTime = Date.now();
+                            window.__waitless__._log('Angular became stable');
+                        }
+                    });
+                });
+            }
+            
+            // Also try to hook into Zone.js if available
+            if (window.Zone && window.Zone.current) {
+                var originalRun = Zone.prototype.run;
+                window.__waitless__._angularOriginals = {
+                    zonePrototype: Zone.prototype,
+                    run: originalRun
+                };
+                Zone.prototype.run = function(callback, applyThis, applyArgs) {
+                    var angular = window.__waitless__ && window.__waitless__.framework && window.__waitless__.framework.angular;
+                    var tracked = this.name === 'angular' && angular;
+                    if (tracked) {
+                        angular.isStable = false;
+                        angular.pendingTasks++;
+                    }
+                    try {
+                        return originalRun.apply(this, arguments);
+                    } finally {
+                        var current = window.__waitless__ && window.__waitless__.framework && window.__waitless__.framework.angular;
+                        if (tracked && current) {
+                            current.pendingTasks--;
+                            if (current.pendingTasks === 0) {
+                                current.isStable = true;
+                                current.lastStableTime = Date.now();
+                            }
+                        }
+                    }
+                };
+            }
+            
+            window.__waitless__._angularHooked = true;
+            window.__waitless__._log('Angular adapter installed');
+            return true;
+        })();
+        """
+    
+    @property
+    def uninstall_script(self) -> str:
+        return """
+        (function() {
+            if (!window.__waitless__) return true;
+            var originals = window.__waitless__._angularOriginals || {};
+            if (originals.zonePrototype && originals.run) {
+                originals.zonePrototype.run = originals.run;
+            }
+            if (window.__waitless__.framework) delete window.__waitless__.framework.angular;
+            delete window.__waitless__._angularOriginals;
+            delete window.__waitless__._angularHooked;
+            return true;
+        })();
+        """
+
+    def get_status_script(self) -> str:
+        return """
+        (function() {
+            if (!window.__waitless__ || !window.__waitless__.framework || !window.__waitless__.framework.angular) {
+                return { stable: true, details: 'Angular not detected' };
+            }
+            
+            var angular = window.__waitless__.framework.angular;
+            var timeSinceStable = Date.now() - angular.lastStableTime;
+            
+            return {
+                stable: angular.isStable,
+                details: angular.isStable 
+                    ? 'NgZone stable, last activity ' + timeSinceStable + 'ms ago'
+                    : 'NgZone unstable, pending=' + angular.pendingTasks
+            };
+        })();
+        """

waitless-1.0.1/waitless/adapters/base.py

@@ -0,0 +1,79 @@
+"""
+Base adapter interface for framework-specific hooks.
+
+Adapters detect when a framework has finished its internal work
+(rendering, effects, zone tasks) beyond what DOM observation captures.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+
+class FrameworkAdapter(ABC):
+    """
+    Base class for framework-specific stability detection.
+    
+    Subclasses implement framework-specific JavaScript that detects
+    when the framework has finished its internal processing.
+    """
+    
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for this adapter (e.g., 'react', 'angular')."""
+        pass
+    
+    @property
+    @abstractmethod
+    def detection_script(self) -> str:
+        """
+        JavaScript that detects if this framework is present on the page.
+        Should return true if the framework is detected.
+        """
+        pass
+    
+    @property
+    @abstractmethod
+    def instrumentation_script(self) -> str:
+        """
+        JavaScript to inject for monitoring framework activity.
+        Should set window.__waitless__.framework[name] with status info.
+        """
+        pass
+    
+    @property
+    @abstractmethod
+    def uninstall_script(self) -> str:
+        """JavaScript that restores every function patched by this adapter."""
+        pass
+
+    @abstractmethod
+    def get_status_script(self) -> str:
+        """
+        JavaScript that returns the current framework stability status.
+        Should return { stable: bool, details: string }.
+        """
+        pass
+
+
+def get_adapter(name: str) -> Optional['FrameworkAdapter']:
+    """Get a framework adapter by name."""
+    # Lazy imports to avoid circular dependency
+    from .react import ReactAdapter
+    from .angular import AngularAdapter
+    from .vue import VueAdapter
+    
+    adapters = {
+        'react': ReactAdapter,
+        'angular': AngularAdapter,
+        'vue': VueAdapter,
+    }
+    adapter_class = adapters.get(name.lower())
+    if adapter_class:
+        return adapter_class()
+    return None
+
+
+def get_available_adapters() -> list:
+    """List available adapter names."""
+    return ['react', 'angular', 'vue']

waitless-1.0.1/waitless/adapters/react.py

@@ -0,0 +1,140 @@
+"""
+React framework adapter for detecting React-specific settling work.
+
+Detects React by looking for React DevTools hook or __REACT_DEVTOOLS_GLOBAL_HOOK__.
+Monitors React commits and batch updates to detect when React has finished rendering.
+"""
+
+from .base import FrameworkAdapter
+
+
+class ReactAdapter(FrameworkAdapter):
+    """
+    Adapter for React framework.
+    
+    Hooks into React's commit phase via the DevTools global hook to detect
+    when React has finished reconciliation and committed changes to the DOM.
+    """
+    
+    @property
+    def name(self) -> str:
+        return 'react'
+    
+    @property
+    def detection_script(self) -> str:
+        return """
+        (function() {
+            // Check for React DevTools hook (most reliable)
+            if (window.__REACT_DEVTOOLS_GLOBAL_HOOK__) return true;
+            
+            // Check for React fiber root on body
+            var root = document.getElementById('root') || document.body;
+            for (var key in root) {
+                if (key.startsWith('__reactFiber') || key.startsWith('__reactContainer')) {
+                    return true;
+                }
+            }
+            
+            return false;
+        })();
+        """
+    
+    @property
+    def instrumentation_script(self) -> str:
+        return """
+        (function() {
+            if (!window.__waitless__) return false;
+            if (window.__waitless__._reactHooked) return true;
+            
+            window.__waitless__.framework = window.__waitless__.framework || {};
+            window.__waitless__.framework.react = {
+                lastCommitTime: 0,
+                pendingUpdates: 0,
+                isSettled: true
+            };
+            
+            var originals = window.__waitless__._reactOriginals = {};
+            var hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+            if (hook && hook.onCommitFiberRoot) {
+                var originalOnCommit = hook.onCommitFiberRoot;
+                originals.hook = hook;
+                originals.onCommitFiberRoot = originalOnCommit;
+                hook.onCommitFiberRoot = function(id, root, priority) {
+                    var react = window.__waitless__ && window.__waitless__.framework && window.__waitless__.framework.react;
+                    if (react) {
+                        react.lastCommitTime = Date.now();
+                        react.isSettled = false;
+                        window.__waitless__._log('React commit', { priority: priority });
+
+                        setTimeout(function() {
+                            var current = window.__waitless__ && window.__waitless__.framework && window.__waitless__.framework.react;
+                            if (current) current.isSettled = true;
+                        }, 50);
+                    }
+
+                    return originalOnCommit.apply(this, arguments);
+                };
+            }
+            
+            // Also try to intercept React's scheduler if available
+            if (window.scheduler && window.scheduler.unstable_scheduleCallback) {
+                var originalSchedule = window.scheduler.unstable_scheduleCallback;
+                originals.scheduler = window.scheduler;
+                originals.scheduleCallback = originalSchedule;
+                window.scheduler.unstable_scheduleCallback = function(priority, callback) {
+                    var react = window.__waitless__ && window.__waitless__.framework && window.__waitless__.framework.react;
+                    if (react) react.pendingUpdates++;
+                    var wrappedCallback = function() {
+                        var result = callback.apply(this, arguments);
+                        var current = window.__waitless__ && window.__waitless__.framework && window.__waitless__.framework.react;
+                        if (current) current.pendingUpdates--;
+                        return result;
+                    };
+                    return originalSchedule.call(this, priority, wrappedCallback);
+                };
+            }
+            
+            window.__waitless__._reactHooked = true;
+            window.__waitless__._log('React adapter installed');
+            return true;
+        })();
+        """
+    
+    @property
+    def uninstall_script(self) -> str:
+        return """
+        (function() {
+            if (!window.__waitless__) return true;
+            var originals = window.__waitless__._reactOriginals || {};
+            if (originals.hook && originals.onCommitFiberRoot) {
+                originals.hook.onCommitFiberRoot = originals.onCommitFiberRoot;
+            }
+            if (originals.scheduler && originals.scheduleCallback) {
+                originals.scheduler.unstable_scheduleCallback = originals.scheduleCallback;
+            }
+            if (window.__waitless__.framework) delete window.__waitless__.framework.react;
+            delete window.__waitless__._reactOriginals;
+            delete window.__waitless__._reactHooked;
+            return true;
+        })();
+        """
+
+    def get_status_script(self) -> str:
+        return """
+        (function() {
+            if (!window.__waitless__ || !window.__waitless__.framework || !window.__waitless__.framework.react) {
+                return { stable: true, details: 'React not detected' };
+            }
+            
+            var react = window.__waitless__.framework.react;
+            var timeSinceCommit = Date.now() - react.lastCommitTime;
+            var isStable = react.isSettled && timeSinceCommit > 100;
+            
+            return {
+                stable: isStable,
+                details: isStable 
+                    ? 'React idle, last commit ' + timeSinceCommit + 'ms ago'
+                    : 'React updating, pending=' + react.pendingUpdates
+            };
+        })();
+        """