waitless 0.3.1__tar.gz → 1.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waitless
-Version: 0.3.1
+Version: 1.0.0
 Summary: Eliminate explicit waits in UI automation by detecting true UI stability
 Author-email: Dhiraj Das <dhirajdas.666@gmail.com>
 License: MIT
@@ -36,6 +36,8 @@ Dynamic: license-file
 
 Eliminate explicit waits and sleeps by automatically detecting true UI stability.
 
+
+
 ## Installation
 
 ```bash
@@ -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)
+- ✅ iframe monitoring (opt-in)
 
 When you interact, waitless ensures the page is truly ready.
 
@@ -171,18 +176,18 @@ python -m waitless doctor --file diagnostics.json
 
 Sample output:
 ```
-╔══════════════════════════════════════════════════════════════════╗
-║                    WAITLESS STABILITY REPORT                     ║
-╠══════════════════════════════════════════════════════════════════╣
-║ BLOCKING FACTORS:                                                ║
-║   ⚠ NETWORK: 2 request(s) still pending                         ║
-║   → GET /api/users                                               ║
-║   ⚠ ANIMATIONS: 1 active animation(s)                           ║
-╠══════════════════════════════════════════════════════════════════╣
-║ SUGGESTIONS:                                                     ║
-║   1. Set network_idle_threshold=2 for background traffic         ║
-║   2. Use animation_detection=False for infinite spinners         ║
-╚══════════════════════════════════════════════════════════════════╝
++--------------------------------------------------------------------+
+|                     WAITLESS STABILITY REPORT                      |
++--------------------------------------------------------------------+
+| BLOCKING FACTORS:                                                  |
+|   [!] NETWORK: 2 request(s) still pending                          |
+|   -> GET /api/users                                                |
+|   [!] ANIMATIONS: 1 active animation(s)                            |
++--------------------------------------------------------------------+
+| SUGGESTIONS:                                                       |
+|   1. Set network_idle_threshold=2 for background traffic           |
+|   2. Use animation_detection=False for infinite spinners           |
++--------------------------------------------------------------------+
 ```
 
 ## Important Notes
@@ -214,11 +219,46 @@ element = driver.find_element(By.ID, "button")
 original = element.unwrap()  # Gets the real WebElement
 ```
 
-## v0.3 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 | ~5-10ms |
+| Per-poll overhead | ~1-2ms |
+| Poll interval (default) | 50ms |
+| Typical stabilization | 50-200ms after activity |
+
+### SPA Navigation Handling
+
+Waitless automatically re-injects instrumentation after SPA route changes:
+
+1. Checks `__waitless__.isAlive()` before each wait
+2. Detects URL changes via `driver.current_url`
+3. Re-injects if instrumentation is missing
+
+This works transparently with React Router, Vue Router, Angular Router, etc.
+
+## 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.1 → waitless-1.0.0}/README.md

@@ -6,6 +6,8 @@
 
 Eliminate explicit waits and sleeps by automatically detecting true UI stability.
 
+
+
 ## Installation
 
 ```bash
@@ -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)
+- ✅ iframe monitoring (opt-in)
 
 When you interact, waitless ensures the page is truly ready.
 
@@ -141,18 +146,18 @@ python -m waitless doctor --file diagnostics.json
 
 Sample output:
 ```
-╔══════════════════════════════════════════════════════════════════╗
-║                    WAITLESS STABILITY REPORT                     ║
-╠══════════════════════════════════════════════════════════════════╣
-║ BLOCKING FACTORS:                                                ║
-║   ⚠ NETWORK: 2 request(s) still pending                         ║
-║   → GET /api/users                                               ║
-║   ⚠ ANIMATIONS: 1 active animation(s)                           ║
-╠══════════════════════════════════════════════════════════════════╣
-║ SUGGESTIONS:                                                     ║
-║   1. Set network_idle_threshold=2 for background traffic         ║
-║   2. Use animation_detection=False for infinite spinners         ║
-╚══════════════════════════════════════════════════════════════════╝
++--------------------------------------------------------------------+
+|                     WAITLESS STABILITY REPORT                      |
++--------------------------------------------------------------------+
+| BLOCKING FACTORS:                                                  |
+|   [!] NETWORK: 2 request(s) still pending                          |
+|   -> GET /api/users                                                |
+|   [!] ANIMATIONS: 1 active animation(s)                            |
++--------------------------------------------------------------------+
+| SUGGESTIONS:                                                       |
+|   1. Set network_idle_threshold=2 for background traffic           |
+|   2. Use animation_detection=False for infinite spinners           |
++--------------------------------------------------------------------+
 ```
 
 ## Important Notes
@@ -184,11 +189,46 @@ element = driver.find_element(By.ID, "button")
 original = element.unwrap()  # Gets the real WebElement
 ```
 
-## v0.3 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 | ~5-10ms |
+| Per-poll overhead | ~1-2ms |
+| Poll interval (default) | 50ms |
+| Typical stabilization | 50-200ms after activity |
+
+### SPA Navigation Handling
+
+Waitless automatically re-injects instrumentation after SPA route changes:
+
+1. Checks `__waitless__.isAlive()` before each wait
+2. Detects URL changes via `driver.current_url`
+3. Re-injects if instrumentation is missing
+
+This works transparently with React Router, Vue Router, Angular Router, etc.
+
+## 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.1 → waitless-1.0.0}/pyproject.toml

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

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

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

{waitless-0.3.1 → waitless-1.0.0}/waitless/__main__.py

@@ -71,34 +71,39 @@ def run_doctor(args):
             return 1
     else:
         # Show usage instructions
-        print("╔" + "═" * 66 + "╗")
-        print("║" + "WAITLESS DOCTOR".center(66) + "║")
-        print("╠" + "═" * 66 + "╣")
-        print("║".ljust(67) + "║")
-        print("║ The doctor command analyzes stability diagnostics.".ljust(67) + "║")
-        print("║".ljust(67) + "║")
-        print("║ USAGE OPTIONS:".ljust(67) + "║")
-        print("║".ljust(67) + "║")
-        print("║ 1. From a diagnostic file:".ljust(67) + "║")
-        print("║    waitless doctor --file diagnostics.json".ljust(67) + "║")
-        print("║".ljust(67) + "║")
-        print("║ 2. In your test code, capture diagnostics on failure:".ljust(67) + "║")
-        print("║".ljust(67) + "║")
-        print("║    from waitless import get_diagnostics".ljust(67) + "║")
-        print("║    from waitless.diagnostics import print_report".ljust(67) + "║")
-        print("║".ljust(67) + "║")
-        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("║".ljust(67) + "║")
-        print("║ 3. Export diagnostics for CI:".ljust(67) + "║")
-        print("║".ljust(67) + "║")
-        print("║    diagnostics = get_diagnostics(driver)".ljust(67) + "║")
-        print("║    with open('diag.json', 'w') as f:".ljust(67) + "║")
-        print("║        json.dump(diagnostics, f)".ljust(67) + "║")
-        print("║".ljust(67) + "║")
-        print("╚" + "═" * 66 + "╝")
+        print("+-" + "-" * 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) + "|")
+        print("|    waitless doctor --file diagnostics.json".ljust(67) + "|")
+        print("|".ljust(67) + "|")
+        print("| 2. In your test code, capture diagnostics on failure:".ljust(67) + "|")
+        print("|".ljust(67) + "|")
+        print("|    from waitless import get_diagnostics".ljust(67) + "|")
+        print("|    from waitless.diagnostics import print_report".ljust(67) + "|")
+        print("|".ljust(67) + "|")
+        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("|".ljust(67) + "|")
+        print("| 3. Export diagnostics for CI:".ljust(67) + "|")
+        print("|".ljust(67) + "|")
+        print("|    diagnostics = get_diagnostics(driver)".ljust(67) + "|")
+        print("|    with open('diag.json', 'w') as f:".ljust(67) + "|")
+        print("|        json.dump(diagnostics, f)".ljust(67) + "|")
+        print("|".ljust(67) + "|")
+        print("+-" + "-" * 66 + "-+")
         return 0
     
     # Generate report

waitless-1.0.0/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.0/waitless/adapters/angular.py

@@ -0,0 +1,109 @@
+"""
+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() {
+                        window.__waitless__.framework.angular.isStable = true;
+                        window.__waitless__.framework.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;
+                Zone.prototype.run = function(callback, applyThis, applyArgs) {
+                    if (this.name === 'angular') {
+                        window.__waitless__.framework.angular.isStable = false;
+                        window.__waitless__.framework.angular.pendingTasks++;
+                    }
+                    var result = originalRun.apply(this, arguments);
+                    if (this.name === 'angular') {
+                        window.__waitless__.framework.angular.pendingTasks--;
+                        if (window.__waitless__.framework.angular.pendingTasks === 0) {
+                            window.__waitless__.framework.angular.isStable = true;
+                            window.__waitless__.framework.angular.lastStableTime = Date.now();
+                        }
+                    }
+                    return result;
+                };
+            }
+            
+            window.__waitless__._angularHooked = true;
+            window.__waitless__._log('Angular adapter installed');
+            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.0/waitless/adapters/base.py

@@ -0,0 +1,73 @@
+"""
+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
+    
+    @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.0/waitless/adapters/react.py

@@ -0,0 +1,111 @@
+"""
+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 hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+            if (hook && hook.onCommitFiberRoot) {
+                var originalOnCommit = hook.onCommitFiberRoot;
+                hook.onCommitFiberRoot = function(id, root, priority) {
+                    window.__waitless__.framework.react.lastCommitTime = Date.now();
+                    window.__waitless__.framework.react.isSettled = false;
+                    window.__waitless__._log('React commit', { priority: priority });
+                    
+                    // Mark as settled after a short delay (microtask completion)
+                    setTimeout(function() {
+                        window.__waitless__.framework.react.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;
+                window.scheduler.unstable_scheduleCallback = function(priority, callback) {
+                    window.__waitless__.framework.react.pendingUpdates++;
+                    var wrappedCallback = function() {
+                        var result = callback.apply(this, arguments);
+                        window.__waitless__.framework.react.pendingUpdates--;
+                        return result;
+                    };
+                    return originalSchedule.call(this, priority, wrappedCallback);
+                };
+            }
+            
+            window.__waitless__._reactHooked = true;
+            window.__waitless__._log('React adapter installed');
+            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
+            };
+        })();
+        """