selenium-screenshot-compare 0.1.0__tar.gz

selenium_screenshot_compare-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & format (pre-commit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install project (dev extras)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run pre-commit on all files
+        run: pre-commit run --all-files --show-diff-on-failure
+
+  smoke:
+    name: Install & import (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install project (robot extra)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[robot]"
+
+      - name: Import package + Robot Framework library
+        run: |
+          python -c "import selenium_screenshot_compare as s; print(s.__version__)"
+          python -c "from selenium_screenshot_compare.ScreenshotCompareLibrary import ScreenshotCompareLibrary"
+
+  build:
+    name: Build package & install wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build backend
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Install the built wheel and import
+        run: |
+          python -m venv /tmp/wheel-test
+          /tmp/wheel-test/bin/pip install dist/*.whl
+          /tmp/wheel-test/bin/python -c "import selenium_screenshot_compare as s; print(s.__version__)"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  robot-dryrun:
+    name: Robot Framework dry-run
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install project with Robot Framework
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[robot]"
+
+      - name: Robot Framework dry-run
+        run: robot --dryrun --outputdir output/robot tests/

selenium_screenshot_compare-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs the full history
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          pip install --quiet dist/*.whl
+          WHEEL_VERSION=$(python -c "from importlib.metadata import version; print(version('selenium-screenshot-compare'))")
+          echo "Tag=$TAG  Wheel=$WHEEL_VERSION"
+          [ "$TAG" = "$WHEEL_VERSION" ] || { echo "::error::Version mismatch"; exit 1; }
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

selenium_screenshot_compare-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python environment
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.robocop_cache/
+
+# Build artefacts
+build/
+dist/
+
+# Generated outputs (captures, diffs, result.json, Robot Framework reports)
+output/
+
+# Downloaded Firefox binaries (heavy artefacts, ~90 MB)
+firefoxes/
+
+# Storage state / session secrets (cookies, tokens): DO NOT commit
+resources/env/
+
+# Misc OS / editors
+.DS_Store
+*.swp

selenium_screenshot_compare-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+# Hooks executed before every commit. Install with:  pre-commit install
+repos:
+  - repo: https://github.com/MarketSquare/robotframework-robocop
+    rev: v8.3.2
+    hooks:
+      # Format .robot files (ex-robotidy).
+      - id: robocop-format
+      # Lint .robot files; fails if any issue is found.
+      - id: robocop
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      # Python lint (fast); fails if any issue is found.
+      - id: ruff
+        args: [--fix]
+      # Format Python code.
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: debug-statements

selenium_screenshot_compare-0.1.0/CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+This file guides Claude Code (and Claude agents) when working in this repo.
+
+## The project in one sentence
+
+Python package + Robot Framework library that compares a website's rendering
+between **two Firefox versions** driven in parallel via Selenium.
+
+## Structure
+
+- `selenium_screenshot_compare/` — installable package (flat layout).
+  - Plain Python core: `capture.py`, `comparison.py`, `session.py`,
+    `storage.py`, `naming.py`.
+  - `ScreenshotCompareLibrary.py`: Robot Framework wrapper around the core.
+    **Do not** duplicate business logic here — only `@keyword` methods.
+- `tests/` — example `.robot` suites; they import `Library
+  selenium_screenshot_compare.ScreenshotCompareLibrary` (the package must be
+  installed, see README).
+- `resources/env/` — storage state (`auth.json`), **gitignored**. Contains
+  session cookies: never commit, never log the contents.
+- `firefoxes/` — downloaded Firefox binaries, **gitignored**.
+- `output/` — captures, diffs, `result.json`, Robot reports, **gitignored**.
+
+## Installation convention
+
+Always editable with the `dev` extra during development:
+
+```bash
+./.venv/bin/pip install -e ".[dev]"
+```
+
+The `requirements*.txt` files just forward to `pip install -e .[…]` — they
+exist for backwards compatibility, but `pyproject.toml` is the source of truth.
+
+## Code style
+
+- Python **3.10+** (we use `X | None`, `from __future__ import annotations`
+  is already in place).
+- Ruff is configured in `pyproject.toml` (`[tool.ruff]`, `line-length = 100`,
+  rule set `E,F,W,I,UP,B,SIM,RUF`).
+- Docstrings and comments **in English**.
+- No abstractions/factories/speculative layers. The code is intentionally flat.
+
+## Quality — hooks
+
+The project uses `pre-commit` with:
+
+- **ruff** (Python lint + format)
+- **robocop / robocop-format** (`.robot` lint + format)
+- standard **pre-commit-hooks** (whitespace, EOF, YAML/TOML, large files,
+  `debug-statements`)
+
+To do once per clone:
+
+```bash
+./.venv/bin/pre-commit install
+```
+
+After any substantive change, run:
+
+```bash
+./.venv/bin/pre-commit run --all-files
+```
+
+Never commit with `--no-verify` unless explicitly authorised — if a hook
+fails, fix the root cause.
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs on every push and pull request:
+
+- `pre-commit run --all-files` on Python 3.12
+- Package build (`python -m build`)
+- `robot --dryrun tests/` to verify the library imports cleanly
+
+If you change tooling (Ruff rules, Robocop config, hook versions), update the
+workflow accordingly.
+
+## Versioning
+
+The version is derived from **git tags** by `setuptools-scm` — there is no
+hardcoded version string to maintain. `__version__` reads it from
+`importlib.metadata` at runtime. To release: tag `vX.Y.Z` on `main` and push;
+the release workflow handles the rest (build + PyPI + GitHub Release).
+
+## Adding a Robot Framework keyword
+
+1. Write the logic in a Python module of the package (not in
+   `ScreenshotCompareLibrary.py`).
+2. Expose a clean function/object in `selenium_screenshot_compare/__init__.py`
+   if it belongs to the public API.
+3. Add a `@keyword("Human Readable Name")` method in
+   `ScreenshotCompareLibrary.py` that delegates to the core.
+4. Document the keyword (short docstring) and add it to the README table.
+
+## Robot Framework — good to know
+
+- The `.robot` files load the library by **module name**:
+  `Library    selenium_screenshot_compare.ScreenshotCompareLibrary`. This
+  requires the package to be **installed** in the active venv.
+- Windows paths inside `.robot` files must use forward slashes `/` (`\` is a
+  Robot Framework escape character).
+- The comparison is **pixel-by-pixel**; a vertical offset inflates the
+  percentage even when the pages look identical. `first_diff_y` helps tell
+  the two cases apart.
+
+## What not to do
+
+- Do not reintroduce the old `sys.path.insert` hack in the Robot Framework
+  library — the package is now importable normally.
+- Do not read or commit `resources/env/auth.json` (secrets).
+- Do not install geckodriver manually: Selenium Manager handles it.
+- Do not add a runtime dependency without updating `pyproject.toml`
+  (`dependencies` for the core, `optional-dependencies` for the rest).
+
+## Checks before saying "it's ready"
+
+- `./.venv/bin/pre-commit run --all-files` passes.
+- `./.venv/bin/python -c "import selenium_screenshot_compare as s;
+  print(s.__version__)"` responds without error.
+- If a `.robot` moved: `./.venv/bin/robot --dryrun tests/` stays green
+  (requires Firefox but at least validates the library import).

selenium_screenshot_compare-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing
+
+## Development setup
+
+```bash
+python3 -m venv .venv
+./.venv/bin/pip install -e ".[dev]"
+./.venv/bin/pre-commit install
+```
+
+## Linting & formatting
+
+Orchestrated by **pre-commit** — every `git commit` runs them automatically.
+
+| Tool | Scope | What it does |
+|---|---|---|
+| **Ruff** | Python (`selenium_screenshot_compare/`) | lint + format (replaces flake8 / black / isort) |
+| **Robocop** | `.robot` files | lint + format |
+| **pre-commit-hooks** | everything | trailing whitespace, EOF, YAML/TOML, large files, debug statements |
+
+Run manually:
+
+```bash
+./.venv/bin/ruff check selenium_screenshot_compare/             # Python lint
+./.venv/bin/ruff format selenium_screenshot_compare/            # Python format
+./.venv/bin/robocop format              # format .robot
+./.venv/bin/robocop check               # lint .robot
+./.venv/bin/pre-commit run --all-files  # everything at once
+```
+
+## Continuous integration
+
+A [GitHub Actions workflow](.github/workflows/ci.yml) runs on every push and
+pull request:
+
+- **Lint** — `pre-commit run --all-files` (Python 3.12)
+- **Smoke test** — install + import on Python 3.10 and 3.14
+- **Build** — `python -m build`, install the wheel, verify the import
+- **Robot dry-run** — `robot --dryrun tests/` to validate the library loads
+
+## Checks before submitting
+
+```bash
+./.venv/bin/pre-commit run --all-files
+./.venv/bin/python -c "import selenium_screenshot_compare as s; print(s.__version__)"
+./.venv/bin/robot --dryrun tests/
+```
+
+## Releasing
+
+The version is derived automatically from git tags by **setuptools-scm** — no
+version string to maintain manually.
+
+To publish a new release:
+
+1. Merge `dev` into `main`.
+2. Tag and push: `git tag v0.1.0 && git push origin v0.1.0`
+3. The [release workflow](.github/workflows/release.yml) automatically:
+   - Builds the sdist + wheel
+   - Publishes to **PyPI**
+   - Creates a **GitHub Release** with auto-generated release notes
+
+> First-time setup: configure [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/)
+> for the repository — add a publisher with workflow `release.yml` and
+> environment `pypi`. No API token needed after that.