RustScreenDiffAI

A Rust CLI pixel-diff engine for screenshot regression checks — deterministic PASS/FAIL verdicts.

RustScreenDiffAI (installed as the screendiffai command) compares two images pixel by pixel, calculates the changed-pixel percentage, and returns a clear PASS or FAIL verdict against a configurable threshold.

Table of Contents

• Overview
• Features
• Installation
• Usage
• Included Example
• How It Works
• Example Output
• Threshold Guidance
• Development
• Project Structure
• Documentation
• Release Status
• License
• About

Overview

Visual regressions are easiest to miss when screens look "mostly fine." RustScreenDiffAI provides a deterministic, script-friendly image comparison step that can be used in QA workflows, CI jobs, screenshot tests, and digital signage review pipelines.

Features

• Compares two PNG or image files using the Rust image crate.
• Validates that both screenshots have identical dimensions.
• Counts changed pixels exactly.
• Calculates diff percentage from total pixels.
• Supports configurable pass/fail threshold.
• Emits terminal output for manual review.
• Emits JSON output for automation.
• Handles identical images, partial diffs, full diffs, and dimension mismatch errors.

Installation

From crates.io (recommended)

cargo install screendiffai

From source

git clone https://github.com/SUDARSHANCHAUDHARI/RustScreenDiffAI.git
cd RustScreenDiffAI
cargo build --release

The binary is created at:

target/release/screendiffai

Optional local install from a source checkout:

cargo install --path .

Usage

# Compare two screenshots with the default 1% threshold
screendiffai compare before.png after.png

# Allow up to 5% difference
screendiffai compare before.png after.png --threshold 0.05

# Emit JSON
screendiffai compare before.png after.png --json

# Write a visual diff image with changed pixels highlighted in magenta
screendiffai compare before.png after.png --diff-output diff.png

Included Example

The repository includes two tiny PPM fixtures:

screendiffai compare examples/before.ppm examples/after.ppm --threshold 0.10

screendiffai compare examples/before.ppm examples/after.ppm --diff-output diff.png

Real output:

ScreenDiff Report
Before: examples/before.ppm
After: examples/after.ppm
Total Pixels: 16
Diff Pixels: 1
Diff: 6.25%
Threshold: 10.00%
Verdict: PASS

How It Works

1. Load both images.
2. Verify dimensions match.
3. Compare every pixel pair.
4. Count changed pixels.
5. Calculate diff_percent = diff_pixels / total_pixels.
6. Optionally write a diff image where changed pixels are magenta and unchanged pixels come from the baseline image.
7. Return PASS when diff_percent <= threshold; otherwise return FAIL.

Example Output

ScreenDiff Report
Before:        before.png
After:         after.png
Total Pixels:  10000
Diff Pixels:   42
Diff:          0.42%
Threshold:     1.00%
Verdict:       PASS

Threshold Guidance

Threshold	Typical Use
0.00	Exact pixel match required
0.01	Default, allows up to 1% changed pixels
0.05	Looser check for anti-aliasing or dynamic content

Development

cargo fmt --check
cargo clippy -- -D warnings
cargo test
cargo build --release

The integration tests cover zero diff, full diff, one-pixel changes, threshold behavior, dimension mismatch, CLI output, and visual diff image generation.

Project Structure

src/
  cli.rs          Command-line interface
  diff/           Pixel comparison engine
  report.rs       Verdict and report output
tests/
  integration_test.rs

Documentation

• Architecture
• Roadmap
• Maintainer notes
• Content plan

Release Status

Current release: v1.1.1, published on crates.io.

Each release is verified with formatting, Clippy, tests, an optimized release build, and cargo package before publishing.

License

MIT — see LICENSE.

---

About

I'm Sudarshan Chaudhari, a Senior Quality Engineer, Test Automation specialist, and AI systems builder based in Bangkok, Thailand.

I have 13+ years of experience in software quality engineering, working across SaaS, fintech, gaming, web, mobile, cloud, and digital signage platforms. My background combines hands-on test automation with QA leadership, test strategy, CI/CD, release quality, production investigation, and cross-platform validation.

Alongside my professional QA career, I run SudarshanTechLabs, my independent engineering and product lab where I design, build, test, and ship software across Android, web, AI, cybersecurity, developer tooling, and cross-platform applications.

What I work on

• ⚙️ Quality Engineering & Test Automation — Playwright, Selenium, Cypress, Appium, API testing, automation frameworks, end-to-end testing, CI/CD, release gates, GitHub Actions, risk-based testing, and production validation
• 🤖 AI Systems & Automation — AI agents, multi-agent orchestration, MCP servers, AI-assisted QA, prompt tooling, developer workflows, automation systems, and Claude Code plugins
• 📱 Mobile & Cross-Platform Applications — Android applications built with Kotlin and Jetpack Compose, Google Play releases, automated build and publishing pipelines, and cross-platform development spanning iOS, web, Windows, and macOS
• 🌐 Web Applications & Platforms — Full-stack applications using Next.js, TypeScript, Firebase, Cloudflare, REST APIs, and modern web infrastructure
• 🛠️ Developer Tooling & CLI Engineering — Rust, Python, TypeScript, CLI utilities, multi-repository tooling, build automation, release tooling, and engineering productivity systems
• 🛡️ Cybersecurity & Observability — Threat detection, log analysis, security auditing, vulnerability assessment, monitoring, and security-focused developer tools
• 📺 Digital Signage & Device Platforms — Content validation, playback testing, device compatibility, production investigation, monitoring, and QA across diverse hardware and operating-system environments

My work sits at the intersection of quality engineering, automation, AI, and software development. I approach products with a QA mindset from the beginning: understanding failure modes, designing for testability, automating repetitive work, and building release confidence into the engineering process.

Through SudarshanTechLabs, I also build products and tools from idea to production, covering architecture, development, testing, CI/CD, release automation, monitoring, and ongoing maintenance.

🌐 sudarshantechlabs.com · 💼 LinkedIn · 🐙 GitHub · ✉️ sunny.sudarshan@gmail.com