Setup testing (#37)

* Add initial README doc for tests
  - Partially generated to set up framework
* Set up initial test fixtures
* Update gh actions workflow
* Update dependencies; add test markers
* Update readme
* Update test coverage in actions
* Add os matrix for testing

Author: kaitj

.github/workflows/test.yaml

@@ -8,28 +8,68 @@ on:
     branches:
     - main
   pull_request:
+  workflow_dispatch:
+    inputs:
+      e2e:
+        description: Run end-to-end tests
+        required: false
+        default: false
+        type: boolean
 
 jobs:
   unit:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
     - uses: actions/checkout@v6
     - name: Setup venv
       uses: ./.github/actions/setup-venv
-    - name: Run tests
-      id: run-tests
+    - name: Run quick tests
+      id: run-quick-tests
       run: >
         uv run pytest \
-          --junitxml=pytest.xml \
-          --cov-report=term-missing:skip-covered \
-          --cov-report=xml:coverage.xml \
+          -m "not slow and not full_pipeline"
+          --junitxml=pytest-quick.xml \
           --cov=src tests \
           --log-level=DEBUG \
           --verbose
+
+    - name: Run slow tests (manual trigger)
+      if: github.event_name == 'workflow_dispatch'
+      run: >
+        uv run pytest \
+          -m "slow and not full_pipeline" \
+          --junitxml=pytest-slow.xml \
+          --cov=src tests \
+          --cov-append \
+          --verbose
+
+    - name: Run full pipeline tests (manual trigger)
+      if: github.event_name == 'workflow_dispatch' && inputs.e2e == true
+      run: >
+        uv run pytest \
+          -m "full_pipeline" \
+          --junitxml=pytest-full.xml \
+          --cov=src tests \
+          --cov-append \
+          --verbose
+
+    - name: Generate coverage report
+      run: >
+        uv run pytest \
+          --cov-report=term-missing:skip-covered \
+          --cov-report=xml:coverage.xml \
+          --cov=src \
+          --cov-report-only
+
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./coverage.xml
         verbose: true
 
   ruff:

pyproject.toml

@@ -27,6 +27,15 @@ docs = ["pdoc>=15.0.0"]
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]
+markers = [
+  "unit: Fast (<1s) unit tests (e.g. utilities, BIDS parsing, file operations",
+  "integration: Medium (1-5 min) integration tests with small/downsampled data",
+  "slow: Long (30+ min) tests; skip on CI",
+  "full_pipeline: End-to-end workflow tests; skip on CI"
+]
+
+[tool.coverage.report]
+omit = ["src/rbc/core/resources/"]
 
 [tool.mypy]
 ignore_missing_imports = true

tests/README.md

@@ -0,0 +1,114 @@
+# Testing Guide
+
+Quick guide for running tests in this project.
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run fast tests (recommended during development)
+pytest -m unit
+
+# Run all tests (except slow ones)
+pytest -m "not slow and not full_pipeline"
+
+# Run everything
+pytest
+```
+
+## Test Categories
+
+| Marker          | Speed        |
+| --------------- | ------------ |
+| `unit`          | <1s per test |
+| `integration`   | 1-5 min      |
+| `slow`          | >5 min       |
+| `full_pipeline` | 30+ min      |
+
+## Common Commands
+
+### Development Workflow
+
+```bash
+# Fast feedback loop (unit tests only)
+pytest -m unit
+
+# Test specific file
+pytest tests/unit/test_bids_parsing.py
+
+# Test specific function
+pytest tests/unit/test_bids_parsing.py::test_parse_subject_id
+```
+
+<details>
+<summary><h2>Useful Options</h2></summary>
+
+```bash
+# Stop on first failure
+pytest -x
+
+# Show which tests are slowest
+pytest --durations=10
+
+# Run tests matching a pattern
+pytest -k "motion_correction"
+```
+
+</details>
+
+## Test Data
+
+Test data is stored in `tests/data/`.
+
+## Coverage Requirements
+
+- **Overall:** >85%
+- **Unit tests:** >90%
+- **Integration tests:** >80%
+
+```bash
+# Check coverage
+pytest --cov=src --cov-report=term-missing
+
+# Generate HTML report
+pytest --cov=src --cov-report=html
+```
+
+## CI/CD
+
+Tests run automatically on GitHub Actions:
+
+- **On every push:** Unit tests + fast integration tests
+- **Manual trigger:** Full pipeline tests (slow)
+
+To run the same tests as CI locally:
+
+```bash
+pytest -m "not slow and not full_pipeline" \
+  --cov=src \
+  --cov-report=xml \
+  --junitxml=pytest.xml
+```
+
+## Directory Structure
+
+```
+tests/
+├── conftest.py              # Shared fixtures
+├── unit/                    # Fast tests (<1s)
+├── integration/             # Medium tests (1-5 min)
+├── full_pipeline/           # Slow tests (30+ min)
+└── data/                    # Test datasets
+```
+
+## Best Practices
+
+1. **Run unit tests frequently** - They're fast (<1s)
+2. **Run integration tests before committing** - Catch issues early
+3. **Use appropriate markers** - Auto-applied based on file location
+4. **Write descriptive test names** - `test_motion_correction_preserves_dimensions`
+5. **One assertion per test** - When practical
+6. **Use fixtures** - Don't repeat setup code
+7. **Keep tests independent** - No shared state between tests

tests/conftest.py

@@ -0,0 +1,43 @@
+"""Shared fixtures for tests data."""
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+
+@pytest.fixture
+def test_dataset_dir() -> Path:
+    """Return path to test dataset directory."""
+    return Path(__file__).parent / "data" / "ds000001"
+
+
+@pytest.fixture
+def test_subject(test_dataset_dir: Path) -> SimpleNamespace:
+    """Return namespace containing file paths to test subject data."""
+    subject_id = "01"
+    task_id = "balloonanalogrisktask"
+
+    subject_dir = test_dataset_dir / f"sub-{subject_id}"
+    anat_dir = subject_dir / "anat"
+    func_dir = subject_dir / "func"
+
+    subject_data = SimpleNamespace(
+        subject_id=subject_id,
+        subject_dir=subject_dir,
+        t1w=anat_dir / f"sub-{subject_id}_T1w.nii.gz",
+        bold=func_dir / f"sub-{subject_id}_task-{task_id}_run-01_bold.nii.gz",
+        tasks=test_dataset_dir / f"task-{task_id}_bold.json",
+        events=func_dir / f"sub-{subject_id}_task-{task_id}_run-01_events.tsv",
+    )
+
+    required_files = {
+        "T1w": subject_data.t1w,
+        "BOLD": subject_data.bold,
+        "task": subject_data.tasks,
+        "events": subject_data.events,
+    }
+    for name, fpath in required_files.items():
+        if not fpath.exists():
+            raise FileNotFoundError(f"{name} file not found: {fpath}")
+    return subject_data