pytest-checkpoint 0.1.0__py3-none-any.whl

pytest_checkpoint/__init__.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pytest_checkpoint.plugin import CheckpointPlugin, CheckpointPluginOpts, CollectBehavior
+
+if TYPE_CHECKING:
+    from pytest import Config, Parser
+
+
+_DEFAULT_LAP_OUT = ".pytest_checkpoint/lap.json"
+
+
+def pytest_addoption(parser: Parser) -> None:
+    group = parser.getgroup(
+        name=CheckpointPlugin.name,
+        description=CheckpointPlugin.name,
+    )
+    group.addoption(
+        CheckpointPluginOpts.LAP_OUT,
+        action="store",
+        default=_DEFAULT_LAP_OUT,
+        help="Output file to store lap information for recording a checkpoint",
+    )
+    group.addoption(
+        CheckpointPluginOpts.COLLECT_BEHAVIOR,
+        action="store",
+        default=CollectBehavior.DESELECT,
+        # NOTE: In python 3.11, the choices argument is not supported for enums
+        # We must convert it to a list of strings
+        choices=list(CollectBehavior),
+        help="This will determine how tests are collected when a checkpoint is restored",
+    )
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_configure(config: Config) -> None:
+    config.pluginmanager.register(CheckpointPlugin(config), CheckpointPlugin.name)
+
+
+__all__ = [
+    "pytest_addoption",
+    "pytest_configure",
+]

pytest_checkpoint/lap.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Lap:
+    passed: list[str] = field(default_factory=list)
+    failed: list[str] = field(default_factory=list)
+
+    def mark_passed(self, test: str) -> None:
+        """Call this when a test has passed so we can record it in the lap.
+
+        Args:
+            test (str): The test name that passed.
+        """
+        if test in self.passed:
+            return
+
+        self.passed.append(test)
+        if test in self.failed:
+            self.failed.remove(test)
+
+    def mark_failed(self, test: str) -> None:
+        """Call this when a test has failed so we can record it in the lap.
+
+        Args:
+            test (str): The test name that failed.
+        """
+        if test in self.failed:
+            return
+
+        self.failed.append(test)
+        if test in self.passed:
+            self.passed.remove(test)
+
+    def is_recorded(self, test: str) -> bool:
+        """Check if a test has been recorded in the lap.
+
+        Args:
+            test (str): The test name to check.
+
+        Returns:
+            bool: True if the test has been recorded, False otherwise.
+        """
+        return test in self.passed or test in self.failed
+
+    def encode(self) -> dict[str, list[str]]:
+        """Encode the lap data into a dictionary.
+
+        Returns:
+            dict: The lap data encoded into a dictionary.
+        """
+        return {
+            "passed": self.passed,
+            "failed": self.failed,
+        }
+
+    @classmethod
+    def decode(cls, data: dict[str, list[str]]) -> Lap:
+        """Decode a dictionary into a Lap object.
+
+        Args:
+            data (dict): The dictionary to decode.
+
+        Returns:
+            Lap: The Lap object decoded from the dictionary.
+        """
+        return cls(
+            passed=data["passed"],
+            failed=data["failed"],
+        )

pytest_checkpoint/logger.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from _pytest.logging import ColoredLevelFormatter, get_log_level_for_setting
+
+if TYPE_CHECKING:
+    from pytest import Config
+
+
+def get_logger(config: Config, name: str) -> logging.Logger:
+    level = get_log_level_for_setting(config, "log_cli_level")
+    if level is None:
+        level = logging.DEBUG if config.option.verbose > 0 else logging.INFO
+
+    # TODO: Color does not work as expected.
+    formatter = ColoredLevelFormatter(
+        config.get_terminal_writer(), config.getini("log_cli_format"), datefmt=config.getini("log_cli_date_format")
+    )
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+    handler.setFormatter(formatter)
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    logger.addHandler(handler)
+    return logger

pytest_checkpoint/plugin.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pytest_checkpoint.lap import Lap
+from pytest_checkpoint.logger import get_logger
+
+if TYPE_CHECKING:
+    from pytest import Config, Item, Session, TestReport
+
+
+class RunTestPhase(StrEnum):
+    SETUP = "setup"
+    CALL = "call"
+    TEARDOWN = "teardown"
+
+
+class CheckpointPluginOpts(StrEnum):
+    LAP_OUT = "--lap-out"
+    COLLECT_BEHAVIOR = "--collect-behavior"
+
+
+class CollectBehavior(StrEnum):
+    DESELECT = "deselect"
+    SKIP = "skip"
+
+
+class CheckpointPlugin:
+    name = "pytest-checkpoint"
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self.logger = get_logger(config, self.name)
+        self.lap_file = Path(config.getoption(CheckpointPluginOpts.LAP_OUT))
+        self.collect_behavior = CollectBehavior(config.getoption(CheckpointPluginOpts.COLLECT_BEHAVIOR))
+        self._lap: Lap | None = None
+
+    @property
+    def lap(self) -> Lap:
+        if self._lap:
+            return self._lap
+
+        if self.lap_file.exists():
+            # TODO: figure out a better way to do logging. Possibly do a report instead.
+            # Write a line before logging
+            self.config.get_terminal_writer().line()
+            self.logger.debug("Restoring checkpoint from %s", self.lap_file)
+            self._lap = Lap.decode(json.loads(self.lap_file.read_text()))
+        else:
+            self._lap = Lap()
+        return self._lap
+
+    def pytest_collection_modifyitems(self, session: Session, config: Config, items: list[Item]) -> None:
+        """https://docs.pytest.org/en/stable/reference/reference.html#pytest.hookspec.pytest_collection_modifyitems
+
+        Here we will record all the tests that are expected to run.
+
+        Args:
+            session (Session): The pytest session object.
+        """
+        deselected: set[Item] = set()
+        for item in items:
+            if item.nodeid in self.lap.passed:
+                if self.collect_behavior == CollectBehavior.DESELECT:
+                    self.logger.debug("Deselecting %s from checkpoint", item.nodeid)
+                    deselected.add(item)
+                    continue
+                elif self.collect_behavior == CollectBehavior.SKIP:
+                    self.logger.debug("Skipping %s from checkpoint", item.nodeid)
+                    item.add_marker("skip")
+
+        items[:] = [item for item in items if item not in deselected]
+        config.hook.pytest_deselected(items=deselected)
+
+    def pytest_runtest_logreport(self, report: TestReport) -> None:
+        """https://docs.pytest.org/en/7.1.x/reference/reference.html#pytest.hookspec.pytest_runtest_logreport
+
+        We will inspect the report object to determine if the test passed, failed, or was skipped.
+
+        It handles this for each phase of the test: setup, call, and teardown.
+
+        Args:
+            report (TestReport): The report about to be logged.
+        """
+        # Special case for unittest expected failures
+        # This is not handled in the internal 'TestReport.from_item_and_call' method
+        is_unittest_expected_failure = report.keywords.get("__unittest_expecting_failure__", 0) == 1
+
+        if report.when == RunTestPhase.SETUP:
+            if report.failed and is_unittest_expected_failure is False:
+                self.lap.mark_failed(report.nodeid)
+            elif report.skipped and (hasattr(report, "wasxfail") or is_unittest_expected_failure):
+                # Edge case where setup failure happens on a xfail test.
+                # In these cases we should mark the test as passed
+                # After this we skip call and go to teardown
+                self.lap.mark_passed(report.nodeid)
+
+            return None
+
+        if report.when == RunTestPhase.CALL:
+            if report.skipped or report.passed:
+                self.lap.mark_passed(report.nodeid)
+
+            if report.failed and is_unittest_expected_failure is False:
+                self.lap.mark_failed(report.nodeid)
+            elif report.failed and is_unittest_expected_failure:
+                self.lap.mark_passed(report.nodeid)
+
+            return None
+
+        if report.when == RunTestPhase.TEARDOWN:
+            if report.failed and is_unittest_expected_failure is False:
+                self.lap.mark_failed(report.nodeid)
+            self._checkpoint()
+
+    def _checkpoint(self) -> None:
+        """Checkpoint your progress.
+
+        This will write the lap info to the output file.
+        """
+        self.logger.debug("Creating checkpoint to %s", self.lap_file)
+        self.lap_file.parent.mkdir(parents=True, exist_ok=True)
+        self.lap_file.write_text(json.dumps(self.lap.encode()))

pytest_checkpoint-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: pytest-checkpoint
+Version: 0.1.0
+Summary: Restore a checkpoint in pytest
+Author-email: Nick Grisafi <njgrisafi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pytest>=8.3.5
+Description-Content-Type: text/markdown
+
+# pytest-checkpoint
+
+<!-- <img src="./docs/logo.png" alt="pytest-checkpoint Logo" width="250" /> -->
+<img src="https://i.postimg.cc/wMKBDZ79/logo.webp" alt="pytest-checkpoint Logo" width="250" />
+
+## Overview
+
+`pytest-checkpoint` is a plugin for the [pytest](https://docs.pytest.org/en/stable/) testing framework that allows developers to restore their testing state from a checkpoint. This feature is particularly useful for long-running test suites, enabling you to pick up where you left off without having to rerun all tests.
+
+### Perfect for Interruptible Environments
+
+Running long test suites can be challenging when your environment isn't guaranteed to be stable. For example:
+- Your CI pipeline might time out
+- Your development machine might need a reboot
+- Your cloud instance might be interrupted (i.e. AWS Spot instances)
+
+`pytest-checkpoint` automatically saves your test progress, so you can pick up exactly where you left off when the system comes back online. This saves valuable time and computing resources, especially in environments where interruptions are common.
+
+## Features
+
+- **Checkpoint Restoration**: Automatically restore the state of tests from a previously saved checkpoint.
+- **Flexible Collection Behavior**: Choose how tests are collected when restoring from a checkpoint (deselect or skip).
+- **Detailed Logging**: Get insights into the checkpointing process with debug logs.
+
+## Installation
+
+You can install `pytest-checkpoint` using pip:
+
+```bash
+pip install pytest-checkpoint
+```
+
+## Usage
+
+To use `pytest-checkpoint`, you need to add options to your pytest configuration. You can do this by adding the following lines to your `pytest.ini` or directly in the command line:
+
+```ini
+[pytest]
+lap_out = .pytest_checkpoint/lap.json
+collect_behavior = deselect  # or skip
+```
+
+### Command Line Options
+
+- `--lap-out`: Specify the output file to store lap information for recording a checkpoint. Default is `.pytest_checkpoint/lap.json`.
+- `--collect-behavior`: Determines how tests are collected when a checkpoint is restored. Options are `deselect` or `skip`.
+
+### Example
+
+Run your tests as usual, and the plugin will handle the checkpointing automatically:
+
+```bash
+pytest
+```
+
+If a test fails or is skipped, the plugin will mark it accordingly in the checkpoint file.
+
+## Contributing
+
+We welcome contributions from the community! To contribute to `pytest-checkpoint`, please follow these steps:
+
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix.
+3. Make your changes and commit them.
+4. Push your branch to your forked repository.
+5. Create a pull request describing your changes.
+
+## License
+
+`pytest-checkpoint` is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+
+## Authors
+
+- **Nick Grisafi** - [njgrisafi@gmail.com](mailto:njgrisafi@gmail.com)
+
+## Acknowledgments
+
+- Thanks to the [pytest](https://docs.pytest.org/en/stable/) community for their support and contributions to the testing ecosystem.
+
+---
+
+For more information, please refer to the [documentation](https://docs.pytest.org/en/stable/) or check the source code in this repository.

pytest_checkpoint-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pytest_checkpoint/__init__.py,sha256=xQnekaCL4wSUtpcIURF_ap18RmvEKViL4YJt7Db4idE,1276
+pytest_checkpoint/lap.py,sha256=me4F2KS2S7HBZ-a-9E_NokfnNfzOWrKIWFDMjfejJfU,1904
+pytest_checkpoint/logger.py,sha256=d1wuyCOKYwNL2a9ADOFUHDyozdcA_0IHLZxw6Ze9AEs,858
+pytest_checkpoint/plugin.py,sha256=txMxiZ65zhAJM9shqEjnHCKmZTtQ0NpwfyaAxvdr5fs,4746
+pytest_checkpoint/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_checkpoint-0.1.0.dist-info/METADATA,sha256=6UmWjrLQTb2GnyHCxqYDRRuc5LmLMexULf3a9Unog5w,3854
+pytest_checkpoint-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pytest_checkpoint-0.1.0.dist-info/licenses/LICENSE,sha256=hVSXDknAkp0GbEr5CYV8X0bauLYoQVUmbeBAgJMHv8Y,1073
+pytest_checkpoint-0.1.0.dist-info/RECORD,,

pytest_checkpoint-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_checkpoint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nicholas Grisafi
+
+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.