pytest-ros 0.1.0__tar.gz

pytest_ros-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,67 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# GitHub recommends pinning actions to a commit SHA.
+# To get a newer version, you will need to update the SHA.
+# You can also reference a tag or branch, but the action may change without warning.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: 
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+
+    needs:
+      - release-build
+
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.3

pytest_ros-0.1.0/.gitignore

@@ -0,0 +1,209 @@
+*_version.py
+
+# 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
+
+# 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__/

pytest_ros-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: pytest-ros
+Version: 0.1.0
+Summary: A pytest plugin for integration testing of ROS 2 systems
+Author-email: Sean Fish <seanfish@gatech.edu>
+License-Expression: MIT
+Classifier: Framework :: Pytest
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pytest>=7.0.0
+Requires-Dist: pyyaml
+Requires-Dist: rclpy
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pytest-ros
+
+A Pytest plugin to provide fixtures and utilities for testing of ROS 2 systems. 
+
+## Features
+
+- *Automated Lifecycle Management*: Automatically initialize and clean up launched programs with some additional safeguards against rogue processes, though not guaranteed
+
+- *Fixtures*: Included fixtures for launching ROS processes such as launch files and for monitoring ROS topics
+
+
+## Installation
+
+To install `pytest-ros`:
+
+```
+pip install .
+```
+
+This plugin has an external undeclared dependency on ROS 2 `rclpy`. Make sure ROS 2 is installed and sourced.
+
+## Usage
+
+### Running Tests
+
+Execute tests normally with `pytest`.
+
+

pytest_ros-0.1.0/README.md

@@ -0,0 +1,28 @@
+# pytest-ros
+
+A Pytest plugin to provide fixtures and utilities for testing of ROS 2 systems. 
+
+## Features
+
+- *Automated Lifecycle Management*: Automatically initialize and clean up launched programs with some additional safeguards against rogue processes, though not guaranteed
+
+- *Fixtures*: Included fixtures for launching ROS processes such as launch files and for monitoring ROS topics
+
+
+## Installation
+
+To install `pytest-ros`:
+
+```
+pip install .
+```
+
+This plugin has an external undeclared dependency on ROS 2 `rclpy`. Make sure ROS 2 is installed and sourced.
+
+## Usage
+
+### Running Tests
+
+Execute tests normally with `pytest`.
+
+

pytest_ros-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "pytest-ros"
+dynamic = ["version"]
+description = "A pytest plugin for integration testing of ROS 2 systems"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Sean Fish", email = "seanfish@gatech.edu" },
+]
+classifiers = [
+    "Framework :: Pytest",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "pytest>=7.0.0",
+    "rclpy",
+    "pyyaml",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+
+[project.optional-dependencies]
+dev = [
+    "hatch",
+    "black",
+    "pytest-cov",
+]
+
+[project.entry-points."pytest11"]
+# This registers the plugin with pytest
+pytest_ros = "pytest_ros.plugin"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/pytest_ros/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytest_ros"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+log_cli = true
+log_cli_level = "INFO"

pytest_ros-0.1.0/src/pytest_ros/__init__.py

@@ -0,0 +1,5 @@
+try:
+    import rclpy
+    RCLPY_AVAILABLE = True
+except ImportError:
+    RCLPY_AVAILABLE = False

pytest_ros-0.1.0/src/pytest_ros/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

pytest_ros-0.1.0/src/pytest_ros/monitor.py

@@ -0,0 +1,387 @@
+import time
+import threading
+
+from pytest_ros import RCLPY_AVAILABLE
+if RCLPY_AVAILABLE:
+    import rclpy
+    from rclpy.node import Node
+    from rclpy.executors import SingleThreadedExecutor
+
+
+import logging
+
+
+class EpisodeMonitor:
+    """
+    A class to monitor test episodes, enabling waiting for start conditions and monitoring for 
+    termination conditions, both success and failure.
+
+    The conditions are defined as ROS topics with either a requirement for a message to be received
+    or a specific value to be met.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        timeout: float | None = None
+    ):
+        
+        self.name = name
+        self._logger = logging.getLogger(f'EpisodeMonitor.{self.name}')
+
+        self._conditions = {} # dict of condition name to its 'value' (True/False/None) and 'interface' (e.g. subscriber or service client)
+        self._statuses = {}
+        
+        # Monitor start time
+        self._start_time = time.time()
+        self._timeout = timeout
+
+        # Initialize the internal ROS 2 node
+        self.node = Node(name)
+
+        # Setup threading and execution infrastructure
+        self._stop_event = threading.Event()
+        self._is_running = threading.Event()
+        
+        self._executor = SingleThreadedExecutor()
+        self._executor.add_node(self.node)
+        
+        self._spin_thread = threading.Thread(target=self._run, daemon=True)
+        self._spin_thread.start()
+        
+        if not self._is_running.wait(timeout=2.0):
+            raise RuntimeError("ROS 2 background executor failed to start.")
+        
+        # Create default statuses
+        self.register_condition(condition_name='episode_timeout')
+        self.register_status(status_name='timeout', conditions=['episode_timeout'], trigger='ANY') # Evaluates to True if any timeouts occur
+        self.register_status(status_name='complete', conditions=['timeout'], trigger='ANY') # A special status that can be triggered by any condition or externally to indicate episode completion
+        
+    def set_timeout(self, timeout: float):
+        """Sets a new timeout for the episode. If the timeout is breached, the 'timeout' status will be triggered."""
+        self._start_time = time.time()  # Reset start time whenever timeout is set
+        self._timeout = timeout
+        self._logger.info(f"Episode timeout set to {timeout} seconds from time {self._start_time}.")
+
+
+    def register_condition(self, condition_name):
+        """
+        Registers a simple condition that can be manually set to True or False.
+
+        Parameters:
+            condition_name (str): The name of the condition.
+        """
+        self._conditions[condition_name] = {'value': None, 'interface': 'manual'}  # Initialize condition value as None
+
+    def get_condition(self, condition_name):
+        """
+        Retrieves the current value of a condition.
+
+        Parameters:
+            condition_name (str): The name of the condition.
+
+        Returns:
+            bool: The current value of the condition, or None if the condition is not registered.
+        """
+        condition_info = self._conditions.get(condition_name)
+        if condition_info:
+            return condition_info['value']
+        return None
+
+    def register_topic_condition(self, condition_name, topic_name, msg_type, value_check=None):
+        """
+        Registers a condition based on a ROS topic. 
+        Conditions can be True, False, or None (not yet received).
+
+        Parameters:
+            condition_name (str): The name of the condition.
+            topic_name (str): The name of the ROS topic to subscribe to.
+            msg_type: The ROS message type to expect (e.g., std_msgs.msg.String).
+            value_check (callable, optional): A function that takes a message and returns True if it meets the desired condition. If None, any message will suffice.
+        """
+        self._conditions[condition_name] = {'value': None, 'interface': None}  # Initialize condition value as None
+        self._conditions[condition_name]['interface'] = self._setup_subscription(
+            condition_name=condition_name,
+            topic_name=topic_name, 
+            msg_type=msg_type, 
+            value_check=value_check
+        )
+
+    
+
+    def register_service_condition(self, 
+        condition_name, 
+        service_name, 
+        srv_type,
+        srv_req,
+        value_check=None,
+        period: float = 1.0,
+        start_on_status: str = None,
+        timeout: float = None,
+        timeout_is_fatal: bool = False
+    ):
+        """
+        Registers a condition based on a ROS service.
+
+        Parameters:
+            condition_name (str): The name of the condition.
+            service_name (str): The name of the ROS service to call.
+            srv_type: The ROS service type to expect (e.g., std_srvs.srv.Trigger).
+            srv_req (srv_type.Request or callable): The request object or a function that returns the request object for the service call.
+            value_check (callable, optional): A function that takes a service response and returns True if it meets the desired condition. If None, any response will suffice.
+            period (float): How often to call the service in seconds.
+            start_on_status (str, optional): If provided, the service calls will only start once this status is triggered.
+            timeout (float, optional): Maximum time to keep trying the service call before giving up. If None, it will keep trying indefinitely.
+            timeout_is_fatal (bool, optional): If True, the timeout will be reported as an episode timeout.
+        """
+        self._conditions[condition_name] = {'value': None, 'interface': None}  # Initialize condition value as None
+        if timeout is not None:
+            self._conditions[f'{condition_name}_timeout'] = {'value': False, 'interface': None} 
+            if timeout_is_fatal:
+                self.add_condition_to_status('timeout', f'{condition_name}_timeout')
+        self._conditions[condition_name]['interface'] = self._setup_client(
+            condition_name=condition_name,
+            service_name=service_name,
+            srv_type=srv_type,
+            srv_req=srv_req,
+            value_check=value_check,
+            period=period,
+            start_on_status=start_on_status,
+            timeout=timeout
+        )
+    
+    def register_status(self, status_name, conditions, trigger='ALL'):
+        """
+        Registers a status to monitor.
+
+        Parameters:
+            status_name (str): The name of the status.
+            conditions (list of str): A list of condition names that contribute to this status.
+            trigger (str): 'ANY' or 'ALL' - determines how multiple conditions are evaluated.
+        """
+        # Prevent overwriting existing statuses
+        if status_name in self._statuses:
+            self.node.get_logger().warning(f"Status '{status_name}' is already registered. Skipping registration.")
+            return
+        self._statuses[status_name] = {
+            'trigger': trigger,
+            'conditions': conditions
+        }
+        self._conditions.setdefault(status_name, {'value': None, 'interface': 'status'})  # Ensure the status itself is also a condition for potential nesting
+
+
+    def add_condition_to_status(self, status_name, condition_name):
+        """
+        Dynamically adds a condition to an existing status.
+
+        Parameters:
+            status_name (str): The name of the status to update.
+            condition_name (str): The name of the condition to add.
+        """
+        if status_name in self._statuses:
+            self._statuses[status_name]['conditions'].append(condition_name)
+        else:
+            self.node.get_logger().warning(f"Status '{status_name}' not found. Cannot add condition '{condition_name}'.")
+
+    def get_status(self, status_name):
+        """
+        Checks the status by dynamically resolving its underlying condition values.
+
+        Returns:
+            bool: True if the logical trigger condition is met, False otherwise.
+        """
+        status = self._statuses.get(status_name)
+        if not status:
+            self.node.get_logger().warning(f"Status '{status_name}' is not registered.")
+            return False
+
+        if len(status['conditions']) == 0:
+            return False  # A status with no conditions is considered always False
+
+        # If a condition is actually another status, we need to evaluate it recursively by calling get_status on it.
+        # TODO: This could be optimized with memoization if we expect deep nesting, but for now we assume simple cases.
+        for cond in status['conditions']:
+            if self._conditions[cond]['interface'] == 'status':
+                # If the condition is actually another status, we need to evaluate it recursively
+                self._conditions[cond]['value'] = self.get_status(cond)
+        
+        # Map the list of condition strings to their current real-time boolean states
+        # Using .get('value', False) handles uninitialized or pending states safely.
+        resolved_values = [
+            self._conditions.get(cond, {}).get('value', False) 
+            for cond in status['conditions']
+        ]
+
+        # 2. Evaluate the values against the gate logic
+        if status['trigger'] == 'ANY':
+            return any(resolved_values)
+        elif status['trigger'] == 'ALL':
+            return all(resolved_values)
+            
+        return False
+
+    def wait_for_status(self, status_name: str, poll_interval: float = 0.1) -> bool:
+        """
+        Blocks synchronously until the status becomes True, 'complete' triggers,
+        or the configured timeout duration is exceeded.
+        
+        Returns:
+            bool: True if the status was successfully reached, False otherwise.
+        """
+        start_time = time.time()
+        
+        while not self.get_status(status_name):
+            # 1. Check if an external mechanism or internal logic set 'complete'
+            if self.get_status("complete"):
+                break
+                
+            # 2. Check if the time elapsed exceeds our timeout limit
+            if (time.time() - start_time) > self._timeout:
+                self._statuses["timeout"] = True
+                return False
+                
+            # 3. Yield thread execution to allow rclpy executor thread 
+            # or topic callbacks to flush and update data structures
+            time.sleep(poll_interval)
+            
+        # Double check we didn't exit the loop due to a break condition failure
+        return self.get_status(status_name)
+
+    def _update_condition(self, condition_name, value):
+        """
+        Updates the value of a condition and checks if the associated status is triggered.
+        """
+        self._conditions[condition_name]['value'] = value
+        self._logger.info(f"Condition '{condition_name}' updated: {value}.")
+
+    def _setup_subscription(self, condition_name, topic_name, msg_type, value_check=None):
+        """
+        Sets up a subscription to a topic and returns a function that checks for the desired condition.
+        """
+        sub = self.node.create_subscription(
+            msg_type, 
+            topic_name, 
+            lambda msg: self._update_condition(condition_name, value_check(msg) if value_check else True),
+            10
+        )
+
+        return sub
+
+    def _setup_client(self,
+            condition_name, 
+            service_name, 
+            srv_type,
+            srv_req,
+            value_check=None,
+            period: float = 1.0,
+            start_on_status: str = None,
+            timeout: float = None
+        ):
+        """
+        Sets up a service client that periodically calls the service and updates the condition based on the response.
+        """
+        client = self.node.create_client(
+            srv_type, 
+            service_name
+        )
+        
+        def service_poll_worker():
+            """Background thread that periodically calls the service and updates the condition status."""
+            
+            worker_start_time = None
+
+            def check_timeout_breach():
+                if timeout is not None and (time.time() - worker_start_time) > timeout:
+                    self.node.get_logger().error(f"[{condition_name}] Master timeout of {timeout}s exceeded.")
+                    # Explicitly fail the condition so the test state knows it timed out
+                    self._update_condition(condition_name, False)
+                    self._update_condition(f'{condition_name}_timeout', True)  # Set the timeout flag
+                    return True
+                return False
+            
+            if start_on_status:
+                # Wait until the specified status is triggered before starting the service calls
+                while rclpy.ok() and not self._stop_event.is_set():
+                    if self.get_status(start_on_status):
+                        worker_start_time = time.time()
+                        break
+                    time.sleep(0.1)
+            else:
+                worker_start_time = time.time()
+            
+            # Wait for the service to become available
+            while rclpy.ok() and not self._stop_event.is_set():
+                if check_timeout_breach():
+                    return
+                if client.wait_for_service(timeout_sec=1.0):
+                    break
+
+            # Periodically call the service and check the response
+            while rclpy.ok() and not self._stop_event.is_set():
+                if check_timeout_breach():
+                    return
+                start_time = time.time()
+                # Before making the service call, check if the condition has already been met to avoid unnecessary calls
+                if self._conditions[condition_name]['value']:
+                    break
+
+                req = srv_req() if callable(srv_req) else srv_req
+
+                future = client.call_async(req)
+                
+                timeout_limit = 5.0
+                while rclpy.ok() and not self._stop_event.is_set() and not future.done():
+                    if time.time() - start_time > timeout_limit:
+                        break
+                    time.sleep(0.01) # Cooperatively yield execution slice
+
+                if future.done():
+                    try:
+                        response = future.result()
+                        if value_check is None or value_check(response):
+                            self._update_condition(condition_name, True)
+                            break
+                    except Exception as e:
+                        self.node.get_logger().error(f"Service call failed: {e}")
+                else:
+                    self.node.get_logger().error("Service call timed out")
+
+                elapsed = time.time() - start_time
+                time_to_sleep = max(0, period - elapsed)
+                time.sleep(time_to_sleep)    
+        
+        poll_thread = threading.Thread(target=service_poll_worker, daemon=True)
+        poll_thread.start()
+    
+
+    def _run(self):
+        """Internal background loop running the executor."""
+        self._is_running.set()
+        
+        while rclpy.ok() and not self._stop_event.is_set():
+            # Safely process pending callbacks on the internal node
+            self._executor.spin_once(timeout_sec=0.0)
+
+            # Check for episode timeout
+            if self._timeout is not None and (time.time() - self._start_time) > self._timeout:
+                self.node.get_logger().error(f"Episode timeout of {self._timeout}s exceeded.")
+                self._update_condition('episode_timeout', True)
+
+                break
+                
+
+    def shutdown(self):
+        """
+        Shuts down the internal ROS node and cleans up resources.
+        """
+        self._stop_event.set()
+        
+        if hasattr(self, '_executor'):
+            self._executor.shutdown()
+            
+        if hasattr(self, '_spin_thread') and self._spin_thread.is_alive():
+            self._spin_thread.join(timeout=1.0)
+            
+        # Clean up the node itself
+        if hasattr(self, 'node'):
+            self.node.destroy_node()

pytest_ros-0.1.0/src/pytest_ros/plugin.py

@@ -0,0 +1,32 @@
+import pytest
+
+from pytest_ros import RCLPY_AVAILABLE
+if RCLPY_AVAILABLE:
+    import rclpy
+
+from .process import ROSProcessManager
+from .monitor import EpisodeMonitor
+ 
+
+
+@pytest.fixture(scope="session", autouse=True)
+def ros_context():
+    """Session-scoped fixture to manage ROS context initialization and shutdown."""
+    rclpy.init()
+    yield
+    if rclpy.ok():
+        rclpy.shutdown()
+
+@pytest.fixture
+def ros_process_manager():
+    """Factory fixture to manage ROS launch processes."""
+    manager = ROSProcessManager()
+    yield manager
+    manager.terminate_all()  # Ensure all ROS processes are terminated at the end of the session
+
+@pytest.fixture
+def ros_monitor():
+    """Fixture to provide an EpisodeMonitor instance for monitoring test conditions."""  
+    monitor = EpisodeMonitor(name="episode_monitor")
+    yield monitor
+    monitor.shutdown()

pytest_ros-0.1.0/src/pytest_ros/process.py

@@ -0,0 +1,108 @@
+import signal
+import subprocess
+import uuid
+import os
+import psutil
+
+
+class MultiProcessManager:
+    """
+    A utility class to manage multiple processes in a pytest session, 
+    ensuring that all processes are properly terminated at the end of the session.
+    """
+    def __init__(self, tag="PYTEST_MULTIPROC_ID"):
+        self.tag = tag
+        self.session_id = str(uuid.uuid4())
+        self.processes = []
+
+    def runner(self, cmd):
+        # Inject the tag into the environment
+        env = os.environ.copy()
+        env[self.tag] = self.session_id
+        
+        # Start the process group
+        proc = subprocess.Popen(
+            cmd, 
+            env=env, 
+            preexec_fn=os.setsid,
+            shell=True
+        )
+        
+        self.processes.append(proc)
+
+        return proc
+
+
+    def stop_process(self, proc):
+        """Kill a process group."""
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+
+        if proc in self.processes:
+            self.processes.remove(proc)
+
+    def terminate_all(self):
+        """Kills everything tagged with this session ID."""
+        for proc in list(self.processes):
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+
+        for proc in psutil.process_iter(['environ']):
+            try:
+                if (env := proc.info.get('environ')) and env.get(self.tag) == self.session_id:
+                    proc.send_signal(signal.SIGKILL)
+            except (psutil.NoSuchProcess, psutil.AccessDenied):
+                continue
+
+
+class ROSProcessManager(MultiProcessManager):
+    """
+    A specialized context manager for managing ROS processes, ensuring that all ROS nodes
+    launched during the pytest session are properly terminated at the end of the session.
+    
+    Manages ROS 2 launch files.
+
+    Example:
+    with orch.launch(package_name='my_package', launch_file='my_launch.py', arguments=['arg1:=value1']):
+        # Run tests that depend on the launched ROS nodes
+    """
+    def __init__(self, ):
+        super().__init__(tag="ROS_SESSION_ID")
+
+    def launch(self, package_name, launch_file, arguments=None):
+        """
+        Launches a ROS 2 launch file.
+        
+        Returns a context manager that can be used to manage the lifecycle of the launched processes.
+
+        Example: orch.launch(arguments=['arg1:=value1', 'arg2:=value2'])
+        """
+        cmd = ["ros2", "launch", package_name, launch_file]
+        if arguments:
+            cmd.extend(arguments)
+
+        cmd = ' '.join(cmd)  # Join the command list into a single string for better logging
+
+        print(f"Launching ROS with command: {cmd}")  # Debug statement to verify the command being launched
+        
+        # This uses the 'runner' context manager from the base class
+        return self.runner(cmd)
+    
+
+    def run(self, package_name, run_process, arguments=None):
+        """        
+        Returns a context manager that can be used to manage the lifecycle of the run process.
+
+        Example: orch.run(package_name='my_package', run_process='my_run.py', arguments=['arg1:=value1', 'arg2:=value2'])
+        """
+        cmd = ["ros2", "run", package_name, run_process]
+        if arguments:
+            cmd.extend(arguments)
+        
+        # This uses the 'runner' context manager from the base class
+        return self.runner(cmd)
+    

pytest_ros-0.1.0/src/pytest_ros/video_recorder.py

@@ -0,0 +1,108 @@
+import cv2
+import logging
+import numpy as np
+import threading
+
+from pytest_ros import RCLPY_AVAILABLE
+if RCLPY_AVAILABLE:
+    import rclpy
+    from rclpy.node import Node
+    from sensor_msgs.msg import Image
+
+logger = logging.getLogger(__name__)
+
+class VideoRecorder:
+    """
+    This utility enables direct recording of ROS image topics to MP4 files for assessment purposes.
+    It is not intended for logging but rather for quick visual verification of test runs.
+    
+    Subscribes to a ROS image topic and writes frames to an MP4 file.
+
+    Usage::
+        recorder = VideoRecorder(node, CAMERA_TOPIC, "/tmp/sim_logs/run.mp4")
+        recorder.start()
+        # ... run test ...
+        recorder.stop()   # flushes and closes the file
+    """
+
+    def __init__(
+            self, 
+            node, 
+            topic: str, 
+            output_path: str, 
+            fps: int = 12
+        ):
+        if type(node) is str:
+            rclpy.init()
+            node = rclpy.create_node(node)
+        self._node = node
+        self._output_path = output_path
+        self._fps = fps
+        self._writer: cv2.VideoWriter | None = None
+        self._lock = threading.Lock()
+        self._sub = None
+        self._topic = topic
+
+    def start(self) -> None:
+        self._sub = self._node.create_subscription(
+            Image,
+            self._topic,
+            self._on_image,
+            10,
+        )
+        logger.info(f"[VIDEO] Recording {self._topic} → {self._output_path}")
+
+    def stop(self) -> None:
+        if self._sub is not None:
+            self._node.destroy_subscription(self._sub)
+            self._sub = None
+        with self._lock:
+            if self._writer is not None:
+                self._writer.release()
+                self._writer = None
+                logger.info(f"[VIDEO] Saved {self._output_path}")
+
+    def _on_image(self, msg: Image) -> None:
+        """Convert a sensor_msgs/Image to BGR and append to the video file."""
+        try:
+            frame = self._decode(msg)
+        except Exception as exc:
+            logger.warning(f"[VIDEO] Frame decode error: {exc}")
+            return
+
+        with self._lock:
+            if self._writer is None:
+                h, w = frame.shape[:2]
+                fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+                self._writer = cv2.VideoWriter(
+                    self._output_path, fourcc, self._fps, (w, h)
+                )
+            self._writer.write(frame)
+
+    @staticmethod
+    def _decode(msg: Image) -> np.ndarray:
+        """Return a BGR uint8 ndarray from a sensor_msgs/Image."""
+        enc = msg.encoding.lower()
+        data = np.frombuffer(msg.data, dtype=np.uint8)
+
+        if enc in ("rgb8", "bgr8", "mono8"):
+            channels = 1 if enc == "mono8" else 3
+            frame = data.reshape((msg.height, msg.width, channels))
+            if enc == "rgb8":
+                frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
+            elif enc == "mono8":
+                frame = cv2.cvtColor(frame, cv2.COLOR_GRAY2BGR)
+        elif enc == "rgba8":
+            frame = data.reshape((msg.height, msg.width, 4))
+            frame = cv2.cvtColor(frame, cv2.COLOR_RGBA2BGR)
+        elif enc in ("16uc1", "mono16"):
+            data16 = np.frombuffer(msg.data, dtype=np.uint16).reshape(
+                (msg.height, msg.width)
+            )
+            frame = cv2.cvtColor(
+                (data16 >> 8).astype(np.uint8), cv2.COLOR_GRAY2BGR
+            )
+        else:
+            raise ValueError(f"Unsupported encoding: {msg.encoding}")
+
+        return frame