waitless 0.1.0__tar.gz

waitless-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,215 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "waitless"
+version = "0.1.0"
+description = "Eliminate explicit waits in UI automation by detecting true UI stability"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Dhiraj Das", email = "dhirajdas.66@gmail.com"}
+]
+keywords = [
+    "selenium",
+    "automation",
+    "testing",
+    "ui-testing",
+    "wait",
+    "stability",
+    "flaky-tests"
+]
+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",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://github.com/godhiraj-code/waitless"
+Documentation = "https://github.com/godhiraj-code/waitless#readme"
+Repository = "https://github.com/godhiraj-code/waitless.git"
+Issues = "https://github.com/godhiraj-code/waitless/issues"
+
+[project.scripts]
+waitless = "waitless.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "selenium>=4.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["waitless*"]

waitless-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

waitless-0.1.0/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',
+]