wup 0.2.14__tar.gz → 0.2.16__tar.gz

{wup-0.2.14/wup.egg-info → wup-0.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wup
-Version: 0.2.14
+Version: 0.2.16
 Summary: WUP (What's Up) - Intelligent file watcher for regression testing in large projects
 Author-email: Tom Sapletta <tom@sapletta.com>
 License: Apache-2.0
@@ -29,17 +29,17 @@ Dynamic: license-file
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.14-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$2.25-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-3.2h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.16-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$2.55-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-4.5h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $2.2500 (15 commits)
-- 👤 **Human dev:** ~$324 (3.2h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $2.5500 (17 commits)
+- 👤 **Human dev:** ~$445 (4.5h @ $100/h, 30min dedup)
 
 Generated on 2026-04-29 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.14-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.16-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 **WUP (What's Up)** - Intelligent file watcher for regression testing in large projects.
 
@@ -285,56 +285,128 @@ export WUP_CPU_THROTTLE=0.5
 export WUP_DEBOUNCE=3
 ```
 
-## Integration with Test Frameworks
-
-WUP is designed to work with any test framework. The current implementation includes placeholder test methods that you can customize:
-
-```python
-# In wup/core.py, customize these methods:
-
-async def run_quick_test(self, service: str, endpoints: List[str]) -> bool:
-    # Integrate with your test framework (pytest, unittest, TestQL, etc.)
-    # Example:
-    result = subprocess.run([
-        "pytest", f"tests/{service}/test_smoke.py",
-        "--maxfail=1", "-q"
-    ])
-    return result.returncode == 0
-
-async def run_detail_test(self, service: str, endpoints: List[str]) -> Dict:
-    # Run full test suite with blame reporting
-    # Example:
-    result = subprocess.run([
-        "pytest", f"tests/{service}/",
-        "--cov", f"app/{service}",
-        "--cov-report=json"
-    ])
-    return parse_coverage_report("coverage.json")
+## Visual DOM Diff
+
+WUP optionally scans configured pages with Playwright after each successful quick test, compares the DOM structure to the previous snapshot, and reports significant changes.
+
+### Setup
+
+```bash
+pip install playwright
+playwright install chromium
 ```
 
+### Configuration
+
+```yaml
+visual_diff:
+  enabled: true
+  base_url: "http://localhost:8100"   # or leave empty and set WUP_BASE_URL env var
+  base_url_env: "WUP_BASE_URL"
+  delay_seconds: 5.0      # wait after file change before scanning
+  max_depth: 10            # DOM snapshot depth
+  pages:
+    - "/health"
+    - "/dashboard"
+  pages_from_endpoints: true   # also scan endpoints from testql config
+  threshold_added: 3           # min node additions to report as "changed"
+  threshold_removed: 3
+  threshold_changed: 5
+  headless: true
+```
+
+Or set the base URL in `.wup.env` in the project root (not committed to git):
+
+```bash
+# .wup.env
+WUP_BASE_URL=http://localhost:8100
+```
+
+### Output
+
+- **Snapshots** — `.wup/visual-snapshots/<service>/<page>.json`
+- **Diff events** — `.wup/visual-diffs/<service>/<page>.jsonl` (appended on each change)
+
+Visible in `wup status` as a "Visual DOM diffs" section.
+
+### Graceful degradation
+
+If Playwright is not installed, the visual diff module logs a warning and skips scanning — it does **not** break the watcher.
+
+## Web Dashboard (wup-web)
+
+Optional FastAPI backend that receives events from WUP agents and renders a live dashboard.
+
+### Run
+
+```bash
+pip install -e wup-web/
+wup-web --reload --port 8000
+```
+
+Open <http://localhost:8000/> to see regressions, passes, anomalies, visual diffs, and health transitions in real time.
+
+### Configure agent → backend
+
+```yaml
+# wup.yaml
+web:
+  enabled: true
+  endpoint: "http://localhost:8000"
+  timeout_s: 2.0
+```
+
+Or via env:
+
+```bash
+export WUP_WEB_ENDPOINT=http://localhost:8000
+```
+
+The agent fire-and-forgets `REGRESSION`, `PASS`, `ANOMALY`, `VISUAL_DIFF`, and `HEALTH_TRANSITION` events. Network errors never break the watcher (soft-fail).
+
+See `wup-web/README.md` for full API reference and driver endpoints (DOM diff, browserless, anomaly).
+
 ## Project Structure
 
 ```
 wup/
 ├── wup/
-│   ├── __init__.py           # Package exports
-│   ├── config.py             # Configuration loader
-│   ├── models/
-│   │   ├── __init__.py       # Models package
-│   │   └── config.py         # Configuration dataclasses
-│   ├── core.py               # WupWatcher implementation
-│   ├── dependency_mapper.py  # Dependency mapping logic
-│   ├── testql_watcher.py     # TestQL integration
-│   └── cli.py                # CLI interface
+│   ├── __init__.py            # Package exports
+│   ├── cli.py                 # CLI: watch, map-deps, status, init, testql-endpoints
+│   ├── config.py              # Config loading/saving + .wup.env support
+│   ├── core.py                # WupWatcher: detection, inference, scheduling
+│   ├── dependency_mapper.py   # DependencyMapper: codebase → deps.json
+│   ├── testql_discovery.py    # TestQLEndpointDiscovery: scenario parsing
+│   ├── testql_watcher.py      # TestQLWatcher: scenario runner + health tracking
+│   ├── visual_diff.py         # VisualDiffer: Playwright DOM snapshot + diff engine
+│   ├── web_client.py          # WebClient: async HTTP event sink → wup-web
+│   └── models/
+│       ├── __init__.py
+│       └── config.py          # Dataclasses: WupConfig, VisualDiffConfig, WebConfig...
+├── wup-web/                   # Optional FastAPI dashboard (separate package)
+│   ├── wup_web/
+│   │   ├── main.py            # FastAPI app
+│   │   ├── routers/           # events, drivers, dashboard
+│   │   ├── storage.py         # EventStore (in-memory + JSONL)
+│   │   └── templates/         # index.html dashboard
+│   └── tests/                 # FastAPI endpoint tests (pytest + TestClient)
 ├── tests/
-│   └── test_wup.py           # Unit tests
+│   ├── test_wup.py            # unit/integration tests (incl. VisualDiffer, config)
+│   ├── test_testql_watcher.py # TestQLWatcher + VisualDiffer integration tests
+│   ├── test_web_client.py     # WebClient + WebConfig tests
+│   └── test_e2e.py            # end-to-end CLI tests
+├── examples/
+│   ├── fastapi-app/           # FastAPI example project
+│   ├── flask-app/             # Flask example project
+│   ├── multi-service/         # Multi-service example
+│   ├── testql_demo.py         # TestQL simulation demo
+│   ├── testql_integration.py  # Custom TestQLWatcher + visual diff example
+│   └── visual_diff_demo.py    # Visual DOM diff demo (no Playwright required)
 ├── docs/
-│   ├── 2.md                  # Refactoring documentation
-│   ├── 3.md                  # Configuration plan
-│   └── TESTQL_INTEGRATION.md # TestQL integration docs
-├── wup.yaml.example          # Example configuration
-├── pyproject.toml           # Package configuration
-└── README.md                 # This file
+│   └── TESTQL_INTEGRATION.md  # TestQL integration guide
+├── testql-scenarios/          # Auto-generated TestQL scenarios
+├── pyproject.toml             # Package config (setuptools)
+└── README.md
 ```
 
 ## Development
@@ -343,23 +415,33 @@ wup/
 
 ```bash
 # Run all tests
-pytest
+python3 -m pytest tests/ -v
+
+# Run specific suite
+python3 -m pytest tests/test_wup.py -v
+python3 -m pytest tests/test_testql_watcher.py -v
 
 # Run with coverage
-pytest --cov=wup
+python3 -m pytest tests/ --cov=wup
+```
 
-# Run specific test
-pytest tests/test_wup.py::TestDependencyMapper::test_init
+### Examples
+
+```bash
+# Visual diff demo (no Playwright required)
+python3 examples/visual_diff_demo.py
+
+# With live page scan (requires playwright)
+python3 examples/visual_diff_demo.py http://localhost:8100/health
+
+# TestQL + visual diff integration
+python3 examples/testql_integration.py /path/to/project
 ```
 
-### Building for Distribution
+### Building & Publishing
 
 ```bash
-# Build wheel and source distribution
 python -m build
-
-# Install from dist
-pip install dist/wup-0.1.6-py3-none-any.whl
 ```
 
 ## License

{wup-0.2.14 → wup-0.2.16}/README.md

@@ -3,17 +3,17 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.14-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$2.25-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-3.2h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.16-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$2.55-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-4.5h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $2.2500 (15 commits)
-- 👤 **Human dev:** ~$324 (3.2h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $2.5500 (17 commits)
+- 👤 **Human dev:** ~$445 (4.5h @ $100/h, 30min dedup)
 
 Generated on 2026-04-29 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.14-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-wup-blue) ![Version](https://img.shields.io/badge/version-0.2.16-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 **WUP (What's Up)** - Intelligent file watcher for regression testing in large projects.
 
@@ -259,56 +259,128 @@ export WUP_CPU_THROTTLE=0.5
 export WUP_DEBOUNCE=3
 ```
 
-## Integration with Test Frameworks
-
-WUP is designed to work with any test framework. The current implementation includes placeholder test methods that you can customize:
-
-```python
-# In wup/core.py, customize these methods:
-
-async def run_quick_test(self, service: str, endpoints: List[str]) -> bool:
-    # Integrate with your test framework (pytest, unittest, TestQL, etc.)
-    # Example:
-    result = subprocess.run([
-        "pytest", f"tests/{service}/test_smoke.py",
-        "--maxfail=1", "-q"
-    ])
-    return result.returncode == 0
-
-async def run_detail_test(self, service: str, endpoints: List[str]) -> Dict:
-    # Run full test suite with blame reporting
-    # Example:
-    result = subprocess.run([
-        "pytest", f"tests/{service}/",
-        "--cov", f"app/{service}",
-        "--cov-report=json"
-    ])
-    return parse_coverage_report("coverage.json")
+## Visual DOM Diff
+
+WUP optionally scans configured pages with Playwright after each successful quick test, compares the DOM structure to the previous snapshot, and reports significant changes.
+
+### Setup
+
+```bash
+pip install playwright
+playwright install chromium
 ```
 
+### Configuration
+
+```yaml
+visual_diff:
+  enabled: true
+  base_url: "http://localhost:8100"   # or leave empty and set WUP_BASE_URL env var
+  base_url_env: "WUP_BASE_URL"
+  delay_seconds: 5.0      # wait after file change before scanning
+  max_depth: 10            # DOM snapshot depth
+  pages:
+    - "/health"
+    - "/dashboard"
+  pages_from_endpoints: true   # also scan endpoints from testql config
+  threshold_added: 3           # min node additions to report as "changed"
+  threshold_removed: 3
+  threshold_changed: 5
+  headless: true
+```
+
+Or set the base URL in `.wup.env` in the project root (not committed to git):
+
+```bash
+# .wup.env
+WUP_BASE_URL=http://localhost:8100
+```
+
+### Output
+
+- **Snapshots** — `.wup/visual-snapshots/<service>/<page>.json`
+- **Diff events** — `.wup/visual-diffs/<service>/<page>.jsonl` (appended on each change)
+
+Visible in `wup status` as a "Visual DOM diffs" section.
+
+### Graceful degradation
+
+If Playwright is not installed, the visual diff module logs a warning and skips scanning — it does **not** break the watcher.
+
+## Web Dashboard (wup-web)
+
+Optional FastAPI backend that receives events from WUP agents and renders a live dashboard.
+
+### Run
+
+```bash
+pip install -e wup-web/
+wup-web --reload --port 8000
+```
+
+Open <http://localhost:8000/> to see regressions, passes, anomalies, visual diffs, and health transitions in real time.
+
+### Configure agent → backend
+
+```yaml
+# wup.yaml
+web:
+  enabled: true
+  endpoint: "http://localhost:8000"
+  timeout_s: 2.0
+```
+
+Or via env:
+
+```bash
+export WUP_WEB_ENDPOINT=http://localhost:8000
+```
+
+The agent fire-and-forgets `REGRESSION`, `PASS`, `ANOMALY`, `VISUAL_DIFF`, and `HEALTH_TRANSITION` events. Network errors never break the watcher (soft-fail).
+
+See `wup-web/README.md` for full API reference and driver endpoints (DOM diff, browserless, anomaly).
+
 ## Project Structure
 
 ```
 wup/
 ├── wup/
-│   ├── __init__.py           # Package exports
-│   ├── config.py             # Configuration loader
-│   ├── models/
-│   │   ├── __init__.py       # Models package
-│   │   └── config.py         # Configuration dataclasses
-│   ├── core.py               # WupWatcher implementation
-│   ├── dependency_mapper.py  # Dependency mapping logic
-│   ├── testql_watcher.py     # TestQL integration
-│   └── cli.py                # CLI interface
+│   ├── __init__.py            # Package exports
+│   ├── cli.py                 # CLI: watch, map-deps, status, init, testql-endpoints
+│   ├── config.py              # Config loading/saving + .wup.env support
+│   ├── core.py                # WupWatcher: detection, inference, scheduling
+│   ├── dependency_mapper.py   # DependencyMapper: codebase → deps.json
+│   ├── testql_discovery.py    # TestQLEndpointDiscovery: scenario parsing
+│   ├── testql_watcher.py      # TestQLWatcher: scenario runner + health tracking
+│   ├── visual_diff.py         # VisualDiffer: Playwright DOM snapshot + diff engine
+│   ├── web_client.py          # WebClient: async HTTP event sink → wup-web
+│   └── models/
+│       ├── __init__.py
+│       └── config.py          # Dataclasses: WupConfig, VisualDiffConfig, WebConfig...
+├── wup-web/                   # Optional FastAPI dashboard (separate package)
+│   ├── wup_web/
+│   │   ├── main.py            # FastAPI app
+│   │   ├── routers/           # events, drivers, dashboard
+│   │   ├── storage.py         # EventStore (in-memory + JSONL)
+│   │   └── templates/         # index.html dashboard
+│   └── tests/                 # FastAPI endpoint tests (pytest + TestClient)
 ├── tests/
-│   └── test_wup.py           # Unit tests
+│   ├── test_wup.py            # unit/integration tests (incl. VisualDiffer, config)
+│   ├── test_testql_watcher.py # TestQLWatcher + VisualDiffer integration tests
+│   ├── test_web_client.py     # WebClient + WebConfig tests
+│   └── test_e2e.py            # end-to-end CLI tests
+├── examples/
+│   ├── fastapi-app/           # FastAPI example project
+│   ├── flask-app/             # Flask example project
+│   ├── multi-service/         # Multi-service example
+│   ├── testql_demo.py         # TestQL simulation demo
+│   ├── testql_integration.py  # Custom TestQLWatcher + visual diff example
+│   └── visual_diff_demo.py    # Visual DOM diff demo (no Playwright required)
 ├── docs/
-│   ├── 2.md                  # Refactoring documentation
-│   ├── 3.md                  # Configuration plan
-│   └── TESTQL_INTEGRATION.md # TestQL integration docs
-├── wup.yaml.example          # Example configuration
-├── pyproject.toml           # Package configuration
-└── README.md                 # This file
+│   └── TESTQL_INTEGRATION.md  # TestQL integration guide
+├── testql-scenarios/          # Auto-generated TestQL scenarios
+├── pyproject.toml             # Package config (setuptools)
+└── README.md
 ```
 
 ## Development
@@ -317,23 +389,33 @@ wup/
 
 ```bash
 # Run all tests
-pytest
+python3 -m pytest tests/ -v
+
+# Run specific suite
+python3 -m pytest tests/test_wup.py -v
+python3 -m pytest tests/test_testql_watcher.py -v
 
 # Run with coverage
-pytest --cov=wup
+python3 -m pytest tests/ --cov=wup
+```
 
-# Run specific test
-pytest tests/test_wup.py::TestDependencyMapper::test_init
+### Examples
+
+```bash
+# Visual diff demo (no Playwright required)
+python3 examples/visual_diff_demo.py
+
+# With live page scan (requires playwright)
+python3 examples/visual_diff_demo.py http://localhost:8100/health
+
+# TestQL + visual diff integration
+python3 examples/testql_integration.py /path/to/project
 ```
 
-### Building for Distribution
+### Building & Publishing
 
 ```bash
-# Build wheel and source distribution
 python -m build
-
-# Install from dist
-pip install dist/wup-0.1.6-py3-none-any.whl
 ```
 
 ## License

{wup-0.2.14 → wup-0.2.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wup"
-version = "0.2.14"
+version = "0.2.16"
 description = "WUP (What's Up) - Intelligent file watcher for regression testing in large projects"
 readme = "README.md"
 requires-python = ">=3.9"

{wup-0.2.14 → wup-0.2.16}/tests/test_testql_watcher.py

@@ -6,7 +6,7 @@ from pathlib import Path
 from subprocess import CompletedProcess
 
 from wup.testql_watcher import TestQLWatcher
-from wup.models.config import WupConfig, ProjectConfig, TestQLConfig
+from wup.models.config import WupConfig, ProjectConfig, TestQLConfig, VisualDiffConfig
 
 
 def test_process_changed_file_creates_track_on_failure():
@@ -199,3 +199,57 @@ def test_service_health_transitions_are_persisted():
         statuses = [event.get("status") for event in events if event.get("service") == "connect-config"]
         assert "down" in statuses
         assert "up" in statuses
+
+
+def test_visual_differ_disabled_by_default():
+    """visual_differ exists but is disabled (no-op) when visual_diff.enabled=False."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        root = Path(tmpdir)
+        cfg = WupConfig(
+            project=ProjectConfig(name="demo"),
+            testql=TestQLConfig(scenario_dir="testql-scenarios"),
+            visual_diff=VisualDiffConfig(enabled=False),
+        )
+
+        watcher = TestQLWatcher(
+            project_root=str(root),
+            deps_file=str(root / "deps.json"),
+            scenarios_dir="testql-scenarios",
+            track_dir=".wup/tracks",
+            config=cfg,
+        )
+
+        # Differ is created but flagged disabled — run_for_service() must be a no-op
+        assert watcher.visual_differ is not None
+        assert watcher.visual_differ.cfg.enabled is False
+        results = asyncio.run(watcher.visual_differ.run_for_service("svc", ["/x"]))
+        assert results == []
+
+
+def test_visual_differ_initialized_when_enabled():
+    """When visual_diff.enabled=True, TestQLWatcher.visual_differ is a VisualDiffer."""
+    from wup.visual_diff import VisualDiffer
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        root = Path(tmpdir)
+        cfg = WupConfig(
+            project=ProjectConfig(name="demo"),
+            testql=TestQLConfig(scenario_dir="testql-scenarios"),
+            visual_diff=VisualDiffConfig(
+                enabled=True,
+                base_url="http://localhost:9000",
+                pages=["/dashboard"],
+            ),
+        )
+
+        watcher = TestQLWatcher(
+            project_root=str(root),
+            deps_file=str(root / "deps.json"),
+            scenarios_dir="testql-scenarios",
+            track_dir=".wup/tracks",
+            config=cfg,
+        )
+
+        assert isinstance(watcher.visual_differ, VisualDiffer)
+        assert watcher.visual_differ.cfg.enabled is True
+        assert watcher.visual_differ.base_url == "http://localhost:9000"