Background Testing Guide

This document provides rules, structure, and patterns for writing pytest tests for Backgrounds in OM Cortex Runtime. Use this guide when adding or reviewing Background tests so that tests are consistent, mock the Provider used inside the Background, and run without hardware.

Implementation rule (test assumption)

REQUIRED: Every Background must initialize and start its Provider(s) in __init__, not in run(). That is:

• In __init__: construct the Provider with config-derived arguments, then call provider.start() (or the provider’s start API, e.g. start_stream()).
• Do not defer start() to run().

When writing tests, assert that provider.start() (or equivalent) is called once during Background construction (e.g. mock_provider_instance.start.assert_called_once() after Background(config=config)). Backgrounds that start the provider in run() are non-compliant and should be refactored.

Quick Checklist

Before submitting Background tests, verify:

• Test file: tests/backgrounds/test_{name}_bg.py
• Fixtures for config (e.g. config, config_default or config_with_*)
• Patch the Provider used inside the Background (e.g. @patch("backgrounds.plugins.xxx_bg.XxxProvider"))
• Tests: config init, Background init (Provider called with correct args, start() called in __init__), name, config access, run(), init failure
• No real hardware or Provider implementation required to run

1. File location and naming

• Path: tests/backgrounds/test_{name}_bg.py
• Naming: test_*.py; test functions named test_*.

Examples:

• tests/backgrounds/test_pointcloud_bg.py → PointCloudBg
• tests/backgrounds/test_unitree_go2_bg.py → UnitreeGo2Bg

2. Fixtures

Config fixtures matching the Background's Config class. No reset_singleton is needed for the Background class itself; the Provider is mocked so the real singleton is not used.

python
1@pytest.fixture
2def config():
3    """Default config."""
4    return UnitreeGo2BgConfig()
5
6
7@pytest.fixture
8def config_with_ethernet():
9    """Config with ethernet channel and custom timeout."""
10    return UnitreeGo2BgConfig(unitree_ethernet="eth0", timeout=10.0)

3. Mocking the Provider

REQUIRED: Patch the Provider that the Background instantiates. Patch path must be the module where the Provider is used (the Background module), not the Provider module.

python
1@patch("backgrounds.plugins.unitree_go2_bg.UnitreeGo2Provider")
2def test_background_initialization(mock_provider_class, config):
3    mock_provider_instance = MagicMock()
4    mock_provider_class.return_value = mock_provider_instance
5
6    background = UnitreeGo2Bg(config=config)
7
8    mock_provider_class.assert_called_once_with(channel="", timeout=1.0)
9    assert background.unitree_go2_provider is mock_provider_instance
10    mock_provider_instance.start.assert_called_once()

This avoids starting the real Provider (and any HW/SDK).

4. What to test

5. Test structure

Prefer one test per behavior; use @patch on the test function or use with patch(...): inside the test.

python
1def test_config_initialization():
2    cfg = UnitreeGo2BgConfig()
3    assert cfg.unitree_ethernet is None
4    assert cfg.timeout == 1.0
5
6
7@patch("backgrounds.plugins.unitree_go2_bg.UnitreeGo2Provider")
8def test_background_initialization(mock_provider_class, config):
9    mock_provider_class.return_value = MagicMock()
10    background = UnitreeGo2Bg(config=config)
11    mock_provider_class.assert_called_once_with(channel="", timeout=1.0)
12    mock_provider_class.return_value.start.assert_called_once()
13
14
15@patch("backgrounds.plugins.unitree_go2_bg.UnitreeGo2Provider")
16@patch("backgrounds.plugins.unitree_go2_bg.time.sleep")
17def test_run_sleeps(mock_sleep, mock_provider_class, config):
18    mock_provider_class.return_value = MagicMock()
19    background = UnitreeGo2Bg(config=config)
20    background.run()
21    mock_sleep.assert_called_once_with(60)

5.1 @patch parameter order

When stacking multiple @patch decorators, the bottom (closest to the function) decorator is applied first, and its mock is the first parameter:

python
1@patch("backgrounds.plugins.unitree_go2_bg.UnitreeGo2Provider")  # second param
2@patch("backgrounds.plugins.unitree_go2_bg.time.sleep")         # first param
3def test_run_sleeps(mock_sleep, mock_provider_class, config):
4    ...

6. Common patterns (pytest / mock)

6.1 MagicMock return_value

• mock_provider_class.return_value = MagicMock(): When the Background does Provider(...), it gets this instance instead of a real Provider.

6.2 Asserting calls

• mock_provider_class.assert_called_once_with(channel="", timeout=1.0): Provider was constructed once with these arguments.
• mock_provider_instance.start.assert_called_once(): start() was called once on the instance.

6.3 Init failure

python
1@patch("backgrounds.plugins.unitree_go2_bg.UnitreeGo2Provider")
2def test_init_raises_on_provider_failure(mock_provider_class, config):
3    mock_provider_class.side_effect = RuntimeError("DDS init failed")
4
5    with pytest.raises(RuntimeError, match="DDS init failed"):
6        UnitreeGo2Bg(config=config)

7. Running Background tests

bash
1uv run pytest tests/backgrounds/test_unitree_go2_bg.py -v

8. Review checklist

• File under tests/backgrounds/test_*_bg.py
• Config fixture(s); Provider patched in Background module
• Config initialization and Background initialization (Provider args + start()) tested
• Name, config access, run() (e.g. sleep) and init failure tested
• Tests pass with uv run pytest tests/backgrounds/test_*_bg.py -v (no HW)

9. Reference examples

• tests/backgrounds/test_unitree_go2_bg.py
• tests/backgrounds/test_pointcloud_bg.py

Implementation guide: .cursor/skills/background-implementation/SKILL.md