waitless 0.1.0__py3-none-any.whl

waitless/signals.py

@@ -0,0 +1,215 @@
+"""
+Stability signal definitions and combination logic.
+
+Signals are measurable indicators of UI state. This module defines
+what signals exist, how to interpret them, and how to combine them
+into an overall stability decision.
+
+Note: This module is designed to be a future extension point.
+Users may eventually be able to define custom signals.
+"""
+
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Dict, Any, List, Optional
+from .config import StabilizationConfig
+
+
+class SignalType(Enum):
+    """Types of stability signals we monitor."""
+    DOM_MUTATIONS = auto()
+    NETWORK_REQUESTS = auto()
+    CSS_ANIMATIONS = auto()
+    CSS_TRANSITIONS = auto()
+    LAYOUT_SHIFT = auto()
+    RAF_ACTIVITY = auto()
+
+
+class SignalState(Enum):
+    """State of an individual signal."""
+    STABLE = auto()      # Signal indicates stability
+    UNSTABLE = auto()    # Signal indicates instability
+    UNKNOWN = auto()     # Signal not yet measured
+
+
+@dataclass
+class Signal:
+    """
+    Represents a single stability signal measurement.
+    
+    Attributes:
+        signal_type: The type of signal
+        state: Current state (stable/unstable/unknown)
+        value: Raw measurement value
+        threshold: Threshold used for stability decision
+        is_mandatory: Whether this signal must be stable
+        details: Additional diagnostic information
+    """
+    signal_type: SignalType
+    state: SignalState
+    value: Any
+    threshold: Any
+    is_mandatory: bool
+    details: Optional[str] = None
+    
+    @property
+    def is_stable(self) -> bool:
+        return self.state == SignalState.STABLE
+    
+    @property
+    def is_blocking(self) -> bool:
+        """Returns True if this signal is blocking overall stability."""
+        return self.is_mandatory and not self.is_stable
+
+
+@dataclass
+class StabilityStatus:
+    """
+    Overall stability status combining all signals.
+    
+    Attributes:
+        is_stable: Whether UI is considered stable
+        signals: Individual signal measurements
+        blocking_signals: Signals preventing stability
+        timestamp: When this status was measured
+    """
+    is_stable: bool
+    signals: List[Signal]
+    timestamp: float
+    
+    @property
+    def blocking_signals(self) -> List[Signal]:
+        """Get list of signals blocking stability."""
+        return [s for s in self.signals if s.is_blocking]
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for diagnostics."""
+        return {
+            'is_stable': self.is_stable,
+            'timestamp': self.timestamp,
+            'signals': [
+                {
+                    'type': s.signal_type.name,
+                    'state': s.state.name,
+                    'value': s.value,
+                    'threshold': s.threshold,
+                    'mandatory': s.is_mandatory,
+                    'details': s.details,
+                }
+                for s in self.signals
+            ],
+            'blocking': [s.signal_type.name for s in self.blocking_signals],
+        }
+
+
+class SignalEvaluator:
+    """
+    Evaluates browser state against configured thresholds.
+    
+    This class interprets raw browser measurements and converts them
+    into Signal objects with stability decisions.
+    """
+    
+    def __init__(self, config: StabilizationConfig):
+        self.config = config
+    
+    def evaluate(self, browser_state: Dict[str, Any], current_time: float) -> StabilityStatus:
+        """
+        Evaluate browser state and return stability status.
+        
+        Args:
+            browser_state: Raw state from JavaScript instrumentation
+            current_time: Current timestamp for calculations
+            
+        Returns:
+            StabilityStatus with all signal evaluations
+        """
+        signals = []
+        
+        dom_signal = self._evaluate_dom(browser_state, current_time)
+        signals.append(dom_signal)
+        
+        network_signal = self._evaluate_network(browser_state)
+        signals.append(network_signal)
+        
+        if self.config.animation_detection:
+            animation_signal = self._evaluate_animations(browser_state)
+            signals.append(animation_signal)
+        
+        if self.config.strictness == 'strict' and self.config.layout_stability:
+            layout_signal = self._evaluate_layout(browser_state)
+            signals.append(layout_signal)
+        
+        is_stable = all(
+            s.is_stable for s in signals if s.is_mandatory
+        )
+        
+        if self.config.strictness == 'strict' and is_stable:
+            is_stable = all(s.is_stable for s in signals)
+        
+        return StabilityStatus(
+            is_stable=is_stable,
+            signals=signals,
+            timestamp=current_time,
+        )
+    
+    def _evaluate_dom(self, state: Dict[str, Any], current_time: float) -> Signal:
+        """Evaluate DOM mutation activity."""
+        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
+        
+        is_stable = time_since_mutation >= threshold_ms
+        
+        return Signal(
+            signal_type=SignalType.DOM_MUTATIONS,
+            state=SignalState.STABLE if is_stable else SignalState.UNSTABLE,
+            value=time_since_mutation,
+            threshold=threshold_ms,
+            is_mandatory=True,
+            details=f"Last mutation {time_since_mutation:.0f}ms ago (need {threshold_ms:.0f}ms quiet)",
+        )
+    
+    def _evaluate_network(self, state: Dict[str, Any]) -> Signal:
+        """Evaluate pending network requests."""
+        pending = state.get('pending_requests', 0)
+        threshold = self.config.network_idle_threshold
+        
+        is_stable = pending <= threshold
+        
+        return Signal(
+            signal_type=SignalType.NETWORK_REQUESTS,
+            state=SignalState.STABLE if is_stable else SignalState.UNSTABLE,
+            value=pending,
+            threshold=threshold,
+            is_mandatory=True,
+            details=f"{pending} pending request(s) (threshold: {threshold})",
+        )
+    
+    def _evaluate_animations(self, state: Dict[str, Any]) -> Signal:
+        """Evaluate CSS animation/transition activity."""
+        active = state.get('active_animations', 0)
+        is_mandatory = self.config.strictness != 'relaxed'
+        is_stable = active == 0
+        
+        return Signal(
+            signal_type=SignalType.CSS_ANIMATIONS,
+            state=SignalState.STABLE if is_stable else SignalState.UNSTABLE,
+            value=active,
+            threshold=0,
+            is_mandatory=is_mandatory,
+            details=f"{active} active animation(s)",
+        )
+    
+    def _evaluate_layout(self, state: Dict[str, Any]) -> Signal:
+        """Evaluate layout stability (element movement)."""
+        is_shifting = state.get('layout_shifting', False)
+        
+        return Signal(
+            signal_type=SignalType.LAYOUT_SHIFT,
+            state=SignalState.STABLE if not is_shifting else SignalState.UNSTABLE,
+            value=is_shifting,
+            threshold=False,
+            is_mandatory=self.config.strictness == 'strict',
+            details="Layout shifting detected" if is_shifting else "Layout stable",
+        )

waitless-0.1.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: waitless
+Version: 0.1.0
+Summary: Eliminate explicit waits in UI automation by detecting true UI stability
+Author-email: Dhiraj Das <dhirajdas.66@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/godhiraj-code/waitless
+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
+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
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: selenium>=4.0; extra == "dev"
+
+# Waitless
+
+**Zero-wait UI automation stabilization for Selenium**
+
+Eliminate explicit waits and sleeps by automatically detecting true UI stability.
+
+## Installation
+
+```bash
+pip install waitless
+```
+
+## Quick Start
+
+```python
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from waitless import stabilize
+
+# Create driver as usual
+driver = webdriver.Chrome()
+
+# Enable automatic stabilization - ONE LINE
+driver = stabilize(driver)
+
+# All interactions now auto-wait for stability
+driver.get("https://example.com")
+driver.find_element(By.ID, "login-button").click()  # ← Auto-waits!
+driver.find_element(By.ID, "username").send_keys("user")  # ← Auto-waits!
+```
+
+## Why Waitless?
+
+### The Problem
+
+Automation tests fail because interactions happen while the UI is still changing:
+
+- DOM mutations from React/Vue/Angular updates
+- In-flight AJAX requests
+- CSS animations and transitions
+- Layout shifts from lazy-loaded content
+
+### Traditional Solutions (and why they fail)
+
+| Approach | Problem |
+|----------|---------|
+| `time.sleep(2)` | Too slow, still fails sometimes |
+| `WebDriverWait` | Only checks one element, misses page-wide state |
+| Retries | Masks the real problem, adds flakiness |
+
+### The Waitless Solution
+
+Waitless monitors the **entire page** for stability signals:
+
+- ✅ DOM mutation activity (MutationObserver)
+- ✅ Pending network requests (XHR/fetch interception)
+- ✅ CSS animations and transitions
+- ✅ Layout stability (element movement)
+
+When you interact, waitless ensures the page is truly ready.
+
+## Configuration
+
+```python
+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
+)
+
+driver = stabilize(driver, config=config)
+```
+
+### Strictness Levels
+
+| Level | What It Waits For |
+|-------|-------------------|
+| `strict` | DOM + Network + Animations + Layout |
+| `normal` | DOM + Network (default) |
+| `relaxed` | DOM only |
+
+### Factory Methods
+
+```python
+# For strict testing
+config = StabilizationConfig.strict()
+
+# For apps with background traffic
+config = StabilizationConfig.relaxed()
+
+# For CI environments
+config = StabilizationConfig.ci()
+```
+
+## Manual Stabilization
+
+If you don't want to wrap the driver:
+
+```python
+from waitless import wait_for_stability
+
+wait_for_stability(driver)
+driver.find_element(By.ID, "button").click()
+```
+
+## Disabling Stabilization
+
+```python
+from waitless import unstabilize
+
+driver = unstabilize(driver)  # Back to original behavior
+```
+
+## Diagnostics
+
+When tests fail, get detailed analysis:
+
+```python
+from waitless import get_diagnostics, StabilizationTimeout
+from waitless.diagnostics import print_report
+
+try:
+    driver.find_element(By.ID, "slow-button").click()
+except StabilizationTimeout as e:
+    diagnostics = get_diagnostics(driver)
+    print_report(engine)  # Print detailed report
+```
+
+### CLI Doctor Command
+
+```bash
+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         ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+## Important Notes
+
+### Network Threshold Warning
+
+The default `network_idle_threshold=0` means **all** network requests must complete.
+
+Many apps have background traffic that never stops:
+- Analytics calls
+- Long polling
+- Feature flags
+- WebSocket heartbeats
+
+If tests timeout frequently, try:
+```python
+config = StabilizationConfig(network_idle_threshold=2)
+```
+
+### Wrapped Elements
+
+The stabilized driver returns wrapped elements that auto-wait. They behave like WebElements but:
+
+- `isinstance(element, WebElement)` returns `False`
+- Use `.unwrap()` to get the original element if needed
+
+```python
+element = driver.find_element(By.ID, "button")
+original = element.unwrap()  # Gets the real WebElement
+```
+
+## v0 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
+
+## API Reference
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `stabilize(driver, config=None)` | Enable auto-stabilization |
+| `unstabilize(driver)` | Disable and return original driver |
+| `wait_for_stability(driver, timeout=None)` | Manual one-time wait |
+| `get_diagnostics(driver)` | Get diagnostic data |
+
+### Classes
+
+| Class | Description |
+|-------|-------------|
+| `StabilizationConfig` | Configuration options |
+| `StabilizedWebDriver` | Wrapped driver with auto-wait |
+| `StabilizedWebElement` | Wrapped element with auto-wait |
+| `StabilizationTimeout` | Exception when UI doesn't stabilize |
+
+## License
+
+MIT

waitless-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+waitless/__init__.py,sha256=R3RDZb6qVdCWPmhVbCXNU_VFHHuinV7YlB2pdK6SU1A,2244
+waitless/__main__.py,sha256=hqJRbJOqOhGJIMBOL6vsvRFmk8KsAofuFAOg65P4KJo,3915
+waitless/config.py,sha256=AJEUUXZwKvTkCl-jIjLZHfk93EE2sHeXn_bY7mN7HeA,6068
+waitless/diagnostics.py,sha256=BmPhaXMhJpWh2fR7fPzM8f6_wnqu4Uxurq1_IhzMaRM,7709
+waitless/engine.py,sha256=fvUY-64rQjPVabDL5oGj4MUpuBFF8j9m9Kbvzohc8yA,9854
+waitless/exceptions.py,sha256=xSsOjNgpSrx7hXqg1xKFAq6quIa8VWx81YyZ5GOUllQ,3578
+waitless/instrumentation.py,sha256=6XF4_xJnTx3mKNR5ySTeI7s6iIcq9t9qvuRl8SwrLa8,11606
+waitless/selenium_integration.py,sha256=mUS_wRowkXQZuvMS0auHZ1MzTuWoqCU6wn5jOcJM-M0,10061
+waitless/signals.py,sha256=lCgSNHhm1309gy2blQdjK8hTyZvXSYuFi9H0P6x0ngs,7537
+waitless-0.1.0.dist-info/METADATA,sha256=o6TzoJfC_WFjWSynpB9yfTncylFMzNeEKjA8DMRn064,7925
+waitless-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+waitless-0.1.0.dist-info/entry_points.txt,sha256=xbJnCccN-M60RRIAaLOV8ILP6C6xwt18ykmfYJXUShU,52
+waitless-0.1.0.dist-info/top_level.txt,sha256=tRSHQHQXgHldCfnMRAjwrjd4ezBGe4dJUCOD5ABtPJc,9
+waitless-0.1.0.dist-info/RECORD,,

waitless-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

waitless-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+waitless = waitless.__main__:main

waitless-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+waitless