feat: improvements for PyPI publishing and testing

README.md

@@ -6,7 +6,7 @@ Built with **FastMCP** leveraging the latest MCP spec (2025-11-25) features.
 
 ## ✨ What It Does
 
-```
+```text
 YOU: "Watch the modal animation on this page"
      ↓
 ANIMAWATCH:
@@ -41,6 +41,12 @@ RESULT: "Jank detected at 1.2s - fade-in stutters for 180ms"
 | `analyze_video` | 🎥 Analyze an existing video file |
 | `record` | ⏺️ Just record without analysis |
 | `check_accessibility` | ♿ Visual accessibility analysis |
+| `list_devices` | 📱 List available device profiles for emulation |
+| `watch_with_device` | 📲 Watch with mobile/tablet device emulation |
+| `compare_screenshots` | 🔍 Visual diff comparison between two URLs |
+| `analyze_fps` | 🎯 FPS consistency and jank detection |
+| `get_performance_metrics` | 📊 Core Web Vitals (LCP, FCP, CLS, TTFB) |
+| `analyze_with_consensus_tool` | 🤝 Multi-model consensus analysis |
 
 ### Resources
 
@@ -84,6 +90,7 @@ cp .env.example .env
 ### 4. Add to Your MCP Client
 
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
 ```json
 {
   "mcpServers": {
@@ -99,6 +106,7 @@ cp .env.example .env
 ```
 
 **Augment Code** (settings):
+
 ```json
 {
   "mcpServers": {
@@ -116,30 +124,71 @@ cp .env.example .env
 ## 📖 Usage Examples
 
 ### Watch Animation Issues
-```
+
+```text
 "Watch the modal animation on https://example.com for any jank"
 ```
 
 ### Perform Actions Then Watch
-```
+
+```text
 "Click the hamburger menu on https://example.com and watch the slide-in animation"
 ```
 
 ### Focus on Specific Area
-```
+
+```text
 "Watch https://example.com with focus on scroll behavior"
 ```
 
 ### Accessibility Check
-```
+
+```text
 "Check accessibility on https://example.com"
 ```
 
 ### Access Previous Results
-```
+
+```text
 "Show me the analysis from animawatch://analyses/abc123"
 ```
 
+### Test on Mobile Device
+
+```text
+"Watch https://example.com on an iPhone 15 Pro and check for animation issues"
+```
+
+### Compare Before/After
+
+```text
+"Compare screenshots of https://staging.example.com and https://example.com for visual differences"
+```
+
+### Check Performance Metrics
+
+```text
+"Get Core Web Vitals for https://example.com"
+```
+
+### Analyze FPS
+
+```text
+"Analyze the FPS of this video recording for frame drops"
+```
+
+### Multi-Model Consensus
+
+```text
+"Analyze https://example.com using both Gemini and Ollama for higher accuracy"
+```
+
+### List Available Devices
+
+```text
+"What mobile devices can I test with?"
+```
+
 ## 🔧 Configuration
 
 | Environment Variable | Default | Description |
@@ -180,25 +229,31 @@ export OLLAMA_MODEL=qwen2.5-vl:7b
 
 ## 🏗️ Architecture
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                       AnimaWatch                            │
-│                    (FastMCP Server)                         │
-├─────────────────────────────────────────────────────────────┤
-│  Lifespan Context (AppContext)                              │
-│  ├── BrowserRecorder (Playwright)                           │
-│  ├── VisionProvider (Gemini/Ollama)                         │
-│  ├── recordings: dict[id, Path]                             │
-│  └── analyses: dict[id, str]                                │
-├─────────────────────────────────────────────────────────────┤
-│  Tools       │  Resources              │  Prompts           │
-│  ─────────   │  ─────────────────────  │  ──────────────    │
-│  watch       │  animawatch://recordings│  animation_diagnosis│
-│  screenshot  │  animawatch://analyses  │  page_analysis     │
-│  record      │  animawatch://config    │  accessibility_check│
-│  analyze_video│                        │                    │
-│  check_access│                         │                    │
-└─────────────────────────────────────────────────────────────┘
+```text
+┌──────────────────────────────────────────────────────────────────────────┐
+│                            AnimaWatch                                    │
+│                         (FastMCP Server)                                 │
+├──────────────────────────────────────────────────────────────────────────┤
+│  Lifespan Context (AppContext)                                           │
+│  ├── BrowserRecorder (Playwright)                                        │
+│  ├── VisionProvider (Gemini/Ollama)                                      │
+│  ├── recordings: dict[id, Path]                                          │
+│  └── analyses: dict[id, str]                                             │
+├──────────────────────────────────────────────────────────────────────────┤
+│  Core Tools          │  Device & Performance   │  Comparison & Accuracy  │
+│  ──────────────────  │  ────────────────────   │  ────────────────────   │
+│  watch               │  list_devices           │  compare_screenshots    │
+│  screenshot          │  watch_with_device      │  analyze_with_consensus │
+│  record              │  analyze_fps            │                         │
+│  analyze_video       │  get_performance_metrics│                         │
+│  check_accessibility │                         │                         │
+├──────────────────────────────────────────────────────────────────────────┤
+│  Resources                    │  Prompts                                 │
+│  ───────────────────────────  │  ─────────────────────────────────────── │
+│  animawatch://recordings/{id} │  animation_diagnosis                     │
+│  animawatch://analyses/{id}   │  page_analysis                           │
+│  animawatch://config          │  accessibility_check                     │
+└──────────────────────────────────────────────────────────────────────────┘
 ```
 
 ## 📄 License

pyproject.toml

@@ -8,14 +8,37 @@ requires-python = ">=3.11"
 authors = [
     { name = "Rishi Tank", email = "3771081+rishitank@users.noreply.github.com" }
 ]
-keywords = ["mcp", "animation", "visual-testing", "playwright", "gemini", "ai-vision", "ui-testing", "fastmcp"]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "animation",
+    "visual-testing",
+    "playwright",
+    "gemini",
+    "ai-vision",
+    "ui-testing",
+    "fastmcp",
+    "web-vitals",
+    "performance",
+    "accessibility",
+    "browser-automation",
+    "claude",
+    "llm",
+]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
 ]
 
 dependencies = [

src/animawatch/diff.py

@@ -8,7 +8,7 @@
 from dataclasses import dataclass
 from pathlib import Path
 
-from PIL import Image, ImageChops, ImageDraw
+from PIL import Image, ImageChops
 
 
 @dataclass
@@ -74,7 +74,7 @@ def compare_images(
     diff_sum = 0
 
     # Get pixel data as a flat list for grayscale image
-    pixel_data = list(diff_gray.getdata())
+    pixel_data = diff_gray.tobytes()
     for pixel_value in pixel_data:
         # For grayscale ("L" mode), pixels are single int values
         pixel_diff = int(pixel_value)
@@ -129,7 +129,7 @@ def _find_diff_regions(
 
     # Calculate region difference score
     region = diff_gray.crop(bbox)
-    pixels = list(region.getdata())
+    pixels = region.tobytes()
     avg_diff = sum(pixels) / len(pixels) if pixels else 0
     difference_score = (avg_diff / 255) * 100
 
@@ -152,22 +152,16 @@ def _generate_diff_image(
     highlight_color: tuple[int, int, int, int],
 ) -> Path:
     """Generate a diff image with highlighted changes."""
-    # Create a copy of the "after" image
-    result = after.copy()
-
-    # Create an overlay for highlighting
-    overlay = Image.new("RGBA", result.size, (0, 0, 0, 0))
-    draw = ImageDraw.Draw(overlay)
-
-    # Highlight differing pixels using getpixel for type safety
-    for x in range(diff_gray.width):
-        for y in range(diff_gray.height):
-            pixel_value = diff_gray.getpixel((x, y))
-            if isinstance(pixel_value, int) and pixel_value > threshold:
-                draw.point((x, y), fill=highlight_color)
-
-    # Composite the overlay onto the result
-    result = Image.alpha_composite(result.convert("RGBA"), overlay)
+    # Mask of differing pixels: 255 where the difference exceeds the threshold.
+    # Image.point runs in C, unlike a per-pixel getpixel loop in Python.
+    mask = diff_gray.point(lambda p: 255 if p > threshold else 0)
+
+    # Transparent overlay with the highlight colour painted only under the mask
+    overlay = Image.new("RGBA", after.size, (0, 0, 0, 0))
+    overlay.paste(highlight_color, (0, 0, *after.size), mask)
+
+    # Composite the overlay onto the "after" image
+    result = Image.alpha_composite(after.convert("RGBA"), overlay)
 
     # Save to temp file
     fd, tmp_path = tempfile.mkstemp(suffix="_diff.png")

tests/conftest.py

@@ -0,0 +1,60 @@
+"""Shared pytest fixtures for AnimaWatch tests."""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from animawatch.server import AppContext
+
+
+@pytest.fixture
+def mock_page() -> MagicMock:
+    """A Playwright ``Page`` stand-in with awaitable navigation and evaluation."""
+    page = MagicMock()
+    page.goto = AsyncMock()
+    page.evaluate = AsyncMock(return_value={})
+    return page
+
+
+@pytest.fixture
+def mock_app_context(mock_page: MagicMock, tmp_path: Path) -> AppContext:
+    """An AppContext whose browser and vision provider are mocks.
+
+    ``browser.pooled_context`` behaves like the real async context manager: calling
+    it returns an object usable in ``async with`` that yields ``(context, page)``.
+    It is wrapped in a ``MagicMock`` so tests can assert how it was called.
+    """
+    mock_browser = AsyncMock()
+    # Paths live under tmp_path so tools that unlink them can't touch real files.
+    mock_browser.record_interaction = AsyncMock(return_value=tmp_path / "video.webm")
+    mock_browser.take_screenshot = AsyncMock(return_value=tmp_path / "screenshot.png")
+
+    @asynccontextmanager
+    async def pooled_context(*_args: Any, **_kwargs: Any) -> AsyncIterator[tuple[Any, Any]]:
+        """Yield a ``(context, page)`` pair like ``BrowserRecorder.pooled_context``."""
+        yield (MagicMock(), mock_page)
+
+    mock_browser.pooled_context = MagicMock(side_effect=pooled_context)
+
+    mock_vision = AsyncMock()
+    mock_vision.analyze_video = AsyncMock(return_value="Video analysis result")
+    mock_vision.analyze_image = AsyncMock(return_value="Image analysis result")
+
+    return AppContext(
+        browser=mock_browser,
+        vision=mock_vision,
+        recordings={},
+        analyses={},
+    )
+
+
+@pytest.fixture
+def mock_ctx(mock_app_context: AppContext) -> MagicMock:
+    """A tool ``Context`` whose lifespan context is ``mock_app_context``."""
+    ctx = MagicMock()
+    ctx.request_context.lifespan_context = mock_app_context
+    return ctx

tests/test_diff.py

@@ -4,7 +4,7 @@
 from pathlib import Path
 
 import pytest
-from PIL import Image
+from PIL import Image, ImageChops
 
 from animawatch.diff import (
     DiffRegion,
@@ -113,6 +113,46 @@ def test_diff_image_generation(self, different_images: tuple[Path, Path]) -> Non
         assert result.diff_image_path.exists()
         result.diff_image_path.unlink(missing_ok=True)
 
+    @pytest.mark.parametrize(
+        "highlight_color", [(0, 0, 255, 255), (255, 0, 0, 128)], ids=["opaque", "translucent"]
+    )
+    def test_diff_image_highlights_exactly_pixels_above_threshold(
+        self, tmp_path: Path, highlight_color: tuple[int, int, int, int]
+    ) -> None:
+        """The diff image is the "after" image with only above-threshold pixels overlaid."""
+        threshold = 5
+        before = Image.new("RGB", (50, 50), "white")
+        after = before.copy()
+        after.paste((255, 0, 0), (10, 10, 20, 20))  # strong difference
+        after.paste((250, 250, 250), (30, 30, 40, 40))  # grey diff of exactly `threshold`
+        before_path, after_path = tmp_path / "before.png", tmp_path / "after.png"
+        before.save(before_path)
+        after.save(after_path)
+
+        result = compare_images(
+            before_path, after_path, threshold=threshold, highlight_color=highlight_color
+        )
+        assert result.diff_image_path is not None
+        try:
+            actual = Image.open(result.diff_image_path).convert("RGBA")
+
+            # Reference: overlay the highlight pixel by pixel wherever the grayscale
+            # difference is strictly greater than the threshold.
+            diff_gray = ImageChops.difference(before, after).convert("L")
+            overlay = Image.new("RGBA", after.size, (0, 0, 0, 0))
+            for x in range(after.width):
+                for y in range(after.height):
+                    value = diff_gray.getpixel((x, y))
+                    if isinstance(value, int) and value > threshold:
+                        overlay.putpixel((x, y), highlight_color)
+            expected = Image.alpha_composite(after.convert("RGBA"), overlay)
+
+            assert actual.tobytes() == expected.tobytes()
+            assert actual.getpixel((35, 35)) == (250, 250, 250, 255)  # at threshold: untouched
+            assert actual.getpixel((0, 0)) == (255, 255, 255, 255)  # unchanged: untouched
+        finally:
+            result.diff_image_path.unlink(missing_ok=True)
+
     def test_result_paths(self, identical_images: tuple[Path, Path]) -> None:
         """Test that result contains correct paths."""
         before, after = identical_images