pytest-r-snapshot 0.1.0__tar.gz

pytest_r_snapshot-0.1.0/.github/workflows/ci-tests.yml

@@ -0,0 +1,56 @@
+name: CI tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          # we are using the -e flag, so that code cov finds the source.
+          # this is not ideal, since installing an editable can technically
+          # differ from a normal install in surprising ways.
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest
+          pytest
+
+      # - name: Upload coverage reports to Codecov
+      #   uses: codecov/codecov-action@v4
+      #   with:
+      #     name: "py${{ matrix.python-version }}"
+      #     token: ${{ secrets.CODECOV_TOKEN }}
+
+  test-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest
+          pytest

pytest_r_snapshot-0.1.0/.github/workflows/mkdocs.yml

@@ -0,0 +1,34 @@
+name: mkdocs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: pip install mkdocstrings-python
+      - run: mkdocs gh-deploy --force

pytest_r_snapshot-0.1.0/.github/workflows/mypy.yml

@@ -0,0 +1,34 @@
+name: Mypy check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  mypy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run Type Checks
+        run: |
+          uv run mypy .

pytest_r_snapshot-0.1.0/.github/workflows/ruff-check.yml

@@ -0,0 +1,25 @@
+name: Ruff check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  ruff-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+      - name: Run Ruff
+        run: ruff check --output-format=github .

pytest_r_snapshot-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# mkdocs site
+/site/

pytest_r_snapshot-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14.2

pytest_r_snapshot-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+## pytest-r-snapshot 0.1.0
+
+### New features
+
+- Initial release of the `pytest-r-snapshot` pytest plugin for snapshot testing against R code outputs.
+- Extract labelled R fenced chunks from Python source (commented chunks and raw chunks in docstrings/multiline strings).
+- Snapshot modes: `replay` (default), `record`, and `auto`.
+- Default snapshot layout: `__r_snapshots__/<test_file_stem>/<name><ext>` with configurable root via `--r-snapshot-dir` / `r_snapshot_dir`.
+- `r_snapshot` fixture with `assert_match_text()`, `read_text()`, `record_text()`, and `path_for()`.
+- Configurable R execution: `Rscript` path, env overrides, working directory, timeout, and snapshot encoding.
+- Optional marker `@pytest.mark.r_snapshot(...)` and decorator alias `pytest_r_snapshot.r_snapshot(...)`.
+- Built-in text normalizers: newline normalization and stripping trailing whitespace.
+
+### Documentation
+
+- Added README and mkdocs articles (setup, usage, configuration, troubleshooting, design, migration).
+
+### Testing
+
+- Added a pytester-based test suite with a mock R runner (no real R required).

pytest_r_snapshot-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2025, pytest-r-snapshot authors
+
+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.

pytest_r_snapshot-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pytest-r-snapshot
+Version: 0.1.0
+Summary: A pytest plugin for snapshot testing against R code outputs
+Project-URL: Homepage, https://nanx.me/pytest-r-snapshot/
+Project-URL: Documentation, https://nanx.me/pytest-r-snapshot/
+Project-URL: Repository, https://github.com/nanxstats/pytest-r-snapshot
+Project-URL: Issues, https://github.com/nanxstats/pytest-r-snapshot/issues
+Project-URL: Changelog, https://github.com/nanxstats/pytest-r-snapshot/blob/main/CHANGELOG.md
+Author-email: Nan Xiao <me@nanx.me>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7.0.0
+Description-Content-Type: text/markdown
+
+# pytest-r-snapshot <img src="https://github.com/nanxstats/pytest-r-snapshot/raw/main/docs/assets/logo.png" align="right" width="120" />
+
+[![PyPI version](https://img.shields.io/pypi/v/pytest-r-snapshot)](https://pypi.org/project/pytest-r-snapshot/)
+![Python versions](https://img.shields.io/pypi/pyversions/pytest-r-snapshot)
+[![CI tests](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ci-tests.yml)
+[![Mypy check](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/mypy.yml/badge.svg)](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/mypy.yml)
+[![Ruff check](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ruff-check.yml)
+[![mkdocs](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/mkdocs.yml/badge.svg)](https://nanx.me/pytest-r-snapshot/)
+![License](https://img.shields.io/pypi/l/pytest-r-snapshot)
+
+A pytest plugin for snapshot testing against reference outputs produced by R code.
+
+It is designed for a portable workflow:
+
+- **Record locally (requires R)**: run labelled R chunks embedded in your
+  Python tests and write snapshot files.
+- **Replay everywhere (default; no R required)**: read committed snapshot
+  files and compare them to Python outputs.
+
+The R chunks live close to the test assertion (copy/paste-able from R scripts
+or R Markdown), but snapshots are stored as deterministic UTF-8 text files.
+
+## Installation
+
+You can install pytest-r-snapshot from PyPI:
+
+```bash
+pip install pytest-r-snapshot
+```
+
+If your project is managed with `uv`, add it as a dev dependency:
+
+```bash
+uv add --dev pytest-r-snapshot
+```
+
+Or install the development version from GitHub:
+
+```bash
+git clone https://github.com/nanxstats/pytest-r-snapshot.git
+cd pytest-r-snapshot
+python3 -m pip install -e .
+```
+
+## Quick start
+
+Embed a labelled R fenced chunk (commented or in a docstring),
+then compare your Python output to the recorded snapshot:
+
+```python
+def test_summary_matches_r(r_snapshot):
+    # ```{r, summary}
+    # x <- c(1, 2, 3)
+    # summary(x)
+    # ```
+
+    actual = my_python_summary(...)
+    r_snapshot.assert_match_text(actual, name="summary")
+```
+
+Generate (or update) snapshots locally:
+
+```bash
+pytest --r-snapshot=record
+```
+
+Commit the generated snapshot files, and run CI with the default
+replay mode (no R required).
+
+## What you get
+
+- A pytest fixture `r_snapshot` with methods:
+  - `assert_match_text(actual, name=..., ext=".txt", normalize=...)`
+  - `read_text(name=..., ext=".txt")`
+  - `record_text(name=..., ext=".txt")`
+  - `path_for(name=..., ext=".txt")`
+- Snapshot modes: `replay` (default), `record`, `auto`.
+- Chunk extraction for R Markdown-style fenced chunks inside Python source:
+  - Commented fences (chunk lines prefixed with `#`).
+  - Raw chunks in docstrings / multi-line strings.
+- Configurable R execution: `Rscript` path, environment, working directory,
+  timeout, encoding.

pytest_r_snapshot-0.1.0/README.md

@@ -0,0 +1,82 @@
+# pytest-r-snapshot <img src="https://github.com/nanxstats/pytest-r-snapshot/raw/main/docs/assets/logo.png" align="right" width="120" />
+
+[![PyPI version](https://img.shields.io/pypi/v/pytest-r-snapshot)](https://pypi.org/project/pytest-r-snapshot/)
+![Python versions](https://img.shields.io/pypi/pyversions/pytest-r-snapshot)
+[![CI tests](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ci-tests.yml)
+[![Mypy check](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/mypy.yml/badge.svg)](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/mypy.yml)
+[![Ruff check](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/ruff-check.yml)
+[![mkdocs](https://github.com/nanxstats/pytest-r-snapshot/actions/workflows/mkdocs.yml/badge.svg)](https://nanx.me/pytest-r-snapshot/)
+![License](https://img.shields.io/pypi/l/pytest-r-snapshot)
+
+A pytest plugin for snapshot testing against reference outputs produced by R code.
+
+It is designed for a portable workflow:
+
+- **Record locally (requires R)**: run labelled R chunks embedded in your
+  Python tests and write snapshot files.
+- **Replay everywhere (default; no R required)**: read committed snapshot
+  files and compare them to Python outputs.
+
+The R chunks live close to the test assertion (copy/paste-able from R scripts
+or R Markdown), but snapshots are stored as deterministic UTF-8 text files.
+
+## Installation
+
+You can install pytest-r-snapshot from PyPI:
+
+```bash
+pip install pytest-r-snapshot
+```
+
+If your project is managed with `uv`, add it as a dev dependency:
+
+```bash
+uv add --dev pytest-r-snapshot
+```
+
+Or install the development version from GitHub:
+
+```bash
+git clone https://github.com/nanxstats/pytest-r-snapshot.git
+cd pytest-r-snapshot
+python3 -m pip install -e .
+```
+
+## Quick start
+
+Embed a labelled R fenced chunk (commented or in a docstring),
+then compare your Python output to the recorded snapshot:
+
+```python
+def test_summary_matches_r(r_snapshot):
+    # ```{r, summary}
+    # x <- c(1, 2, 3)
+    # summary(x)
+    # ```
+
+    actual = my_python_summary(...)
+    r_snapshot.assert_match_text(actual, name="summary")
+```
+
+Generate (or update) snapshots locally:
+
+```bash
+pytest --r-snapshot=record
+```
+
+Commit the generated snapshot files, and run CI with the default
+replay mode (no R required).
+
+## What you get
+
+- A pytest fixture `r_snapshot` with methods:
+  - `assert_match_text(actual, name=..., ext=".txt", normalize=...)`
+  - `read_text(name=..., ext=".txt")`
+  - `record_text(name=..., ext=".txt")`
+  - `path_for(name=..., ext=".txt")`
+- Snapshot modes: `replay` (default), `record`, `auto`.
+- Chunk extraction for R Markdown-style fenced chunks inside Python source:
+  - Commented fences (chunk lines prefixed with `#`).
+  - Raw chunks in docstrings / multi-line strings.
+- Configurable R execution: `Rscript` path, environment, working directory,
+  timeout, encoding.

pytest_r_snapshot-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "pytest-r-snapshot"
+version = "0.1.0"
+description = "A pytest plugin for snapshot testing against R code outputs"
+authors = [{ name = "Nan Xiao", email = "me@nanx.me" }]
+dependencies = ["pytest>=7.0.0"]
+readme = "README.md"
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+
+    "Intended Audience :: Developers",
+
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+
+    "License :: OSI Approved :: MIT License",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+requires-python = ">= 3.10"
+
+[project.urls]
+Homepage = "https://nanx.me/pytest-r-snapshot/"
+Documentation = "https://nanx.me/pytest-r-snapshot/"
+Repository = "https://github.com/nanxstats/pytest-r-snapshot"
+Issues = "https://github.com/nanxstats/pytest-r-snapshot/issues"
+Changelog = "https://github.com/nanxstats/pytest-r-snapshot/blob/main/CHANGELOG.md"
+
+[project.entry-points.pytest11]
+r-snapshot = "pytest_r_snapshot.plugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/docs", "/AGENTS.md", "/mkdocs.yml", "/uv.lock"]
+
+[tool.hatch.build.targets.wheel]
+exclude = ["/docs", "/AGENTS.md", "/mkdocs.yml", "/uv.lock"]
+
+[dependency-groups]
+dev = [
+    "isort>=7.0.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.0",
+    "mkdocstrings-python>=2.0.1",
+    "mypy>=1.19.0",
+    "ruff>=0.14.9",
+]
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

pytest_r_snapshot-0.1.0/src/pytest_r_snapshot/__init__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .normalize import normalize_newlines, strip_trailing_whitespace
+from .settings import RSnapshotSettings, SnapshotMode
+from .snapshot import RSnapshot
+
+if TYPE_CHECKING:  # pragma: no cover
+    from _pytest.mark.structures import MarkDecorator
+
+
+def r_snapshot(name: str, *, ext: str = ".txt") -> MarkDecorator:
+    """Decorator alias for :func:`pytest.mark.r_snapshot`.
+
+    This is a small convenience wrapper around the plugin's marker.
+    """
+
+    import pytest
+
+    return pytest.mark.r_snapshot(name, ext=ext)
+
+
+__all__ = [
+    "RSnapshot",
+    "RSnapshotSettings",
+    "SnapshotMode",
+    "normalize_newlines",
+    "r_snapshot",
+    "strip_trailing_whitespace",
+]

pytest_r_snapshot-0.1.0/src/pytest_r_snapshot/chunks.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import re
+import textwrap
+import tokenize
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import (
+    ChunkLabelMissingError,
+    ChunkParseError,
+    DuplicateChunkLabelError,
+    UnclosedChunkError,
+)
+
+_START_FENCE_RE = re.compile(r"^```\s*\{([^}]*)\}\s*$")
+_END_FENCE_RE = re.compile(r"^```\s*$")
+_LABEL_KV_RE = re.compile(
+    r"""(?x)
+    \blabel
+    \s*=\s*
+    (?:
+        " (?P<dq> [^"]+ ) "
+        |
+        ' (?P<sq> [^']+ ) '
+        |
+        (?P<bare> [^,\s]+ )
+    )
+    """
+)
+
+
+@dataclass(frozen=True)
+class RChunk:
+    """A labelled R chunk extracted from a Python source file."""
+
+    label: str
+    code: str
+    path: Path
+    start_line: int
+    end_line: int
+
+
+def parse_r_chunks(path: Path) -> dict[str, RChunk]:
+    """Parse labelled R fenced chunks from a Python source file."""
+
+    with tokenize.open(path) as handle:
+        source = handle.read()
+    return parse_r_chunks_from_text(source, path=path)
+
+
+def parse_r_chunks_from_text(source: str, *, path: Path) -> dict[str, RChunk]:
+    """Parse labelled R fenced chunks from source text."""
+
+    lines = source.splitlines()
+    chunks: dict[str, RChunk] = {}
+    label_to_lines: dict[str, list[int]] = {}
+
+    line_index = 0
+    while line_index < len(lines):
+        raw_line = lines[line_index]
+        stripped, is_commented = _strip_comment_prefix(raw_line)
+        header = _parse_start_fence_header(stripped)
+        if header is None:
+            line_index += 1
+            continue
+
+        start_line = line_index + 1
+        label = _extract_label(header, path=path, line=start_line)
+
+        body_lines: list[str] = []
+        line_index += 1
+        while line_index < len(lines):
+            raw_body_line = lines[line_index]
+            body_stripped, _ = _strip_comment_prefix(raw_body_line)
+            if _END_FENCE_RE.match(body_stripped) is not None:
+                end_line = line_index + 1
+                code = _normalize_body(body_lines, commented=is_commented)
+                chunk = RChunk(
+                    label=label,
+                    code=code,
+                    path=path,
+                    start_line=start_line,
+                    end_line=end_line,
+                )
+                chunks[label] = chunk
+                label_to_lines.setdefault(label, []).append(start_line)
+                break
+            body_lines.append(raw_body_line)
+            line_index += 1
+        else:
+            raise UnclosedChunkError(path=path, label=label, start_line=start_line)
+
+        line_index += 1
+
+    duplicates = {k: v for k, v in label_to_lines.items() if len(v) > 1}
+    if duplicates:
+        label, dup_lines = sorted(duplicates.items(), key=lambda kv: kv[0])[0]
+        raise DuplicateChunkLabelError(path=path, label=label, lines=dup_lines)
+
+    return chunks
+
+
+def _strip_comment_prefix(line: str) -> tuple[str, bool]:
+    stripped = line.lstrip()
+    if not stripped.startswith("#"):
+        return stripped, False
+    stripped = stripped[1:]
+    if stripped.startswith(" "):
+        stripped = stripped[1:]
+    return stripped, True
+
+
+def _parse_start_fence_header(line: str) -> str | None:
+    if not line.startswith("```") or line.startswith("````"):
+        return None
+    match = _START_FENCE_RE.match(line)
+    if match is None:
+        return None
+    header = match.group(1).strip()
+    if not header.startswith("r") or (len(header) > 1 and header[1] not in (" ", ",")):
+        return None
+    return header
+
+
+def _extract_label(header: str, *, path: Path, line: int) -> str:
+    label_match = _LABEL_KV_RE.search(header)
+    if label_match is not None:
+        label = (
+            label_match.group("dq")
+            or label_match.group("sq")
+            or label_match.group("bare")
+        )
+        return label.strip()
+
+    tokens = header.replace(",", " ").split()
+    if not tokens or tokens[0] != "r":
+        raise ChunkLabelMissingError(path=path, line=line, header=header)
+
+    for token in tokens[1:]:
+        if token and "=" not in token:
+            return token.strip().strip("'\"")
+
+    raise ChunkLabelMissingError(path=path, line=line, header=header)
+
+
+def _normalize_body(body_lines: list[str], *, commented: bool) -> str:
+    if not body_lines:
+        return ""
+    if commented:
+        normalized: list[str] = []
+        for raw in body_lines:
+            if raw.strip() == "":
+                normalized.append("")
+                continue
+            stripped = raw.lstrip()
+            if not stripped.startswith("#"):
+                raise ChunkParseError(
+                    "Found a non-comment line inside a commented R chunk body. "
+                    "Commented chunks must prefix each line with '#'."
+                )
+            stripped = stripped[1:]
+            if stripped.startswith(" "):
+                stripped = stripped[1:]
+            normalized.append(stripped)
+        return "\n".join(normalized)
+
+    return textwrap.dedent("\n".join(body_lines))