lte-launch-test 0.1.0__tar.gz

lte_launch_test-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Spencer Diehl
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

lte_launch_test-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+# The sdist is the package; tests need their launch files and ROS.
+prune test

lte_launch_test-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: lte-launch-test
+Version: 0.1.0
+Summary: ROS 2 launch tests on pytest, a launch_testing replacement on libtmux_easy
+Home-page: https://github.com/bigdiehl/lte_launch_test
+Author: Spencer Diehl
+Author-email: docdiehl@gmail.com
+License: Apache-2.0
+Keywords: ros2,ros,launch,testing,pytest,launch_testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: libtmux-easy>=0.2.0
+Requires-Dist: pytest<9,>=7.0
+Requires-Dist: pyyaml
+Dynamic: license-file
+
+# lte_launch_test
+
+ROS 2 launch tests on pytest: a replacement for `ros2 launch_test` /
+`launch_testing`. [libtmux_easy](https://github.com/nasa-jpl/libtmux_easy)'s pytest plugin runs the
+processes (subprocesses by default, tmux with `--tmux`); this package adds
+the ROS parts. libtmux_easy stays ROS-agnostic.
+
+Processes are shell commands; a launch file is one too (`ros2 launch
+file.py`). Design and `launch_testing` parity: [docs/](docs/README.md).
+
+ROS 2 Humble and Jazzy.
+
+## Install
+
+| how | |
+|---|---|
+| pip | `pip install lte-launch-test` in a venv made with `--system-site-packages` (it needs ROS's `rclpy`) |
+| `.deb` (Ubuntu 24.04) | from the GitHub Releases, with libtmux_easy's |
+| colcon | in your workspace's `src/`, with `package.xml` |
+
+Details: [docs/packaging.md](docs/packaging.md).
+
+## Quick start
+
+```bash
+cd examples
+./run.sh test_01_topic.py -v                      # start here; numbered simplest first
+LTE_DEMO_CRASH=1 ./run.sh test_09_tour.py -v      # a node dies mid-scenario
+./run.sh                                          # all of them
+./run.sh --tmux                                   # the dashboard; --no-attach: detached tmux
+./run.sh --keep-open                              # leave every node running after the run
+./run.sh failing                                  # each fails on purpose
+```
+
+`run.sh` uses ROS as sourced (else `/opt/ros/$ROS_DISTRO`, default Jazzy), puts `src/` on the path, and uses
+`../libtmux_easy/src` if libtmux_easy isn't installed.
+
+## Use
+
+```python
+# conftest.py
+pytest_plugins = ["lte_launch_test.plugin"]
+```
+
+| name | what |
+|---|---|
+| `lte_launch_test.plugin` | a per-run `ROS_DOMAIN_ID` (reserved via `domain_coordinator`) + localhost discovery; every process inherits pytest's environment (ROS and overlays), runs in the rootdir, logs ROS to `$LTE_LOG_DIR/ros`; a `RosProbe` made in a test is destroyed after it |
+| `RosProbe(log_dir=)` | rclpy node (does `rclpy.init()` first; its ROS logs in `<log_dir>/ros_probe`); `with RosProbe() as probe:` in a test, or `RosProbe()` in `setup_class` and `destroy()` in teardown; subscribes with QoS that matches any publisher; waits (`wait_for_nodes`, `wait_for_topics`, `wait_for_services`, `wait_for_messages`, `rate`, `call`, `publish_until`) call `check_health()`, so a death fails them at once |
+| `RosProbe` services, params | `call(Srv, name, a=2, b=40)` (or a request); another node's parameters: `get_param(node, name)`, `get_params`, `set_param(node, name, value)`, `set_params(node, {...})` (fails with the node's reason if rejected), `list_params(node)` |
+| `RosProbe` tf | `wait_for_transform(target, source)`: a `TransformStamped` once tf has it (chains through the tree); the failure lists the transforms it has |
+| `launch_death(allow=)` | `fail_on` check: a node died inside `ros2 launch` (non-zero exit; SIGINT/SIGTERM and exit 0 are fine) |
+| `composable_failure(allow=)` | `fail_on` check: a composable node failed to load (launch's `Failed to load node`, or the container's `Failed to find class` / `Could not find requested resource` / `Failed to load library`) |
+| `wait_for_bag_topics(procs, name, topics, timeout)` | wait for `ros2 bag record` process `name` to subscribe to all its topics; fails naming the missing ones |
+| `check_bag(bag_dir, min_messages)` | after the recorder stopped: fail on each topic below its `{topic: n}` count (from `metadata.yaml`); `bag_counts()`: `{topic: n}` |
+| `Processes`, `check_health`, `arg`, `parametrize` | re-exported from `libtmux_easy.testing` |
+
+## colcon
+
+Verified with `colcon test` on Jazzy, for both build types. Put
+`test/conftest.py` (`pytest_plugins = [...]`) next to the tests; libtmux_easy and
+lte_launch_test must be importable (installed, or on `PYTHONPATH`).
+
+| build type | add |
+|---|---|
+| `ament_python` | nothing: colcon runs pytest on `test/` |
+| `ament_cmake` | `find_package(ament_cmake_pytest REQUIRED)` and `ament_add_pytest_test(test_talker test/test_talker.py TIMEOUT 120)` |
+
+## Layout
+
+| path | what |
+|---|---|
+| `src/lte_launch_test/` | the package |
+| `docs/` | design, `launch_testing` parity, packaging, [future development](docs/FUTURE_DEVELOPMENT.md) |
+| `examples/` | numbered example tests, simplest first; `failing/` fails on purpose. See [examples/](examples/README.md) |
+| `test/` | `test/run.sh`: every failure check, unit and live (launch deaths, container crash, composable load errors, bag topics/counts, probe waits, services, params, tf), and that `examples/failing` fails as documented |
+| `debian/`, `package.xml`, `setup.cfg` | the `.deb`, colcon, pip |
+| `.github/workflows/` | CI (Humble, Jazzy), release |
+
+## Notes
+
+- A failed test stops its class's processes at once (SIGINT, escalating;
+  `on_abort=` first, if given) and skips the rest of the class.
+  `--keep-open` keeps them instead.
+- Logs: each process's output and ROS logs go to pytest's tmp dir, printed
+  at the end as `process logs: <dir>`.
+- A node that should exit 0 on SIGINT must catch `KeyboardInterrupt` /
+  `ExternalShutdownException` around `rclpy.spin()` (see `examples/nodes/counter_node.py`).
+- A stopped node's name can linger in the graph briefly. Give per-test
+  nodes names of their own (`-r __node:=...`).

lte_launch_test-0.1.0/README.md

@@ -0,0 +1,89 @@
+# lte_launch_test
+
+ROS 2 launch tests on pytest: a replacement for `ros2 launch_test` /
+`launch_testing`. [libtmux_easy](https://github.com/nasa-jpl/libtmux_easy)'s pytest plugin runs the
+processes (subprocesses by default, tmux with `--tmux`); this package adds
+the ROS parts. libtmux_easy stays ROS-agnostic.
+
+Processes are shell commands; a launch file is one too (`ros2 launch
+file.py`). Design and `launch_testing` parity: [docs/](docs/README.md).
+
+ROS 2 Humble and Jazzy.
+
+## Install
+
+| how | |
+|---|---|
+| pip | `pip install lte-launch-test` in a venv made with `--system-site-packages` (it needs ROS's `rclpy`) |
+| `.deb` (Ubuntu 24.04) | from the GitHub Releases, with libtmux_easy's |
+| colcon | in your workspace's `src/`, with `package.xml` |
+
+Details: [docs/packaging.md](docs/packaging.md).
+
+## Quick start
+
+```bash
+cd examples
+./run.sh test_01_topic.py -v                      # start here; numbered simplest first
+LTE_DEMO_CRASH=1 ./run.sh test_09_tour.py -v      # a node dies mid-scenario
+./run.sh                                          # all of them
+./run.sh --tmux                                   # the dashboard; --no-attach: detached tmux
+./run.sh --keep-open                              # leave every node running after the run
+./run.sh failing                                  # each fails on purpose
+```
+
+`run.sh` uses ROS as sourced (else `/opt/ros/$ROS_DISTRO`, default Jazzy), puts `src/` on the path, and uses
+`../libtmux_easy/src` if libtmux_easy isn't installed.
+
+## Use
+
+```python
+# conftest.py
+pytest_plugins = ["lte_launch_test.plugin"]
+```
+
+| name | what |
+|---|---|
+| `lte_launch_test.plugin` | a per-run `ROS_DOMAIN_ID` (reserved via `domain_coordinator`) + localhost discovery; every process inherits pytest's environment (ROS and overlays), runs in the rootdir, logs ROS to `$LTE_LOG_DIR/ros`; a `RosProbe` made in a test is destroyed after it |
+| `RosProbe(log_dir=)` | rclpy node (does `rclpy.init()` first; its ROS logs in `<log_dir>/ros_probe`); `with RosProbe() as probe:` in a test, or `RosProbe()` in `setup_class` and `destroy()` in teardown; subscribes with QoS that matches any publisher; waits (`wait_for_nodes`, `wait_for_topics`, `wait_for_services`, `wait_for_messages`, `rate`, `call`, `publish_until`) call `check_health()`, so a death fails them at once |
+| `RosProbe` services, params | `call(Srv, name, a=2, b=40)` (or a request); another node's parameters: `get_param(node, name)`, `get_params`, `set_param(node, name, value)`, `set_params(node, {...})` (fails with the node's reason if rejected), `list_params(node)` |
+| `RosProbe` tf | `wait_for_transform(target, source)`: a `TransformStamped` once tf has it (chains through the tree); the failure lists the transforms it has |
+| `launch_death(allow=)` | `fail_on` check: a node died inside `ros2 launch` (non-zero exit; SIGINT/SIGTERM and exit 0 are fine) |
+| `composable_failure(allow=)` | `fail_on` check: a composable node failed to load (launch's `Failed to load node`, or the container's `Failed to find class` / `Could not find requested resource` / `Failed to load library`) |
+| `wait_for_bag_topics(procs, name, topics, timeout)` | wait for `ros2 bag record` process `name` to subscribe to all its topics; fails naming the missing ones |
+| `check_bag(bag_dir, min_messages)` | after the recorder stopped: fail on each topic below its `{topic: n}` count (from `metadata.yaml`); `bag_counts()`: `{topic: n}` |
+| `Processes`, `check_health`, `arg`, `parametrize` | re-exported from `libtmux_easy.testing` |
+
+## colcon
+
+Verified with `colcon test` on Jazzy, for both build types. Put
+`test/conftest.py` (`pytest_plugins = [...]`) next to the tests; libtmux_easy and
+lte_launch_test must be importable (installed, or on `PYTHONPATH`).
+
+| build type | add |
+|---|---|
+| `ament_python` | nothing: colcon runs pytest on `test/` |
+| `ament_cmake` | `find_package(ament_cmake_pytest REQUIRED)` and `ament_add_pytest_test(test_talker test/test_talker.py TIMEOUT 120)` |
+
+## Layout
+
+| path | what |
+|---|---|
+| `src/lte_launch_test/` | the package |
+| `docs/` | design, `launch_testing` parity, packaging, [future development](docs/FUTURE_DEVELOPMENT.md) |
+| `examples/` | numbered example tests, simplest first; `failing/` fails on purpose. See [examples/](examples/README.md) |
+| `test/` | `test/run.sh`: every failure check, unit and live (launch deaths, container crash, composable load errors, bag topics/counts, probe waits, services, params, tf), and that `examples/failing` fails as documented |
+| `debian/`, `package.xml`, `setup.cfg` | the `.deb`, colcon, pip |
+| `.github/workflows/` | CI (Humble, Jazzy), release |
+
+## Notes
+
+- A failed test stops its class's processes at once (SIGINT, escalating;
+  `on_abort=` first, if given) and skips the rest of the class.
+  `--keep-open` keeps them instead.
+- Logs: each process's output and ROS logs go to pytest's tmp dir, printed
+  at the end as `process logs: <dir>`.
+- A node that should exit 0 on SIGINT must catch `KeyboardInterrupt` /
+  `ExternalShutdownException` around `rclpy.spin()` (see `examples/nodes/counter_node.py`).
+- A stopped node's name can linger in the graph briefly. Give per-test
+  nodes names of their own (`-r __node:=...`).

lte_launch_test-0.1.0/package.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>lte_launch_test</name>
+  <version>0.1.0</version>
+  <description>ROS 2 launch tests on pytest, a launch_testing replacement on libtmux_easy</description>
+  <maintainer email="docdiehl@gmail.com">Spencer Diehl</maintainer>
+  <license>Apache-2.0</license>
+  <url type="repository">https://github.com/bigdiehl/lte_launch_test</url>
+
+  <!-- libtmux_easy has no rosdep key: pip install libtmux-easy, or its .deb. -->
+  <exec_depend>domain_coordinator</exec_depend>
+  <exec_depend>python3-pytest</exec_depend>
+  <exec_depend>python3-yaml</exec_depend>
+  <exec_depend>rcl_interfaces</exec_depend>
+  <exec_depend>rclpy</exec_depend>
+  <exec_depend>tf2_ros_py</exec_depend>
+  <exec_depend>tmux</exec_depend>
+
+  <!-- test/ and examples/ -->
+  <test_depend>composition</test_depend>
+  <test_depend>demo_nodes_cpp</test_depend>
+  <test_depend>demo_nodes_py</test_depend>
+  <test_depend>example_interfaces</test_depend>
+  <test_depend>launch_ros</test_depend>
+  <test_depend>rclcpp_components</test_depend>
+  <test_depend>ros2bag</test_depend>
+  <test_depend>rosbag2</test_depend>
+  <test_depend>std_msgs</test_depend>
+  <test_depend>std_srvs</test_depend>
+  <test_depend>tf2_msgs</test_depend>
+  <test_depend>tf2_ros</test_depend>
+
+  <export>
+    <build_type>ament_python</build_type>
+  </export>
+</package>

lte_launch_test-0.1.0/pyproject.toml

@@ -0,0 +1,5 @@
+# Metadata is in setup.cfg: Ubuntu 22.04's setuptools (59, what colcon uses
+# on Humble) can't read a [project] table.
+[build-system]
+requires = ["setuptools>=59"]
+build-backend = "setuptools.build_meta"

lte_launch_test-0.1.0/setup.cfg

@@ -0,0 +1,42 @@
+[metadata]
+name = lte-launch-test
+version = 0.1.0
+description = ROS 2 launch tests on pytest, a launch_testing replacement on libtmux_easy
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/bigdiehl/lte_launch_test
+author = Spencer Diehl
+author_email = docdiehl@gmail.com
+license = Apache-2.0
+license_files = LICENSE
+keywords = ros2, ros, launch, testing, pytest, launch_testing
+classifiers = 
+	Development Status :: 4 - Beta
+	Framework :: Pytest
+	Intended Audience :: Developers
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3.10
+	Programming Language :: Python :: 3.12
+	Topic :: Software Development :: Testing
+
+[options]
+package_dir = 
+	= src
+packages = find:
+python_requires = >=3.10
+install_requires = 
+	libtmux-easy>=0.2.0
+	pytest>=7.0,<9
+	pyyaml
+
+[options.packages.find]
+where = src
+
+[options.data_files]
+share/ament_index/resource_index/packages = resource/lte_launch_test
+share/lte_launch_test = package.xml
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

lte_launch_test-0.1.0/setup.py

@@ -0,0 +1,4 @@
+# Metadata: setup.cfg. This file is for colcon (ament_python) and pybuild.
+from setuptools import setup
+
+setup()

lte_launch_test-0.1.0/src/lte_launch_test/__init__.py

@@ -0,0 +1,44 @@
+"""ROS 2 launch tests on pytest, with libtmux_easy running the processes.
+
+libtmux_easy.testing does the generic work (start, watch, stop, logs,
+--tmux, --keep-open); this adds the ROS parts. Enable with:
+
+    pytest_plugins = ["lte_launch_test.plugin"]      # in conftest.py
+"""
+
+import os
+
+import pytest
+
+if "ROS_DISTRO" not in os.environ:
+    raise ImportError(
+        "lte_launch_test: source ROS 2 first, e.g. source /opt/ros/jazzy/setup.bash"
+    )
+
+# Imported below, before pytest loads it as a plugin: rewrite its asserts anyway.
+pytest.register_assert_rewrite("libtmux_easy.testing")
+
+from libtmux_easy.testing import Processes, arg, check_health, parametrize  # noqa: E402
+
+from .bag import (
+    ALL_SUBSCRIBED,
+    bag_counts,
+    check_bag,
+    wait_for_bag_topics,
+)  # noqa: E402
+from .checks import composable_failure, launch_death  # noqa: E402
+from .probe import RosProbe  # noqa: E402
+
+__all__ = [
+    "ALL_SUBSCRIBED",
+    "Processes",
+    "RosProbe",
+    "arg",
+    "bag_counts",
+    "check_bag",
+    "check_health",
+    "composable_failure",
+    "launch_death",
+    "parametrize",
+    "wait_for_bag_topics",
+]

lte_launch_test-0.1.0/src/lte_launch_test/bag.py

@@ -0,0 +1,52 @@
+"""Checks on a 'ros2 bag record' process: it found every topic it was
+asked for, and its bag holds enough messages."""
+
+import os
+import re
+
+import yaml
+
+# rosbag2's recorder, once it has subscribed to every topic it was given.
+ALL_SUBSCRIBED = "All requested topics are subscribed"
+_SUBSCRIBED = re.compile(r"Subscribed to topic '([^']+)'")
+
+
+def wait_for_bag_topics(procs, name, topics, timeout=30.0):
+    """Wait for recorder 'name' to subscribe to all its 'topics'; fails
+    naming the ones it hasn't after 'timeout' s."""
+    try:
+        procs.wait_for(name, ALL_SUBSCRIBED, timeout)
+    except AssertionError as exc:
+        missing = sorted(set(topics) - set(_SUBSCRIBED.findall(procs.output(name))))
+        # Keep the cause: the recorder may have died, not just not found them.
+        raise AssertionError(
+            f"{name}: not subscribed to {', '.join(missing) or '?'}" f"\n{exc}"
+        ) from None
+
+
+def bag_counts(bag_dir):
+    """{topic: messages} from the bag's metadata.yaml, which the recorder
+    writes when it stops."""
+    with open(os.path.join(bag_dir, "metadata.yaml")) as f:
+        info = yaml.safe_load(f)["rosbag2_bagfile_information"]
+    return {
+        t["topic_metadata"]["name"]: t["message_count"]
+        for t in info["topics_with_message_count"]
+    }
+
+
+def check_bag(bag_dir, min_messages):
+    """Fail naming each topic with fewer messages than min_messages[topic].
+    Stop the recorder first."""
+    try:
+        counts = bag_counts(bag_dir)
+    except FileNotFoundError:
+        raise AssertionError(
+            f"no {bag_dir}/metadata.yaml: stop the recorder first"
+        ) from None
+    low = [
+        f"{topic}: {counts.get(topic, 0)} messages, want at least {n}"
+        for topic, n in min_messages.items()
+        if counts.get(topic, 0) < n
+    ]
+    assert not low, f"bag {bag_dir}:\n  " + "\n  ".join(low)

lte_launch_test-0.1.0/src/lte_launch_test/checks.py

@@ -0,0 +1,72 @@
+"""fail_on checks for ROS output."""
+
+import re
+
+# 'ros2 launch' reports a node's death in its output and keeps running.
+_LAUNCH_DIED = re.compile(
+    r"\[ERROR\] \[(?P<name>[\w.]+?)(-\d+)?\]: process has died "
+    r"\[pid \d+, exit code (?P<code>-?\d+)"
+)
+
+# A composable node 'ros2 launch' could not load into its container.
+_LOAD_FAILED = re.compile(
+    r"\[ERROR\] \[launch_ros\.actions\.load_composable_nodes\]: "
+    r"Failed to load node '(?P<name>[^']+)' of type '(?P<type>[^']+)' "
+    r"in container '(?P<container>[^']+)': (?P<reason>.*)"
+)
+
+# The container's own log, when it cannot create a component: its logger
+# name, and the plugin only for a missing class.
+_CONTAINER_ERROR = re.compile(
+    r"\[ERROR\] .*?\[(?P<container>[^\]]+)\]: (?P<what>Failed to find class with the requested "
+    r"plugin name(?: '(?P<plugin>[^']*)')?|Could not find requested "
+    r"resource in ament index|Failed to load library)"
+)
+
+# Exit codes launch reports for a stop on purpose: SIGINT or SIGTERM, as a
+# signal (-N) or a shell status (128+N). Same semantics as classify() in
+# core_launch's launch_monitor.py (kept apart: this package doesn't import it).
+_STOP_CODES = {-2, -15, 130, 143}
+
+
+def _is_failure(code):
+    """Exit 0 and SIGINT/SIGTERM are not; any other code is."""
+    return code != 0 and code not in _STOP_CODES
+
+
+def launch_death(allow=()):
+    """A fail_on check: a node died inside 'ros2 launch'. Exit 0, a stop by
+    SIGINT/SIGTERM, and the names in 'allow', are fine."""
+    allow = set(allow)
+
+    def check(line):
+        m = _LAUNCH_DIED.search(line)
+        if m and _is_failure(int(m["code"])) and m["name"] not in allow:
+            return f"node {m['name']} died (exit code {m['code']})"
+
+    return check
+
+
+def composable_failure(allow=()):
+    """A fail_on check: a composable node failed to load, from 'ros2 launch'
+    ("Failed to load node ...") or from the container's own error ("Failed to
+    find class", "Could not find requested resource", "Failed to load
+    library"). 'allow': node names, types or containers ("/cont" from launch,
+    "cont" from the container's log) and plugin names to ignore. The container's
+    "Could not find requested resource" line names no node: allow the container."""
+    allow = set(allow)
+
+    def check(line):
+        m = _LOAD_FAILED.search(line)
+        if m:
+            if {m["name"], m["type"], m["container"]} & allow:
+                return None
+            return (
+                f"composable node {m['name']} ({m['type']}) failed to load "
+                f"in {m['container']}: {m['reason'].strip()}"
+            )
+        m = _CONTAINER_ERROR.search(line)
+        if m and not {m["plugin"], m["container"]} & allow:
+            return f"container error: {m['what']}"
+
+    return check

lte_launch_test-0.1.0/src/lte_launch_test/plugin.py

@@ -0,0 +1,83 @@
+"""The pytest plugin: libtmux_easy.testing, plus
+
+  - each run its own ROS_DOMAIN_ID (reserved through domain_coordinator, as
+    launch_testing_ros does), localhost only
+  - lte_pane_setup: every process runs in pytest's rootdir, in this run's
+    domain, and writes its ROS logs next to its process log (LTE_LOG_DIR)
+  - a RosProbe made in a test is destroyed after it
+  - pytest's own ignores (--ignore, collect_ignore, norecursedirs) work
+    beside launch_testing 3.4.12, which disables them
+"""
+
+import os
+import shlex
+
+import pytest
+from domain_coordinator import domain_id
+
+
+# Before rclpy.init(), and given to every process: keep this run's DDS
+# traffic to itself and to this machine. The domain stays reserved (a bound
+# port) until the run ends, so runs at once get different ones.
+if "ROS_DOMAIN_ID" not in os.environ:
+    _domain = domain_id()
+    os.environ["ROS_DOMAIN_ID"] = str(_domain.__enter__())
+# Localhost only: Humble's switch; Iron and later replaced it.
+_LOCAL = (
+    ("ROS_LOCALHOST_ONLY", "1")
+    if os.environ.get("ROS_DISTRO") == "humble"
+    else ("ROS_AUTOMATIC_DISCOVERY_RANGE", "LOCALHOST")
+)
+os.environ.setdefault(*_LOCAL)
+
+from . import probe as _probe
+
+pytest_plugins = ["libtmux_easy.testing"]
+
+
+@pytest.fixture(scope="session")
+def lte_pane_setup(pytestconfig):
+    # Processes inherit pytest's environment, ROS and any overlay included:
+    # sourcing ROS again would put the underlay first.
+    return (
+        f"export ROS_DOMAIN_ID={os.environ['ROS_DOMAIN_ID']}"
+        f" {_LOCAL[0]}={os.environ[_LOCAL[0]]}"
+        ' ROS_LOG_DIR="$LTE_LOG_DIR/ros"'
+        f" && cd {shlex.quote(str(pytestconfig.rootpath))}"
+    )
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_call(item):
+    """A RosProbe made in a test is destroyed after it, 'with' or not."""
+    _probe._test_probes = []
+    try:
+        yield
+    finally:
+        made, _probe._test_probes = _probe._test_probes, None
+        for probe in made:
+            probe.destroy()
+
+
+# Workaround: launch_testing 3.4.12 (Jazzy's apt package) disables pytest's
+# --ignore, collect_ignore and norecursedirs for every project with ROS sourced.
+#
+# pytest asks pytest_ignore_collect(path) of every plugin before collecting a
+# path; the first answer that isn't None wins. pytest's own ignore rules are
+# its default implementation of that hook. launch_testing 3.4.12 registers one
+# with tryfirst=True that returns False ("don't ignore") for everything but
+# launch files, so pytest's default is never asked. (Fixed upstream: it returns
+# None now. Seen in CI: examples/failing/ collected despite norecursedirs.)
+#
+# This hook is tryfirst too, and registered later (conftest pytest_plugins load
+# after setuptools entry points), so pluggy calls it first. It asks pytest's
+# default: True (ignore) wins; else None, and the other hooks decide as before.
+# _pytest.main is private, but this function has had this signature since
+# pytest 7. Remove once Jazzy ships the fix: test/test_plugin_collect.py checks
+# both the bug and this workaround.
+@pytest.hookimpl(tryfirst=True)
+def pytest_ignore_collect(collection_path, config):
+    """pytest's own ignores first: --ignore, collect_ignore, norecursedirs."""
+    from _pytest.main import pytest_ignore_collect as pytest_default
+
+    return True if pytest_default(collection_path=collection_path, config=config) else None

lte_launch_test-0.1.0/src/lte_launch_test/probe.py

@@ -0,0 +1,273 @@
+"""RosProbe: an rclpy node the tests talk to the system with. Nothing here
+knows about tmux or subprocesses: libtmux_easy's check_health() is how a
+wait fails fast on a death."""
+
+import itertools
+import os
+import time
+
+import rclpy
+import rclpy.time
+import yaml
+from rcl_interfaces.msg import ParameterType
+from rcl_interfaces.srv import GetParameters, ListParameters, SetParameters
+from rclpy.parameter import Parameter, parameter_value_to_python
+from rclpy.qos import DurabilityPolicy, QoSProfile, ReliabilityPolicy
+
+from libtmux_easy.testing import check_health
+
+
+# Matches any publisher: BEST_EFFORT takes RELIABLE and BEST_EFFORT ones,
+# VOLATILE takes VOLATILE and TRANSIENT_LOCAL ones (e.g. a lidar's sensor QoS).
+ANY_PUBLISHER = QoSProfile(
+    depth=10,
+    reliability=ReliabilityPolicy.BEST_EFFORT,
+    durability=DurabilityPolicy.VOLATILE,
+)
+
+
+def ros_init(log_dir=None):
+    """rclpy.init() once per run. 'log_dir': where this process's ROS logs
+    go (ROS_LOG_DIR), read at the first init only."""
+    if not rclpy.ok():
+        if log_dir:
+            os.environ["ROS_LOG_DIR"] = str(log_dir)
+        rclpy.init()
+
+
+def _srv(node, service):
+    """'talker', 'get_parameters' -> '/talker/get_parameters'."""
+    return f"/{node.strip('/')}/{service}"
+
+
+_test_probes = None  # while a test runs (plugin.py): the RosProbes it made
+_count = itertools.count()  # node names unique within the process
+
+
+class RosProbe:
+    """An rclpy node the tests use to poke the system. Every wait calls
+    check_health(), so a dead process fails it now, not at the timeout.
+
+        cls.probe = RosProbe(log_dir=cls.procs.log_dir)   # setup_class; destroy() in teardown
+        with RosProbe() as probe:                         # in a test
+
+    One made in a test is destroyed after it, 'with' or not. rclpy.init()
+    is done by the first RosProbe of the run; 'log_dir': its ROS logs go to
+    '<log_dir>/ros_probe' (that first RosProbe's only)."""
+
+    def __init__(self, name="test_probe", log_dir=None):
+        ros_init(os.path.join(log_dir, "ros_probe") if log_dir else None)
+        n = next(_count)
+        self.node = rclpy.create_node(f"{name}_{os.getpid()}" + (f"_{n}" if n else ""))
+        self._tf = None  # (Buffer, TransformListener), on the first wait_for_transform
+        if _test_probes is not None:
+            _test_probes.append(self)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.destroy()
+
+    def destroy(self):
+        """Destroy the node; a second call does nothing."""
+        if self.node is not None:
+            if self._tf:
+                self._tf[1].unregister()
+            self.node.destroy_node()
+            self.node = None
+
+    def spin_until(self, done, timeout, what):
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            rclpy.spin_once(self.node, timeout_sec=0.1)
+            check_health()
+            result = done()
+            if result:
+                return result
+        raise AssertionError(f"timed out after {timeout}s waiting for {what}")
+
+    def nodes(self):
+        return set(self.node.get_node_names())
+
+    def wait_for_nodes(self, names, timeout=20.0):
+        self.spin_until(
+            lambda: set(names) <= self.nodes(), timeout, f"nodes {sorted(names)}"
+        )
+
+    def wait_for_nodes_gone(self, names, timeout=10.0):
+        self.spin_until(
+            lambda: not set(names) & self.nodes(),
+            timeout,
+            f"nodes {sorted(names)} to leave the graph",
+        )
+
+    def topic_types(self):
+        return dict(self.node.get_topic_names_and_types())
+
+    def wait_for_topics(self, names, timeout=10.0):
+        """The topic types, once every topic in 'names' has a type."""
+        if not names:
+            return self.topic_types()
+        try:
+
+            def have_all():
+                types = self.topic_types()
+                return set(names) <= set(types) and types
+
+            return self.spin_until(have_all, timeout, f"topics {sorted(names)}")
+        except AssertionError as exc:
+            raise AssertionError(f"{exc}; have {sorted(self.topic_types())}") from None
+
+    def wait_for_messages(
+        self, msg_type, topic, count=1, timeout=5.0, qos=ANY_PUBLISHER
+    ):
+        received = []
+        sub = self.node.create_subscription(msg_type, topic, received.append, qos)
+        try:
+            self.spin_until(
+                lambda: len(received) >= count, timeout, f"{count} on {topic}"
+            )
+            return received[:count]
+        finally:
+            self.node.destroy_subscription(sub)
+
+    def rate(self, msg_type, topic, seconds=2.0, qos=ANY_PUBLISHER):
+        """Messages per second on 'topic', counted for 'seconds'."""
+        received = []
+        sub = self.node.create_subscription(msg_type, topic, received.append, qos)
+        try:
+            self.spin_until(lambda: received, 5.0, f"a message on {topic}")
+            received.clear()
+            end = time.monotonic() + seconds
+            self.spin_until(lambda: time.monotonic() >= end, seconds + 1, "the count")
+            return len(received) / seconds
+        finally:
+            self.node.destroy_subscription(sub)
+
+    def services(self):
+        """{service: [types]} in the graph."""
+        return dict(self.node.get_service_names_and_types())
+
+    def wait_for_services(self, names, timeout=10.0):
+        """The service types, once every service in 'names' is in the graph."""
+
+        def have_all():
+            types = self.services()
+            return set(names) <= set(types) and types
+
+        try:
+            return self.spin_until(have_all, timeout, f"services {sorted(names)}")
+        except AssertionError as exc:
+            raise AssertionError(f"{exc}; have {sorted(self.services())}") from None
+
+    def call(self, srv_type, name, request=None, timeout=5.0, **fields):
+        """Call service 'name' once it is up; the reply. The request, or
+        its fields: call(AddTwoInts, "add_two_ints", a=2, b=40)."""
+        if request is None:
+            request = srv_type.Request(**fields)
+        elif fields:
+            raise TypeError("call(): a request or its fields, not both")
+        client = self.node.create_client(srv_type, name)
+        try:
+            self.spin_until(client.service_is_ready, timeout, f"service {name}")
+            future = client.call_async(request)
+            self.spin_until(future.done, timeout, f"a reply from {name}")
+            return future.result()
+        finally:
+            self.node.destroy_client(client)
+
+    def wait_for_transform(self, target, source, timeout=10.0):
+        """The latest transform from frame 'source' to frame 'target' (a
+        TransformStamped), once tf has it: wait_for_transform("map",
+        "base_link") is base_link's pose in map. Chains through the tree.
+        The probe listens to tf from its first call on; static transforms
+        are latched, so they arrive whenever it starts."""
+        if self._tf is None:
+            from tf2_ros import (
+                Buffer,
+                TransformListener,
+            )  # only tests that use tf need it
+
+            buffer = Buffer()
+            self._tf = (buffer, TransformListener(buffer, self.node))
+        buffer = self._tf[0]
+
+        def lookup():
+            if buffer.can_transform(target, source, rclpy.time.Time()):
+                return buffer.lookup_transform(target, source, rclpy.time.Time())
+
+        try:
+            return self.spin_until(lookup, timeout, f"transform {source} -> {target}")
+        except AssertionError as exc:
+            frames = yaml.safe_load(buffer.all_frames_as_yaml()) or {}
+            have = ", ".join(
+                sorted(f"{f['parent']} -> {child}" for child, f in frames.items())
+            )
+            raise AssertionError(f"{exc}; have {have or 'no transforms'}") from None
+
+    # Another node's parameters, through its parameter services. 'node': its
+    # name, "talker" or "/ns/talker".
+
+    def get_params(self, node, names, timeout=5.0):
+        """{name: value} (Python values); fails naming any 'node' hasn't set."""
+        reply = self.call(
+            GetParameters,
+            _srv(node, "get_parameters"),
+            timeout=timeout,
+            names=list(names),
+        )
+        missing = [
+            n
+            for n, v in zip(names, reply.values)
+            if v.type == ParameterType.PARAMETER_NOT_SET
+        ]
+        assert not missing, f"{node}: no parameter {', '.join(missing)}"
+        return {n: parameter_value_to_python(v) for n, v in zip(names, reply.values)}
+
+    def get_param(self, node, name, timeout=5.0):
+        return self.get_params(node, [name], timeout)[name]
+
+    def set_params(self, node, values, timeout=5.0):
+        """Set {name: value} on 'node', each on its own; fails with the
+        node's reason for each one it rejects."""
+        msgs = [Parameter(n, value=v).to_parameter_msg() for n, v in values.items()]
+        reply = self.call(
+            SetParameters,
+            _srv(node, "set_parameters"),
+            timeout=timeout,
+            parameters=msgs,
+        )
+        rejected = [
+            f"{n}: {r.reason or 'rejected'}"
+            for n, r in zip(values, reply.results)
+            if not r.successful
+        ]
+        assert not rejected, f"{node} rejected " + "; ".join(rejected)
+
+    def set_param(self, node, name, value, timeout=5.0):
+        self.set_params(node, {name: value}, timeout)
+
+    def list_params(self, node, timeout=5.0):
+        """The names of 'node''s parameters."""
+        reply = self.call(
+            ListParameters, _srv(node, "list_parameters"), timeout=timeout
+        )
+        return sorted(reply.result.names)
+
+    def publish_until(self, msg_type, topic, msg, done, timeout=5.0, what=None):
+        """Publish 'msg' every half second until done() -- a fresh publisher's
+        first messages can go out before a subscriber has matched it."""
+        pub = self.node.create_publisher(msg_type, topic, 10)
+        last = [0.0]
+
+        def step():
+            if time.monotonic() - last[0] > 0.5:
+                pub.publish(msg)
+                last[0] = time.monotonic()
+            return done()
+
+        try:
+            return self.spin_until(step, timeout, what or f"a reaction to {topic}")
+        finally:
+            self.node.destroy_publisher(pub)

lte_launch_test-0.1.0/src/lte_launch_test.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: lte-launch-test
+Version: 0.1.0
+Summary: ROS 2 launch tests on pytest, a launch_testing replacement on libtmux_easy
+Home-page: https://github.com/bigdiehl/lte_launch_test
+Author: Spencer Diehl
+Author-email: docdiehl@gmail.com
+License: Apache-2.0
+Keywords: ros2,ros,launch,testing,pytest,launch_testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: libtmux-easy>=0.2.0
+Requires-Dist: pytest<9,>=7.0
+Requires-Dist: pyyaml
+Dynamic: license-file
+
+# lte_launch_test
+
+ROS 2 launch tests on pytest: a replacement for `ros2 launch_test` /
+`launch_testing`. [libtmux_easy](https://github.com/nasa-jpl/libtmux_easy)'s pytest plugin runs the
+processes (subprocesses by default, tmux with `--tmux`); this package adds
+the ROS parts. libtmux_easy stays ROS-agnostic.
+
+Processes are shell commands; a launch file is one too (`ros2 launch
+file.py`). Design and `launch_testing` parity: [docs/](docs/README.md).
+
+ROS 2 Humble and Jazzy.
+
+## Install
+
+| how | |
+|---|---|
+| pip | `pip install lte-launch-test` in a venv made with `--system-site-packages` (it needs ROS's `rclpy`) |
+| `.deb` (Ubuntu 24.04) | from the GitHub Releases, with libtmux_easy's |
+| colcon | in your workspace's `src/`, with `package.xml` |
+
+Details: [docs/packaging.md](docs/packaging.md).
+
+## Quick start
+
+```bash
+cd examples
+./run.sh test_01_topic.py -v                      # start here; numbered simplest first
+LTE_DEMO_CRASH=1 ./run.sh test_09_tour.py -v      # a node dies mid-scenario
+./run.sh                                          # all of them
+./run.sh --tmux                                   # the dashboard; --no-attach: detached tmux
+./run.sh --keep-open                              # leave every node running after the run
+./run.sh failing                                  # each fails on purpose
+```
+
+`run.sh` uses ROS as sourced (else `/opt/ros/$ROS_DISTRO`, default Jazzy), puts `src/` on the path, and uses
+`../libtmux_easy/src` if libtmux_easy isn't installed.
+
+## Use
+
+```python
+# conftest.py
+pytest_plugins = ["lte_launch_test.plugin"]
+```
+
+| name | what |
+|---|---|
+| `lte_launch_test.plugin` | a per-run `ROS_DOMAIN_ID` (reserved via `domain_coordinator`) + localhost discovery; every process inherits pytest's environment (ROS and overlays), runs in the rootdir, logs ROS to `$LTE_LOG_DIR/ros`; a `RosProbe` made in a test is destroyed after it |
+| `RosProbe(log_dir=)` | rclpy node (does `rclpy.init()` first; its ROS logs in `<log_dir>/ros_probe`); `with RosProbe() as probe:` in a test, or `RosProbe()` in `setup_class` and `destroy()` in teardown; subscribes with QoS that matches any publisher; waits (`wait_for_nodes`, `wait_for_topics`, `wait_for_services`, `wait_for_messages`, `rate`, `call`, `publish_until`) call `check_health()`, so a death fails them at once |
+| `RosProbe` services, params | `call(Srv, name, a=2, b=40)` (or a request); another node's parameters: `get_param(node, name)`, `get_params`, `set_param(node, name, value)`, `set_params(node, {...})` (fails with the node's reason if rejected), `list_params(node)` |
+| `RosProbe` tf | `wait_for_transform(target, source)`: a `TransformStamped` once tf has it (chains through the tree); the failure lists the transforms it has |
+| `launch_death(allow=)` | `fail_on` check: a node died inside `ros2 launch` (non-zero exit; SIGINT/SIGTERM and exit 0 are fine) |
+| `composable_failure(allow=)` | `fail_on` check: a composable node failed to load (launch's `Failed to load node`, or the container's `Failed to find class` / `Could not find requested resource` / `Failed to load library`) |
+| `wait_for_bag_topics(procs, name, topics, timeout)` | wait for `ros2 bag record` process `name` to subscribe to all its topics; fails naming the missing ones |
+| `check_bag(bag_dir, min_messages)` | after the recorder stopped: fail on each topic below its `{topic: n}` count (from `metadata.yaml`); `bag_counts()`: `{topic: n}` |
+| `Processes`, `check_health`, `arg`, `parametrize` | re-exported from `libtmux_easy.testing` |
+
+## colcon
+
+Verified with `colcon test` on Jazzy, for both build types. Put
+`test/conftest.py` (`pytest_plugins = [...]`) next to the tests; libtmux_easy and
+lte_launch_test must be importable (installed, or on `PYTHONPATH`).
+
+| build type | add |
+|---|---|
+| `ament_python` | nothing: colcon runs pytest on `test/` |
+| `ament_cmake` | `find_package(ament_cmake_pytest REQUIRED)` and `ament_add_pytest_test(test_talker test/test_talker.py TIMEOUT 120)` |
+
+## Layout
+
+| path | what |
+|---|---|
+| `src/lte_launch_test/` | the package |
+| `docs/` | design, `launch_testing` parity, packaging, [future development](docs/FUTURE_DEVELOPMENT.md) |
+| `examples/` | numbered example tests, simplest first; `failing/` fails on purpose. See [examples/](examples/README.md) |
+| `test/` | `test/run.sh`: every failure check, unit and live (launch deaths, container crash, composable load errors, bag topics/counts, probe waits, services, params, tf), and that `examples/failing` fails as documented |
+| `debian/`, `package.xml`, `setup.cfg` | the `.deb`, colcon, pip |
+| `.github/workflows/` | CI (Humble, Jazzy), release |
+
+## Notes
+
+- A failed test stops its class's processes at once (SIGINT, escalating;
+  `on_abort=` first, if given) and skips the rest of the class.
+  `--keep-open` keeps them instead.
+- Logs: each process's output and ROS logs go to pytest's tmp dir, printed
+  at the end as `process logs: <dir>`.
+- A node that should exit 0 on SIGINT must catch `KeyboardInterrupt` /
+  `ExternalShutdownException` around `rclpy.spin()` (see `examples/nodes/counter_node.py`).
+- A stopped node's name can linger in the graph briefly. Give per-test
+  nodes names of their own (`-r __node:=...`).

lte_launch_test-0.1.0/src/lte_launch_test.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+package.xml
+pyproject.toml
+setup.cfg
+setup.py
+resource/lte_launch_test
+src/lte_launch_test/__init__.py
+src/lte_launch_test/bag.py
+src/lte_launch_test/checks.py
+src/lte_launch_test/plugin.py
+src/lte_launch_test/probe.py
+src/lte_launch_test.egg-info/PKG-INFO
+src/lte_launch_test.egg-info/SOURCES.txt
+src/lte_launch_test.egg-info/dependency_links.txt
+src/lte_launch_test.egg-info/requires.txt
+src/lte_launch_test.egg-info/top_level.txt

lte_launch_test-0.1.0/src/lte_launch_test.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lte_launch_test-0.1.0/src/lte_launch_test.egg-info/requires.txt

@@ -0,0 +1,3 @@
+libtmux-easy>=0.2.0
+pytest<9,>=7.0
+pyyaml

lte_launch_test-0.1.0/src/lte_launch_test.egg-info/top_level.txt

@@ -0,0 +1 @@
+lte_launch_test