wup 0.2.14__tar.gz → 0.2.15__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wup
-Version: 0.2.14
+Version: 0.2.15
 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.15-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.40-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-4.1h-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.4000 (16 commits)
+- 👤 **Human dev:** ~$411 (4.1h @ $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.15-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,86 @@ 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.
+
 ## 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
+│   └── models/
+│       ├── __init__.py
+│       └── config.py          # Dataclasses: WupConfig, VisualDiffConfig, TestQLConfig...
 ├── tests/
-│   └── test_wup.py           # Unit tests
+│   ├── test_wup.py            # unit/integration tests (incl. VisualDiffer, config)
+│   ├── test_testql_watcher.py # TestQLWatcher + VisualDiffer integration 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 +373,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
+```
+
+### 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
 
-# Run specific test
-pytest tests/test_wup.py::TestDependencyMapper::test_init
+# 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.15}/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.15-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.40-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-4.1h-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.4000 (16 commits)
+- 👤 **Human dev:** ~$411 (4.1h @ $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.15-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,86 @@ 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.
+
 ## 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
+│   └── models/
+│       ├── __init__.py
+│       └── config.py          # Dataclasses: WupConfig, VisualDiffConfig, TestQLConfig...
 ├── tests/
-│   └── test_wup.py           # Unit tests
+│   ├── test_wup.py            # unit/integration tests (incl. VisualDiffer, config)
+│   ├── test_testql_watcher.py # TestQLWatcher + VisualDiffer integration 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 +347,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
+```
+
+### 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
 
-# Run specific test
-pytest tests/test_wup.py::TestDependencyMapper::test_init
+# 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.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wup"
-version = "0.2.14"
+version = "0.2.15"
 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.15}/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"

{wup-0.2.14 → wup-0.2.15}/tests/test_wup.py

@@ -18,8 +18,10 @@ from wup.models.config import (
     NotifyConfig,
     ServiceTestConfig,
     ProjectConfig,
+    VisualDiffConfig,
 )
 from wup.testql_watcher import TestQLWatcher
+from wup.visual_diff import VisualDiffer, _diff_snapshots, _page_slug, _resolve_base_url
 
 
 class TestDependencyMapper:
@@ -921,6 +923,162 @@ class TestConfigModels:
         assert config.project.name == "test"
         assert len(config.services) == 1
         assert config.services[0].name == "users"
+        # visual_diff is auto-populated with defaults
+        assert isinstance(config.visual_diff, VisualDiffConfig)
+        assert config.visual_diff.enabled is False
+
+    def test_visual_diff_config_defaults(self):
+        """Test VisualDiffConfig has sensible defaults."""
+        cfg = VisualDiffConfig()
+        assert cfg.enabled is False
+        assert cfg.base_url == ""
+        assert cfg.base_url_env == "WUP_BASE_URL"
+        assert cfg.delay_seconds == 5.0
+        assert cfg.max_depth == 10
+        assert cfg.snapshot_dir == ".wup/visual-snapshots"
+        assert cfg.diff_dir == ".wup/visual-diffs"
+        assert cfg.pages == []
+        assert cfg.pages_from_endpoints is True
+        assert cfg.headless is True
+
+    def test_visual_diff_config_custom(self):
+        """Test VisualDiffConfig with custom values."""
+        cfg = VisualDiffConfig(
+            enabled=True,
+            base_url="http://localhost:9000",
+            pages=["/dashboard", "/users"],
+            threshold_added=10,
+        )
+        assert cfg.enabled is True
+        assert cfg.base_url == "http://localhost:9000"
+        assert cfg.pages == ["/dashboard", "/users"]
+        assert cfg.threshold_added == 10
+
+
+class TestVisualDiffer:
+    """Tests for the VisualDiffer class (no Playwright required)."""
+
+    def test_resolve_base_url_from_config(self):
+        cfg = VisualDiffConfig(base_url="http://localhost:8080/")
+        assert _resolve_base_url(cfg) == "http://localhost:8080"
+
+    def test_resolve_base_url_from_env(self, monkeypatch):
+        cfg = VisualDiffConfig(base_url="", base_url_env="MY_VD_URL")
+        monkeypatch.setenv("MY_VD_URL", "http://env-host:1234/")
+        assert _resolve_base_url(cfg) == "http://env-host:1234"
+
+    def test_resolve_base_url_empty(self, monkeypatch):
+        cfg = VisualDiffConfig(base_url="", base_url_env="WUP_VD_NONE")
+        monkeypatch.delenv("WUP_VD_NONE", raising=False)
+        assert _resolve_base_url(cfg) == ""
+
+    def test_page_slug(self):
+        assert _page_slug("http://x/api/v1/users") == "api_v1_users"
+        assert _page_slug("http://x/") == "root"
+
+    def test_pages_for_service_explicit(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cfg = VisualDiffConfig(
+                base_url="http://localhost:8080",
+                pages=["/dashboard"],
+                pages_from_endpoints=False,
+            )
+            differ = VisualDiffer(tmpdir, cfg)
+            pages = differ._pages_for_service("users", ["/api/users"])
+            assert pages == ["http://localhost:8080/dashboard"]
+
+    def test_pages_for_service_from_endpoints(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cfg = VisualDiffConfig(
+                base_url="http://localhost:8080",
+                pages_from_endpoints=True,
+            )
+            differ = VisualDiffer(tmpdir, cfg)
+            pages = differ._pages_for_service("users", ["/api/users", "/api/users/1"])
+            assert "http://localhost:8080/api/users" in pages
+            assert "http://localhost:8080/api/users/1" in pages
+
+    def test_pages_for_service_fallback(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cfg = VisualDiffConfig(
+                base_url="http://localhost:8080",
+                pages_from_endpoints=False,
+            )
+            differ = VisualDiffer(tmpdir, cfg)
+            pages = differ._pages_for_service("users", [])
+            assert pages == ["http://localhost:8080/users"]
+
+    def test_pages_for_service_absolute_url_passthrough(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cfg = VisualDiffConfig(
+                base_url="http://localhost:8080",
+                pages=["https://example.com/health"],
+                pages_from_endpoints=False,
+            )
+            differ = VisualDiffer(tmpdir, cfg)
+            pages = differ._pages_for_service("svc", [])
+            assert pages == ["https://example.com/health"]
+
+    def test_diff_snapshots_baseline(self):
+        new = {"tag": "HTML", "children": [{"tag": "BODY"}]}
+        diff = _diff_snapshots(None, new, max_depth=5,
+                               threshold_added=1, threshold_removed=1, threshold_changed=1)
+        assert diff["status"] == "new"
+
+    def test_diff_snapshots_identical(self):
+        snap = {"tag": "HTML", "children": [{"tag": "BODY", "id": "main"}]}
+        diff = _diff_snapshots(snap, snap, max_depth=5,
+                               threshold_added=1, threshold_removed=1, threshold_changed=1)
+        assert diff["status"] == "ok"
+        assert diff["counts"]["added"] == 0
+        assert diff["counts"]["removed"] == 0
+
+    def test_diff_snapshots_changed(self):
+        old = {"tag": "HTML", "children": [{"tag": "BODY"}]}
+        new = {"tag": "HTML", "children": [
+            {"tag": "BODY"},
+            {"tag": "DIV", "id": "added1"},
+            {"tag": "DIV", "id": "added2"},
+            {"tag": "DIV", "id": "added3"},
+        ]}
+        diff = _diff_snapshots(old, new, max_depth=5,
+                               threshold_added=3, threshold_removed=10, threshold_changed=10)
+        assert diff["status"] == "changed"
+        assert diff["counts"]["added"] >= 3
+
+    def test_run_for_service_disabled_returns_empty(self):
+        """When disabled, run_for_service should be a no-op."""
+        import asyncio
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cfg = VisualDiffConfig(enabled=False)
+            differ = VisualDiffer(tmpdir, cfg)
+            results = asyncio.run(differ.run_for_service("svc", ["/x"]))
+            assert results == []
+
+    def test_get_recent_diffs_empty(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cfg = VisualDiffConfig()
+            differ = VisualDiffer(tmpdir, cfg)
+            assert differ.get_recent_diffs() == []
+
+    def test_get_recent_diffs_filters_by_age(self):
+        import time
+        with tempfile.TemporaryDirectory() as tmpdir:
+            cfg = VisualDiffConfig(diff_dir=".wup/visual-diffs")
+            differ = VisualDiffer(tmpdir, cfg)
+            now = int(time.time())
+            diff_file = differ.diff_dir / "svc" / "page.jsonl"
+            diff_file.parent.mkdir(parents=True, exist_ok=True)
+            diff_file.write_text(
+                json.dumps({"timestamp": now, "service": "svc", "url": "/x",
+                            "diff": {"status": "changed"}}) + "\n"
+                + json.dumps({"timestamp": now - 9999, "service": "svc", "url": "/y",
+                              "diff": {"status": "changed"}}) + "\n",
+                encoding="utf-8",
+            )
+            recent = differ.get_recent_diffs(seconds=300)
+            assert len(recent) == 1
+            assert recent[0]["url"] == "/x"
 
 
 class TestConfigLoader:
@@ -1073,6 +1231,126 @@ project:
             with pytest.raises(ValueError, match="project.name"):
                 load_config(Path(tmpdir), config_path)
 
+    def test_save_and_load_visual_diff_config(self):
+        """Test that visual_diff section is correctly saved and reloaded."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            config = WupConfig(
+                project=ProjectConfig(name="vd-test"),
+                visual_diff=VisualDiffConfig(
+                    enabled=True,
+                    base_url="http://localhost:9000",
+                    pages=["/health", "/users"],
+                    delay_seconds=2.5,
+                    max_depth=6,
+                    threshold_added=7,
+                    threshold_removed=4,
+                    threshold_changed=8,
+                    headless=False,
+                ),
+            )
+            config_path = Path(tmpdir) / "wup.yaml"
+            save_config(config, config_path)
+
+            loaded = load_config(Path(tmpdir), config_path)
+            vd = loaded.visual_diff
+            assert vd.enabled is True
+            assert vd.base_url == "http://localhost:9000"
+            assert vd.pages == ["/health", "/users"]
+            assert vd.delay_seconds == 2.5
+            assert vd.max_depth == 6
+            assert vd.threshold_added == 7
+            assert vd.threshold_removed == 4
+            assert vd.threshold_changed == 8
+            assert vd.headless is False
+
+    def test_load_config_visual_diff_from_yaml(self):
+        """Test parsing visual_diff section from raw YAML."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            yaml_content = """
+project:
+  name: "my-app"
+visual_diff:
+  enabled: true
+  base_url: "http://localhost:8100"
+  base_url_env: "MY_BASE_URL"
+  delay_seconds: 3.0
+  max_depth: 8
+  snapshot_dir: ".wup/snaps"
+  diff_dir: ".wup/diffs"
+  pages:
+    - "/dashboard"
+    - "/settings"
+  pages_from_endpoints: false
+  threshold_added: 5
+  threshold_removed: 2
+  threshold_changed: 9
+  headless: false
+"""
+            config_path = Path(tmpdir) / "wup.yaml"
+            config_path.write_text(yaml_content)
+            config = load_config(Path(tmpdir), config_path)
+            vd = config.visual_diff
+            assert vd.enabled is True
+            assert vd.base_url == "http://localhost:8100"
+            assert vd.base_url_env == "MY_BASE_URL"
+            assert vd.delay_seconds == 3.0
+            assert vd.max_depth == 8
+            assert vd.snapshot_dir == ".wup/snaps"
+            assert vd.diff_dir == ".wup/diffs"
+            assert vd.pages == ["/dashboard", "/settings"]
+            assert vd.pages_from_endpoints is False
+            assert vd.threshold_added == 5
+            assert vd.threshold_removed == 2
+            assert vd.threshold_changed == 9
+            assert vd.headless is False
+
+    def test_load_config_visual_diff_defaults_when_section_absent(self):
+        """visual_diff section absent → all defaults used."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            config_path = Path(tmpdir) / "wup.yaml"
+            config_path.write_text("project:\n  name: x\n")
+            config = load_config(Path(tmpdir), config_path)
+            vd = config.visual_diff
+            assert vd.enabled is False
+            assert vd.base_url == ""
+            assert vd.max_depth == 10
+            assert vd.pages == []
+            assert vd.headless is True
+
+    def test_load_dotenv_sets_env_var(self):
+        """_load_dotenv should load .wup.env into os.environ."""
+        import os
+        from wup.config import _load_dotenv
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            env_file = root / ".wup.env"
+            env_file.write_text('WUP_TEST_DUMMY_VAR=hello_wup\n# comment\n', encoding="utf-8")
+            existing = os.environ.pop("WUP_TEST_DUMMY_VAR", None)
+            try:
+                _load_dotenv(root)
+                assert os.environ.get("WUP_TEST_DUMMY_VAR") == "hello_wup"
+            finally:
+                os.environ.pop("WUP_TEST_DUMMY_VAR", None)
+                if existing is not None:
+                    os.environ["WUP_TEST_DUMMY_VAR"] = existing
+
+    def test_load_dotenv_does_not_overwrite_existing(self):
+        """_load_dotenv must NOT overwrite already-set env vars."""
+        import os
+        from wup.config import _load_dotenv
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            env_file = root / ".wup.env"
+            env_file.write_text('WUP_TEST_NOOVERWRITE=from_file\n', encoding="utf-8")
+            os.environ["WUP_TEST_NOOVERWRITE"] = "original"
+            try:
+                _load_dotenv(root)
+                assert os.environ["WUP_TEST_NOOVERWRITE"] == "original"
+            finally:
+                os.environ.pop("WUP_TEST_NOOVERWRITE", None)
+
 
 class TestConfigIntegration:
     """Tests for configuration integration with WupWatcher."""

{wup-0.2.14 → wup-0.2.15}/wup/__init__.py

@@ -7,7 +7,7 @@ WUP monitors file changes and runs intelligent regression tests using a 3-layer
 3. Detail Layer: Full tests with blame reports (only on failure)
 """
 
-__version__ = "0.2.14"
+__version__ = "0.2.15"
 __author__ = "Tom Sapletta"
 
 from .config import load_config, save_config, get_default_config

{wup-0.2.14 → wup-0.2.15}/wup/config.py

@@ -183,12 +183,31 @@ def validate_config(raw: dict) -> WupConfig:
 
     # Parse visual_diff config
     vd_raw = raw.get("visual_diff", {})
+    env_visual_enabled = os.environ.get("WUP_VISUAL_DIFF_ENABLED")
+    env_visual_delay = os.environ.get("WUP_VISUAL_DIFF_DELAY_SECONDS")
+    env_visual_depth = os.environ.get("WUP_VISUAL_DIFF_MAX_DEPTH")
+
+    if env_visual_enabled is None:
+        visual_enabled = vd_raw.get("enabled", False)
+    else:
+        visual_enabled = env_visual_enabled.strip().lower() in {"1", "true", "yes", "on"}
+
+    if env_visual_delay is None:
+        visual_delay = float(vd_raw.get("delay_seconds", 5.0))
+    else:
+        visual_delay = float(env_visual_delay)
+
+    if env_visual_depth is None:
+        visual_depth = int(vd_raw.get("max_depth", 10))
+    else:
+        visual_depth = int(env_visual_depth)
+
     visual_diff = VisualDiffConfig(
-        enabled=vd_raw.get("enabled", False),
+        enabled=visual_enabled,
         base_url=vd_raw.get("base_url", ""),
         base_url_env=vd_raw.get("base_url_env", "WUP_BASE_URL"),
-        delay_seconds=float(vd_raw.get("delay_seconds", 5.0)),
-        max_depth=int(vd_raw.get("max_depth", 10)),
+        delay_seconds=visual_delay,
+        max_depth=visual_depth,
         snapshot_dir=vd_raw.get("snapshot_dir", ".wup/visual-snapshots"),
         diff_dir=vd_raw.get("diff_dir", ".wup/visual-diffs"),
         pages=vd_raw.get("pages", []),

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wup
-Version: 0.2.14
+Version: 0.2.15
 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.15-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.40-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-4.1h-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.4000 (16 commits)
+- 👤 **Human dev:** ~$411 (4.1h @ $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.15-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,86 @@ 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.
+
 ## 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
+│   └── models/
+│       ├── __init__.py
+│       └── config.py          # Dataclasses: WupConfig, VisualDiffConfig, TestQLConfig...
 ├── tests/
-│   └── test_wup.py           # Unit tests
+│   ├── test_wup.py            # unit/integration tests (incl. VisualDiffer, config)
+│   ├── test_testql_watcher.py # TestQLWatcher + VisualDiffer integration 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 +373,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
+```
+
+### 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
 
-# Run specific test
-pytest tests/test_wup.py::TestDependencyMapper::test_init
+# 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