# Visual Regression Testing

Browser Hybrid supports visual regression testing through pixel-by-pixel screenshot comparison. This enables you to detect UI changes, rendering glitches, or layout shifts between different versions of your application.

## Installation

Visual comparison requires the `compare` extra dependencies:

```bash
pip install browser-hybrid[compare]
```

Or install `Pillow` and `numpy` manually.

## Basic Comparison

To compare two existing screenshots:

```python
from browser_hybrid import Browser

browser = Browser()
result = browser.compare_screenshots("baseline.png", "current.png")

if result.match:
    print("Screenshots match exactly!")
else:
    print(f"Differences detected: {result.diff_percentage:.2f}%")
    print(f"Total differing pixels: {result.diff_pixels}")
```

## Tolerance Thresholds

UI rendering can vary slightly due to anti-aliasing, font rendering updates, or minor browser version changes. You can set a `threshold` (0.0 to 100.0) to allow a certain percentage of differing pixels.

```python
# Allow up to 0.5% difference
result = browser.assert_visual_match("baseline.png", threshold=0.5)
```

## Visual Diffs

When a comparison fails, it's often helpful to see exactly what changed. Use the `output_diff` parameter to generate a "diff" image where differences are highlighted in red.

```python
result = browser.compare_screenshots(
    "baseline.png", 
    "current.png", 
    output_diff="diff.png"
)
```

## Partial Comparison (Regions)

If you only want to compare a specific part of the page (e.g., a header or a specific widget), use the `region` parameter.

```python
# Compare a 500x400 area starting at (100, 100)
result = browser.compare_screenshots(
    "baseline.png",
    "current.png",
    region=(100, 100, 500, 400) # x, y, width, height
)
```

## CI/CD Workflow

The most common way to use this is with `assert_visual_match` in your test suite.

```python
def test_dashboard_visual():
    browser = Browser()
    browser.goto("https://myapp.com/dashboard")
    
    # This will raise AssertionError if they don't match
    browser.assert_visual_match("tests/baselines/dashboard.png", threshold=0.1)
```

### Updating Baselines

If you intentionally changed your UI, you can update your baseline screenshots by setting `update_baseline=True`.

```python
# Run once with this flag to update 'dashboard.png' with current view
browser.assert_visual_match("tests/baselines/dashboard.png", update_baseline=True)
```

## Comparison Metrics

The `ComparisonResult` object provides detailed information:

| Property | Description |
|----------|-------------|
| `match` | `True` if `diff_percentage <= threshold` |
| `diff_pixels` | Total count of pixels that changed |
| `diff_percentage` | Percentage of changed pixels (0.0 - 100.0) |
| `baseline_size` | Tuple of (width, height) for baseline |
| `current_size` | Tuple of (width, height) for current |
| `diff_path` | Path to the generated diff image, if any |
| `message` | Human-readable summary of the result |
