diffpdf 0.1.2__tar.gz

diffpdf-0.1.2/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

diffpdf-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install package with dev dependencies
+        run: pip install -e .[dev]
+
+      - name: Run ruff
+        run: ruff check .
+
+      - name: Run pytest
+        run: pytest tests/ -v
+
+      - name: Verify version detection
+        run: |
+          VERSION=$(diffpdf --version | sed -n 's/.*version \([0-9]\+\.[0-9]\+\.[0-9]\+\).*/\1/p')
+          if [ "$VERSION" = "0.0.0" ]; then
+            echo "Error: Version is 0.0.0, setuptools-scm failed to detect version"
+            exit 1
+          fi
+          echo "Version detected correctly: $VERSION"
+        shell: bash

diffpdf-0.1.2/.github/workflows/pypi-publish.yml

@@ -0,0 +1,32 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build package
+      run: python -m build
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        verbose: true

diffpdf-0.1.2/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# CLI output
+log.txt
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

diffpdf-0.1.2/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

diffpdf-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Justus Rijke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

diffpdf-0.1.2/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include LICENSE

diffpdf-0.1.2/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: diffpdf
+Version: 0.1.2
+Summary: A tool for comparing PDF files
+Project-URL: Homepage, https://github.com/JustusRijke/DiffPDF
+Project-URL: Issues, https://github.com/JustusRijke/DiffPDF/issues
+Author-email: Justus Rijke <justusrijke@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: colorlog
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pixelmatch>=0.3.0
+Requires-Dist: pymupdf>=1.23.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DiffPDF
+
+[![CI](https://github.com/JustusRijke/DiffPDF/actions/workflows/ci.yml/badge.svg)](https://github.com/JustusRijke/DiffPDF/actions/workflows/ci.yml)
+
+CLI tool for detecting structural, textual, and visual differences between PDF files, for use in automatic regression tests.
+
+## Installation
+
+```bash
+pip install diffpdf
+```
+
+## Usage
+
+```bash
+diffpdf <baseline.pdf> <actual.pdf> [OPTIONS]
+```
+
+## How It Works
+
+DiffPDF uses a fail-fast sequential pipeline to compare PDFs:
+
+1. **Hash Check** - SHA-256 comparison. If identical, exit immediately with pass.
+2. **Page Count** - Verify both PDFs have the same number of pages.
+3. **Text Content** - Extract and compare text from all pages.
+4. **Visual Check** - Render pages to images and compare using pixelmatch.
+
+Each stage only runs if all previous stages pass.
+
+**⚠️ Performance Warning:** The Python port of pixelmatch is extremely slow.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--threshold` | 0.1 | Pixelmatch threshold (0.0-1.0) |
+| `--dpi` | 96 | Render resolution |
+| `--output-dir` | ./ | Directory for diff images |
+| `--debug` | - | Verbose logging |
+| `--save-log` | - | Write log to log.txt |
+
+## Exit Codes
+
+- `0` — Pass (PDFs are equivalent)
+- `1` — Fail (differences detected)
+- `2` — Error (invalid input or processing error)
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest tests/ -v
+ruff check .
+```
+
+## Acknowledgements
+
+Built with [PyMuPDF](https://pymupdf.readthedocs.io/) for PDF parsing and [pixelmatch-py](https://github.com/whtsky/pixelmatch-py) (Python port of [pixelmatch](https://github.com/mapbox/pixelmatch)) for visual comparison.

diffpdf-0.1.2/README.md

@@ -0,0 +1,58 @@
+# DiffPDF
+
+[![CI](https://github.com/JustusRijke/DiffPDF/actions/workflows/ci.yml/badge.svg)](https://github.com/JustusRijke/DiffPDF/actions/workflows/ci.yml)
+
+CLI tool for detecting structural, textual, and visual differences between PDF files, for use in automatic regression tests.
+
+## Installation
+
+```bash
+pip install diffpdf
+```
+
+## Usage
+
+```bash
+diffpdf <baseline.pdf> <actual.pdf> [OPTIONS]
+```
+
+## How It Works
+
+DiffPDF uses a fail-fast sequential pipeline to compare PDFs:
+
+1. **Hash Check** - SHA-256 comparison. If identical, exit immediately with pass.
+2. **Page Count** - Verify both PDFs have the same number of pages.
+3. **Text Content** - Extract and compare text from all pages.
+4. **Visual Check** - Render pages to images and compare using pixelmatch.
+
+Each stage only runs if all previous stages pass.
+
+**⚠️ Performance Warning:** The Python port of pixelmatch is extremely slow.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--threshold` | 0.1 | Pixelmatch threshold (0.0-1.0) |
+| `--dpi` | 96 | Render resolution |
+| `--output-dir` | ./ | Directory for diff images |
+| `--debug` | - | Verbose logging |
+| `--save-log` | - | Write log to log.txt |
+
+## Exit Codes
+
+- `0` — Pass (PDFs are equivalent)
+- `1` — Fail (differences detected)
+- `2` — Error (invalid input or processing error)
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest tests/ -v
+ruff check .
+```
+
+## Acknowledgements
+
+Built with [PyMuPDF](https://pymupdf.readthedocs.io/) for PDF parsing and [pixelmatch-py](https://github.com/whtsky/pixelmatch-py) (Python port of [pixelmatch](https://github.com/mapbox/pixelmatch)) for visual comparison.

diffpdf-0.1.2/hooks/pre-commit

@@ -0,0 +1,59 @@
+#!/bin/sh
+
+if git rev-parse --verify HEAD >/dev/null 2>&1
+then
+	against=HEAD
+else
+	# Initial commit: diff against an empty tree object
+	against=$(git hash-object -t tree /dev/null)
+fi
+
+# If you want to allow non-ASCII filenames set this variable to true.
+allownonascii=$(git config --type=bool hooks.allownonascii)
+
+# Redirect output to stderr.
+exec 1>&2
+
+# Cross platform projects tend to avoid non-ASCII filenames; prevent
+# them from being added to the repository. We exploit the fact that the
+# printable range starts at the space character and ends with tilde.
+if [ "$allownonascii" != "true" ] &&
+	# Note that the use of brackets around a tr range is ok here, (it's
+	# even required, for portability to Solaris 10's /usr/bin/tr), since
+	# the square bracket bytes happen to fall in the designated range.
+	test $(git diff-index --cached --name-only --diff-filter=A -z $against |
+	  LC_ALL=C tr -d '[ -~]\0' | wc -c) != 0
+then
+	cat <<\EOF
+Error: Attempt to add a non-ASCII file name.
+
+This can cause problems if you want to work with people on other platforms.
+
+To be portable it is advisable to rename the file.
+
+If you know what you are doing you can disable this check using:
+
+  git config hooks.allownonascii true
+EOF
+	exit 1
+fi
+
+# Ruff checks
+ruff check
+CHECK_EXIT=$?
+
+ruff format --check
+FORMAT_EXIT=$?
+
+if [ $CHECK_EXIT -ne 0 ] || [ $FORMAT_EXIT -ne 0 ]; then
+    if [ $CHECK_EXIT -ne 0 ]; then
+        echo "Ruff found linting errors. Run: ruff check --fix"
+    fi
+    if [ $FORMAT_EXIT -ne 0 ]; then
+        echo "Ruff found formatting issues. Run: ruff format"
+    fi
+    exit 1
+fi
+
+# If there are whitespace errors, print the offending file names and fail.
+exec git diff-index --check --cached $against --

diffpdf-0.1.2/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = [
+    "hatchling",
+    "hatch-vcs",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "diffpdf"
+dynamic = ["version"]
+description = "A tool for comparing PDF files"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+authors = [{name = "Justus Rijke", email="justusrijke@gmail.com"}]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Development Status :: 4 - Beta",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+]
+dependencies = [
+    "click",
+    "colorlog",
+    "pymupdf>=1.23.0",
+    "pixelmatch>=0.3.0",
+    "Pillow>=10.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/JustusRijke/DiffPDF"
+Issues = "https://github.com/JustusRijke/DiffPDF/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[project.scripts]
+diffpdf = "diffpdf:main"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"

diffpdf-0.1.2/ruff.toml

@@ -0,0 +1,2 @@
+target-version = "py312"
+lint.select = ["I"]

diffpdf-0.1.2/src/diffpdf/__init__.py

@@ -0,0 +1,15 @@
+from importlib.metadata import version
+
+from .cli import cli
+
+__version__ = version("diffpdf")
+
+
+def main(args=None):  # pragma: no cover
+    if args is None:
+        cli()
+    else:
+        cli(args, standalone_mode=False)
+
+
+__all__ = ["main", "__version__"]

diffpdf-0.1.2/src/diffpdf/cli.py

@@ -0,0 +1,71 @@
+import logging
+import sys
+from pathlib import Path
+
+import click
+import colorlog
+
+from .comparators import compare_pdfs
+
+
+def setup_logging(debug, save_log):  # pragma: no cover
+    level = logging.DEBUG if debug else logging.INFO
+
+    formatter = colorlog.ColoredFormatter(
+        "%(log_color)s%(asctime)s %(levelname)-8s%(reset)s %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        log_colors={
+            "DEBUG": "cyan",
+            "INFO": "green",
+            "WARNING": "yellow",
+            "ERROR": "red",
+            "CRITICAL": "red,bg_white",
+        },
+    )
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+
+    logger = logging.getLogger()
+    logger.setLevel(level)
+    logger.addHandler(console_handler)
+
+    if save_log:
+        file_formatter = logging.Formatter(
+            "%(asctime)s %(levelname)-8s %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        file_handler = logging.FileHandler("log.txt")
+        file_handler.setFormatter(file_formatter)
+        logger.addHandler(file_handler)
+
+    return logger
+
+
+@click.command()
+@click.argument(
+    "reference", type=click.Path(exists=True, dir_okay=False, path_type=Path)
+)
+@click.argument("actual", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--threshold", type=float, default=0.1, help="Pixelmatch threshold (0.0-1.0)"
+)
+@click.option("--dpi", type=int, default=96, help="Render resolution")
+@click.option(
+    "--output-dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default="./",
+    help="Diff image output directory",
+)
+@click.option("--debug", is_flag=True, help="Verbose logging")
+@click.option("--save-log", is_flag=True, help="Write log output to log.txt")
+@click.version_option(package_name="diffpdf")
+def cli(reference, actual, threshold, dpi, output_dir, debug, save_log):
+    """Compare two PDF files for structural, textual, and visual differences."""
+    logger = setup_logging(debug, save_log)
+
+    try:
+        compare_pdfs(reference, actual, threshold, dpi, output_dir, logger)
+    except Exception as e:  # pragma: no cover
+        logger.critical(f"Error: {e}")
+        sys.exit(2)

diffpdf-0.1.2/src/diffpdf/comparators.py

@@ -0,0 +1,22 @@
+import sys
+from pathlib import Path
+
+from .hash_check import check_hash
+from .page_check import check_page_counts
+from .text_check import check_text_content
+from .visual_check import check_visual_content
+
+
+def compare_pdfs(
+    ref: Path, actual: Path, threshold: float, dpi: int, output_dir: Path, logger
+) -> None:
+    check_hash(ref, actual, logger)
+
+    check_page_counts(ref, actual, logger)
+
+    check_text_content(ref, actual, logger)
+
+    check_visual_content(ref, actual, threshold, dpi, output_dir, logger)
+
+    logger.info("PDFs are equivalent")
+    sys.exit(0)

diffpdf-0.1.2/src/diffpdf/hash_check.py

@@ -0,0 +1,24 @@
+import hashlib
+import sys
+from pathlib import Path
+
+
+def compute_file_hash(filepath: Path) -> str:
+    sha256 = hashlib.sha256()
+    with open(filepath, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+
+def check_hash(ref: Path, actual: Path, logger) -> None:
+    logger.info("[1/4] Checking file hashes...")
+
+    ref_hash = compute_file_hash(ref)
+    actual_hash = compute_file_hash(actual)
+
+    if ref_hash == actual_hash:
+        logger.info("Files are identical (hash match)")
+        sys.exit(0)
+
+    logger.info("Hashes differ, continuing checks")

diffpdf-0.1.2/src/diffpdf/page_check.py

@@ -0,0 +1,24 @@
+import sys
+from pathlib import Path
+
+import fitz
+
+
+def get_page_count(pdf_path: Path) -> int:
+    doc = fitz.open(pdf_path)
+    count = len(doc)
+    doc.close()
+    return count
+
+
+def check_page_counts(ref: Path, actual: Path, logger) -> None:
+    logger.info("[2/4] Checking page counts...")
+
+    ref_count = get_page_count(ref)
+    actual_count = get_page_count(actual)
+
+    if ref_count != actual_count:
+        logger.error(f"Page count mismatch: expected {ref_count}, got {actual_count}")
+        sys.exit(1)
+
+    logger.info(f"Page counts match ({ref_count} pages)")

diffpdf-0.1.2/src/diffpdf/text_check.py

@@ -0,0 +1,45 @@
+import difflib
+import sys
+from pathlib import Path
+
+import fitz
+
+
+def extract_text(pdf_path: Path) -> str:
+    doc = fitz.open(pdf_path)
+    text = ""
+    for page in doc:
+        text += page.get_text()
+    doc.close()
+    return text.strip()
+
+
+def generate_diff(ref_text: str, actual_text: str) -> str:
+    ref_lines = ref_text.splitlines(keepends=True)
+    actual_lines = actual_text.splitlines(keepends=True)
+
+    diff = difflib.unified_diff(
+        ref_lines,
+        actual_lines,
+        fromfile="reference.pdf",
+        tofile="actual.pdf",
+        lineterm="",
+    )
+
+    return "".join(diff)
+
+
+def check_text_content(ref: Path, actual: Path, logger) -> None:
+    logger.info("[3/4] Checking text content...")
+
+    ref_text = extract_text(ref)
+    actual_text = extract_text(actual)
+
+    if ref_text != actual_text:
+        diff = generate_diff(ref_text, actual_text)
+        logger.error("Text content mismatch")
+        for line in diff.splitlines():
+            logger.error(line)
+        sys.exit(1)
+
+    logger.info("Text content matches")

diffpdf-0.1.2/src/diffpdf/visual_check.py

@@ -0,0 +1,63 @@
+import sys
+from pathlib import Path
+
+import fitz
+from PIL import Image
+from pixelmatch.contrib.PIL import pixelmatch
+
+
+def render_page_to_image(pdf_path: Path, page_num: int, dpi: int) -> Image.Image:
+    doc = fitz.open(pdf_path)
+    page = doc[page_num]
+    pix = page.get_pixmap(dpi=dpi)
+    img = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
+    doc.close()
+    return img
+
+
+def compare_images(
+    ref_img: Image.Image, actual_img: Image.Image, threshold: float, output_path: Path
+) -> bool:
+    diff_img = Image.new("RGB", ref_img.size)
+    mismatch_count = pixelmatch(ref_img, actual_img, diff_img, threshold=threshold)
+
+    if mismatch_count > 0:
+        diff_img.save(output_path)
+        return False
+
+    return True
+
+
+def check_visual_content(
+    ref: Path, actual: Path, threshold: float, dpi: int, output_dir: Path, logger
+) -> None:
+    logger.info("[4/4] Checking visual content...")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    ref_doc = fitz.open(ref)
+    page_count = len(ref_doc)
+    ref_doc.close()
+
+    failing_pages = []
+
+    for page_num in range(page_count):
+        ref_img = render_page_to_image(ref, page_num, dpi)
+        actual_img = render_page_to_image(actual, page_num, dpi)
+
+        ref_name = ref.stem
+        actual_name = actual.stem
+        output_path = (
+            output_dir / f"{ref_name}_vs_{actual_name}_page{page_num + 1}_diff.png"
+        )
+
+        passed = compare_images(ref_img, actual_img, threshold, output_path)
+
+        if not passed:
+            failing_pages.append(page_num + 1)
+
+    if failing_pages:
+        logger.error(f"Visual mismatch on pages: {', '.join(map(str, failing_pages))}")
+        sys.exit(1)
+
+    logger.info("Visual content matches")

diffpdf-0.1.2/tests/test_cli.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from diffpdf.cli import cli
+
+
+@pytest.mark.parametrize(
+    "ref_pdf_rel,actual_pdf_rel,expected_exit_code",
+    [
+        # Pass cases (exit code 0)
+        ("pass/identical-A.pdf", "pass/identical-B.pdf", 0),
+        ("pass/hash-diff-A.pdf", "pass/hash-diff-B.pdf", 0),
+        ("pass/minor-color-diff-A.pdf", "pass/minor-color-diff-B.pdf", 0),
+        ("pass/multiplatform-diff-A.pdf", "pass/multiplatform-diff-B.pdf", 0),
+        # Fail cases (exit code 1)
+        ("fail/1-letter-diff-A.pdf", "fail/1-letter-diff-B.pdf", 1),
+        ("fail/major-color-diff-A.pdf", "fail/major-color-diff-B.pdf", 1),
+        ("fail/page-count-diff-A.pdf", "fail/page-count-diff-B.pdf", 1),
+        # Critical error cases (exit code 2)
+        ("nonexistent.pdf", "another.pdf", 2),
+    ],
+)
+def test_cli(ref_pdf_rel, actual_pdf_rel, expected_exit_code):
+    """Parametric integration test: CLI should exit with correct code for various PDF pairs."""
+    runner = CliRunner()
+    test_assets_dir = Path(__file__).parent / "assets"
+
+    ref_pdf = str(test_assets_dir / ref_pdf_rel)
+    actual_pdf = str(test_assets_dir / actual_pdf_rel)
+
+    result = runner.invoke(cli, [ref_pdf, actual_pdf])
+
+    assert result.exit_code == expected_exit_code