Set up CI workflow, improve testing and documentation (#13)

- Add and configure CI workflow
- Update .gitignore and enhance CONTRIBUTING.md
- Add mock robot implementation with unit tests (#5)
- Add unit tests for Logger, covering send/receive and log levels
- Rename CI workflow to 'build'; remove coverage reporting
- Specify test directory in CI workflow

Author: MGross21

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: build
+
+on:
+  push:
+    branches: [ main ]
+    paths: [ "**/*.py", "pyproject.toml", ".github/workflows/**"]
+  pull_request:
+    branches: [ main ]
+    paths: [ "**/*.py", "pyproject.toml", ".github/workflows/**"]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Poetry
+        run: |
+          python -m pip install --upgrade pip
+          pip install poetry
+
+      - name: Install dependencies
+        run: |
+          poetry install --no-interaction --with dev
+
+      - name: Run tests
+        run: |
+          poetry run pytest tests --maxfail=1 --disable-warnings --tb=short  -v

.gitignore

@@ -1,10 +1,18 @@
+# Caching
 __pycache__/
-*notes*
+.*_cache/
 
+# Python Package Management
 *egg-info/
 *venv/
 
+# Internal Usage
 local/
+*notes*
+
+# IDE and Editor Configurations
+.idea/
+.vscode/
 
 # Builds
 dist/

CONTRIBUTING.md

@@ -147,3 +147,13 @@ poetry run mypy armctl
 ```
 
 > All code must be properly formatted and pass type checks. Please resolve any issues reported by these tools prior to opening a pull request.
+
+✅ **(Optional) Running Tests Locally:**
+
+While CI/CD automation will run tests on your pull request, you can speed up debugging by running the test suite locally:
+
+```bash
+poetry run pytest tests
+```
+
+This is optional, but helps catch issues before submitting your pull request.

poetry.lock

@@ -36,6 +36,7 @@ black = { version = ">=23.0" }
 ruff = { version = ">=0.4.0" }
 mypy = { version = ">=1.0.0" }
 isort = { version = ">=5.12.0" }
+pytest = { version = ">=8.4.0"}
 
 [tool.black]
 line-length = 80
@@ -57,6 +58,6 @@ force_grid_wrap = 0
 use_parentheses = true
 
 [tool.mypy]
-python_version = 3.8
+python_version = 3.9
 strict = true
 ignore_missing_imports = true

pyproject.toml

@@ -0,0 +1,35 @@
+from armctl.templates import Commands
+from armctl.templates import SocketController as Socket
+import time
+
+TEST_STRING_PREFIX = "MOCK!!"
+
+def _format_mock_command(method_name: str, arg=None):
+    if arg is not None:
+        return f"{TEST_STRING_PREFIX} {method_name.upper()}: {arg}"
+    return f"{TEST_STRING_PREFIX} {method_name.upper()}"
+
+class MockRobot(Socket, Commands):
+    def __init__(self, ip: str = "127.0.0.1", port: int = 8_000):
+        super().__init__(ip, port)
+
+    def move_joints(self, pos) -> str:
+        return self.send_command(_format_mock_command(self.move_joints.__name__, pos))
+
+    def move_cartesian(self, pose) -> str:
+        return self.send_command(_format_mock_command(self.move_cartesian.__name__, pose))
+
+    def get_joint_positions(self) -> str:
+        return self.send_command(_format_mock_command(self.get_joint_positions.__name__))
+
+    def get_cartesian_position(self) -> str:
+        return self.send_command(_format_mock_command(self.get_cartesian_position.__name__))
+
+    def stop_motion(self) -> str:
+        return self.send_command(_format_mock_command(self.stop_motion.__name__))
+
+    def get_robot_state(self) -> str:
+        return self.send_command(_format_mock_command(self.get_robot_state.__name__))
+    
+    def sleep(self, seconds):
+        return time.sleep(seconds)

tests/_mock_robot.py

@@ -0,0 +1,45 @@
+import logging
+import pytest
+from armctl import Logger
+from armctl.templates import logger as logger_module
+
+
+def test_send_level_name():
+    assert logging.getLevelName(logger_module.SEND_LEVEL) == "SEND"
+
+
+def test_receive_level_name():
+    assert logging.getLevelName(logger_module.RECEIVE_LEVEL) == "RECV"
+
+
+def test_logger_send_and_receive_methods_exist():
+    log = logging.getLogger("test_logger")
+    assert hasattr(log, "send")
+    assert hasattr(log, "receive")
+
+
+def test_logger_send_logs_message(caplog):
+    log = logging.getLogger("test_logger_send")
+    with caplog.at_level(logger_module.SEND_LEVEL):
+        log.send("This is a SEND message")
+    assert any("This is a SEND message" in m for m in caplog.messages)
+    assert any(r.levelname == "SEND" for r in caplog.records)
+
+
+def test_logger_receive_logs_message(caplog):
+    log = logging.getLogger("test_logger_receive")
+    with caplog.at_level(logger_module.RECEIVE_LEVEL):
+        log.receive("This is a RECV message")
+    assert any("This is a RECV message" in m for m in caplog.messages)
+    assert any(r.levelname == "RECV" for r in caplog.records)
+
+
+def test_logger_verbosity_and_enable_disable(caplog):
+    with caplog.at_level(logging.INFO):
+        Logger.enable()  # Make sure logging is enabled
+        logging.info("This should appear")
+        assert "This should appear" in caplog.text
+        Logger.disable()
+        logging.info("This should NOT appear")
+        assert "This should NOT appear" not in caplog.text
+        Logger.enable()  # Re-enable for other tests

tests/test_logger.py

@@ -0,0 +1,54 @@
+import pytest
+import time
+
+from tests._mock_robot import MockRobot, TEST_STRING_PREFIX
+
+
+
+@pytest.fixture
+def mock_robot():
+    class PatchedMockRobot(MockRobot):
+        def send_command(self, cmd):
+            return cmd
+
+    return PatchedMockRobot()
+
+
+def test_move_joints(mock_robot):
+    pos = [1, 2, 3]
+    expected = f"{TEST_STRING_PREFIX} MOVE_JOINTS: {pos}"
+    assert mock_robot.move_joints(pos) == expected
+
+
+def test_move_cartesian(mock_robot):
+    pose = [0.1, 0.2, 0.3]
+    expected = f"{TEST_STRING_PREFIX} MOVE_CARTESIAN: {pose}"
+    assert mock_robot.move_cartesian(pose) == expected
+
+
+def test_get_joint_positions(mock_robot):
+    expected = f"{TEST_STRING_PREFIX} GET_JOINT_POSITIONS"
+    assert mock_robot.get_joint_positions() == expected
+
+
+def test_get_cartesian_position(mock_robot):
+    expected = f"{TEST_STRING_PREFIX} GET_CARTESIAN_POSITION"
+    assert mock_robot.get_cartesian_position() == expected
+
+
+def test_stop_motion(mock_robot):
+    expected = f"{TEST_STRING_PREFIX} STOP_MOTION"
+    assert mock_robot.stop_motion() == expected
+
+
+def test_get_robot_state(mock_robot):
+    expected = f"{TEST_STRING_PREFIX} GET_ROBOT_STATE"
+    assert mock_robot.get_robot_state() == expected
+
+
+def test_sleep_duration(mock_robot):
+    sleep_seconds = 0.2
+    start = time.time()
+    mock_robot.sleep(sleep_seconds)
+    elapsed = time.time() - start
+    assert elapsed >= sleep_seconds