waitless 0.1.0__py3-none-any.whl

waitless/__init__.py

@@ -0,0 +1,92 @@
+"""
+Waitless - Zero-wait UI automation stabilization library.
+
+Eliminate explicit waits and sleeps in UI automation by automatically
+waiting for true UI stability instead of time-based conditions.
+
+Basic Usage:
+    from waitless import stabilize
+    
+    driver = webdriver.Chrome()
+    driver = stabilize(driver)  # That's it!
+    
+    # All interactions now auto-wait for stability
+    driver.find_element(By.ID, "button").click()
+
+Configuration:
+    from waitless import stabilize, StabilizationConfig
+    
+    config = StabilizationConfig(
+        timeout=5,                # Max wait time
+        strictness='strict',      # All signals must be stable
+        debug_mode=True           # Enable logging
+    )
+    
+    driver = stabilize(driver, config=config)
+
+Manual Stabilization:
+    from waitless import wait_for_stability
+    
+    wait_for_stability(driver)  # Explicit wait
+    driver.find_element(...).click()
+
+Disable:
+    from waitless import unstabilize
+    
+    driver = unstabilize(driver)  # Back to original behavior
+"""
+
+__version__ = '0.1.0'
+__author__ = 'Dhiraj Das'
+
+# Public API
+from .config import StabilizationConfig, DEFAULT_CONFIG
+from .selenium_integration import (
+    stabilize,
+    unstabilize,
+    wait_for_stability,
+    get_diagnostics,
+    StabilizedWebDriver,
+    StabilizedWebElement,
+)
+from .exceptions import (
+    WaitlessError,
+    StabilizationTimeout,
+    InstrumentationError,
+    ConfigurationError,
+    NotStabilizedError,
+)
+from .engine import StabilizationEngine
+from .diagnostics import DiagnosticReport, generate_report, print_report
+
+__all__ = [
+    # Version
+    '__version__',
+    
+    # Main API
+    'stabilize',
+    'unstabilize',
+    'wait_for_stability',
+    'get_diagnostics',
+    
+    # Configuration
+    'StabilizationConfig',
+    'DEFAULT_CONFIG',
+    
+    # Types
+    'StabilizedWebDriver',
+    'StabilizedWebElement',
+    'StabilizationEngine',
+    
+    # Exceptions
+    'WaitlessError',
+    'StabilizationTimeout',
+    'InstrumentationError',
+    'ConfigurationError',
+    'NotStabilizedError',
+    
+    # Diagnostics
+    'DiagnosticReport',
+    'generate_report',
+    'print_report',
+]

waitless/__main__.py

@@ -0,0 +1,116 @@
+"""
+CLI entry point for waitless.
+
+Provides the 'waitless doctor' command for diagnostics.
+"""
+
+import argparse
+import sys
+import json
+from datetime import datetime
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog='waitless',
+        description='Waitless - Zero-wait UI automation stabilization'
+    )
+    
+    subparsers = parser.add_subparsers(dest='command', help='Available commands')
+    
+    # Doctor command
+    doctor_parser = subparsers.add_parser(
+        'doctor',
+        help='Analyze and diagnose stability issues'
+    )
+    doctor_parser.add_argument(
+        '--json',
+        action='store_true',
+        help='Output in JSON format for CI integration'
+    )
+    doctor_parser.add_argument(
+        '--file',
+        type=str,
+        help='Load diagnostics from a JSON file'
+    )
+    
+    # Version command
+    subparsers.add_parser('version', help='Show version')
+    
+    args = parser.parse_args()
+    
+    if args.command == 'version':
+        from . import __version__
+        print(f"waitless version {__version__}")
+        return 0
+    
+    elif args.command == 'doctor':
+        return run_doctor(args)
+    
+    else:
+        parser.print_help()
+        return 0
+
+
+def run_doctor(args):
+    """Run the doctor diagnostic command."""
+    from .diagnostics import DiagnosticReport
+    
+    if args.file:
+        # Load from file
+        try:
+            with open(args.file, 'r') as f:
+                data = json.load(f)
+            diagnostics = data.get('diagnostics', data)
+        except FileNotFoundError:
+            print(f"Error: File not found: {args.file}", file=sys.stderr)
+            return 1
+        except json.JSONDecodeError as e:
+            print(f"Error: Invalid JSON: {e}", file=sys.stderr)
+            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 + "╝")
+        return 0
+    
+    # Generate report
+    report = DiagnosticReport(diagnostics)
+    
+    if args.json:
+        print(report.to_json())
+    else:
+        print(report.generate_text_report())
+    
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

waitless/config.py

@@ -0,0 +1,162 @@
+"""
+Waitless configuration management.
+
+Provides sensible defaults with full customization options.
+"""
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+from .exceptions import ConfigurationError
+
+
+StrictnessLevel = Literal['strict', 'normal', 'relaxed']
+
+
+@dataclass
+class StabilizationConfig:
+    """
+    Configuration for UI stabilization behavior.
+    
+    Attributes:
+        timeout: Maximum time (seconds) to wait for stability. Default 10s.
+                 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).
+        
+        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.
+        
+        animation_detection: Whether to wait for CSS animations/transitions.
+                             Default True. Disable for apps with infinite animations.
+        
+        layout_stability: Whether to wait for element positions to stabilize.
+                          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)
+        
+        debug_mode: Enable verbose logging for troubleshooting.
+                    Default False.
+        
+        poll_interval: How often to check stability (seconds).
+                       Default 0.05s (50ms). Lower = more responsive but more CPU.
+        
+        reinject_on_navigation: Auto-reinject instrumentation after navigation.
+                                Default True.
+    """
+    
+    timeout: float = 10.0
+    dom_settle_time: float = 0.1
+    network_idle_threshold: int = 0
+    animation_detection: bool = True
+    layout_stability: bool = True
+    strictness: StrictnessLevel = 'normal'
+    debug_mode: bool = False
+    poll_interval: float = 0.05
+    reinject_on_navigation: bool = True
+    
+    def __post_init__(self):
+        """Validate configuration values."""
+        self._validate()
+    
+    def _validate(self) -> None:
+        """Validate all configuration values."""
+        if self.timeout <= 0:
+            raise ConfigurationError(f"timeout must be positive, got {self.timeout}")
+        
+        if self.timeout > 60:
+            import warnings
+            warnings.warn(
+                f"timeout of {self.timeout}s is very high. "
+                "Consider investigating root cause of slow stability.",
+                UserWarning
+            )
+        
+        if self.dom_settle_time < 0:
+            raise ConfigurationError(
+                f"dom_settle_time must be non-negative, got {self.dom_settle_time}"
+            )
+        
+        if self.network_idle_threshold < 0:
+            raise ConfigurationError(
+                f"network_idle_threshold must be non-negative, got {self.network_idle_threshold}"
+            )
+        
+        if self.poll_interval <= 0:
+            raise ConfigurationError(
+                f"poll_interval must be positive, got {self.poll_interval}"
+            )
+        
+        if self.poll_interval > self.timeout:
+            raise ConfigurationError(
+                f"poll_interval ({self.poll_interval}) cannot exceed timeout ({self.timeout})"
+            )
+        
+        if self.strictness not in ('strict', 'normal', 'relaxed'):
+            raise ConfigurationError(
+                f"strictness must be 'strict', 'normal', or 'relaxed', got '{self.strictness}'"
+            )
+    
+    def with_overrides(self, **kwargs) -> 'StabilizationConfig':
+        """
+        Create a new config with some values overridden.
+        
+        Example:
+            new_config = config.with_overrides(timeout=5, debug_mode=True)
+        """
+        current = {
+            'timeout': self.timeout,
+            'dom_settle_time': self.dom_settle_time,
+            'network_idle_threshold': self.network_idle_threshold,
+            'animation_detection': self.animation_detection,
+            'layout_stability': self.layout_stability,
+            'strictness': self.strictness,
+            'debug_mode': self.debug_mode,
+            'poll_interval': self.poll_interval,
+            'reinject_on_navigation': self.reinject_on_navigation,
+        }
+        current.update(kwargs)
+        return StabilizationConfig(**current)
+    
+    @classmethod
+    def strict(cls) -> 'StabilizationConfig':
+        """Factory for strict configuration (all signals, lower timeout)."""
+        return cls(
+            strictness='strict',
+            timeout=5.0,
+            animation_detection=True,
+            layout_stability=True,
+        )
+    
+    @classmethod
+    def relaxed(cls) -> 'StabilizationConfig':
+        """Factory for relaxed configuration (DOM only, higher threshold)."""
+        return cls(
+            strictness='relaxed',
+            network_idle_threshold=2,
+            animation_detection=False,
+            layout_stability=False,
+        )
+    
+    @classmethod
+    def ci(cls) -> 'StabilizationConfig':
+        """Factory for CI environments (longer timeout, verbose logging)."""
+        return cls(
+            timeout=15.0,
+            debug_mode=True,
+            strictness='normal',
+        )
+
+
+DEFAULT_CONFIG = StabilizationConfig()

waitless/diagnostics.py

@@ -0,0 +1,171 @@
+"""
+Diagnostics and doctor feature.
+
+Provides detailed analysis of stability issues with actionable suggestions.
+"""
+
+import json
+from datetime import datetime
+from typing import Dict, Any, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .engine import StabilizationEngine
+
+
+class DiagnosticReport:
+    """
+    Generates human-readable diagnostic reports for stability issues.
+    """
+    
+    def __init__(self, diagnostics: Dict[str, Any]):
+        self.diagnostics = diagnostics
+        self.timestamp = datetime.now()
+    
+    def generate_text_report(self) -> str:
+        """Generate a text-based diagnostic report."""
+        lines = []
+        lines.append("╔" + "═" * 66 + "╗")
+        lines.append("║" + "WAITLESS STABILITY REPORT".center(66) + "║")
+        lines.append("╠" + "═" * 66 + "╣")
+        lines.append(f"║ Report generated at: {self.timestamp.strftime('%Y-%m-%d %H:%M:%S'):<43} ║")
+        
+        config = self.diagnostics.get('config', {})
+        lines.append("╠" + "═" * 66 + "╣")
+        lines.append("║ CONFIGURATION:".ljust(67) + "║")
+        lines.append(f"║   Timeout: {config.get('timeout', 'N/A')}s".ljust(67) + "║")
+        lines.append(f"║   Strictness: {config.get('strictness', 'N/A')}".ljust(67) + "║")
+        lines.append(f"║   Network threshold: {config.get('network_idle_threshold', 'N/A')} pending requests".ljust(67) + "║")
+        lines.append(f"║   Animation detection: {config.get('animation_detection', 'N/A')}".ljust(67) + "║")
+        
+        blocking = self.diagnostics.get('blocking_factors', {})
+        if blocking:
+            lines.append("╠" + "═" * 66 + "╣")
+            lines.append("║ BLOCKING FACTORS:".ljust(67) + "║")
+            lines.append("║".ljust(67) + "║")
+            
+            pending = blocking.get('pending_requests', 0)
+            if pending > 0:
+                lines.append("║ ⚠ NETWORK: {} request(s) still pending".format(pending).ljust(67) + "║")
+                
+                details = blocking.get('pending_request_details', [])
+                for req in details[:5]:  # Show max 5
+                    url = req.get('url', 'unknown')[:50]
+                    started = req.get('startTime', 0)
+                    lines.append(f"║   → {req.get('type', 'unknown').upper()} {url}".ljust(67) + "║")
+                
+                if len(details) > 5:
+                    lines.append(f"║   ... and {len(details) - 5} more".ljust(67) + "║")
+                lines.append("║".ljust(67) + "║")
+            
+            animations = blocking.get('active_animations', 0)
+            if animations > 0:
+                lines.append(f"║ ⚠ ANIMATIONS: {animations} active animation(s)".ljust(67) + "║")
+                lines.append("║".ljust(67) + "║")
+            
+            if blocking.get('layout_shifting'):
+                lines.append("║ ⚠ LAYOUT: Elements are still moving".ljust(67) + "║")
+                lines.append("║".ljust(67) + "║")
+        
+        status = self.diagnostics.get('last_status')
+        if status:
+            lines.append("╠" + "═" * 66 + "╣")
+            lines.append("║ SIGNAL STATUS:".ljust(67) + "║")
+            
+            for signal in status.get('signals', []):
+                state = "✓" if signal['state'] == 'STABLE' else "✗"
+                mandatory = "[M]" if signal['mandatory'] else "[O]"
+                line = f"║   {state} {mandatory} {signal['type']}: {signal.get('details', 'N/A')}"
+                lines.append(line[:66].ljust(67) + "║")
+        
+        timeline = self.diagnostics.get('timeline', [])
+        if timeline:
+            lines.append("╠" + "═" * 66 + "╣")
+            lines.append("║ RECENT EVENTS (last 10):".ljust(67) + "║")
+            
+            for entry in timeline[-10:]:
+                time_str = str(entry.get('time', ''))[-6:]
+                msg = entry.get('message', '')[:50]
+                lines.append(f"║   [{time_str}] {msg}".ljust(67) + "║")
+        
+        lines.extend(self._generate_suggestions())
+        lines.append("╚" + "═" * 66 + "╝")
+        
+        return "\n".join(lines)
+    
+    def _generate_suggestions(self) -> List[str]:
+        """Generate actionable suggestions based on diagnostics."""
+        lines = []
+        suggestions = []
+        
+        blocking = self.diagnostics.get('blocking_factors', {})
+        config = self.diagnostics.get('config', {})
+        pending = blocking.get('pending_requests', 0)
+        if pending > 0:
+            threshold = config.get('network_idle_threshold', 0)
+            if threshold == 0:
+                suggestions.append(
+                    "Network requests are blocking stability. If your app has "
+                    "background traffic (analytics, polling), consider:\n"
+                    "     config = StabilizationConfig(network_idle_threshold=2)"
+                )
+            
+            details = blocking.get('pending_request_details', [])
+            slow_apis = [r for r in details if '/api/' in r.get('url', '')]
+            if slow_apis:
+                suggestions.append(
+                    "Slow API endpoints detected. Consider:\n"
+                    "     - Mocking slow endpoints in tests\n"
+                    "     - Increasing timeout if APIs are legitimately slow"
+                )
+        animations = blocking.get('active_animations', 0)
+        if animations > 0:
+            suggestions.append(
+                "CSS animations are blocking stability. If you have infinite "
+                "animations (spinners), consider:\n"
+                "     config = StabilizationConfig(animation_detection=False)\n"
+                "     OR use strictness='relaxed'"
+            )
+        if blocking.get('layout_shifting'):
+            suggestions.append(
+                "Layout is unstable (elements moving). This often indicates:\n"
+                "     - Images loading without dimensions\n"
+                "     - Font loading causing reflow\n"
+                "     - Dynamic content insertion"
+            )
+        timeout = config.get('timeout', 10)
+        if timeout >= 10:
+            suggestions.append(
+                f"Timeout is {timeout}s (default). For faster feedback, consider:\n"
+                "     config = StabilizationConfig(timeout=5)"
+            )
+        
+        if suggestions:
+            lines.append("╠" + "═" * 66 + "╣")
+            lines.append("║ SUGGESTIONS:".ljust(67) + "║")
+            lines.append("║".ljust(67) + "║")
+            
+            for i, suggestion in enumerate(suggestions, 1):
+                for line in f"{i}. {suggestion}".split('\n'):
+                    lines.append(f"║ {line}".ljust(67) + "║")
+                lines.append("║".ljust(67) + "║")
+        
+        return lines
+    
+    def to_json(self) -> str:
+        """Export diagnostics as JSON for CI integration."""
+        return json.dumps({
+            'timestamp': self.timestamp.isoformat(),
+            'diagnostics': self.diagnostics,
+        }, indent=2, default=str)
+
+
+def generate_report(engine: 'StabilizationEngine') -> DiagnosticReport:
+    """Generate a diagnostic report from an engine."""
+    diagnostics = engine.get_diagnostics()
+    return DiagnosticReport(diagnostics)
+
+
+def print_report(engine: 'StabilizationEngine') -> None:
+    """Print a diagnostic report to stdout."""
+    report = generate_report(engine)
+    print(report.generate_text_report())