Skip to content

Testing

pyvoicebox is validated against the original MATLAB source. Every Python function is tested against reference output generated by running the real MATLAB code through GNU Octave.

Running the tests

pip install -e ".[dev]"
pytest tests/ -v

First run takes a few minutes — it automatically clones the original MATLAB repository and runs 11 Octave harness scripts to generate reference .mat files. Everything is cached at ~/.cache/pyvoicebox-test/ so subsequent runs are fast.

Subsequent runs skip generation and go straight to the 500+ tests.

Prerequisites

Requirement Purpose
Python 3.9+ Runtime
Git Clones the original MATLAB source on first test run
GNU Octave Executes the MATLAB source to generate reference data

How it works

┌──────────────────────┐     ┌────────���─────────────┐
│  Octave harness       │     │  Python test suite    │
│  (gen_ref_phase*.m)   │     │  (test_phase*.py)     │
│                       │     │                       │
│  Runs real MATLAB     │────▶│  Loads .mat files     │
│  v_frq2mel(440)       │     │  Compares Python      │
│  Saves output to .mat │     │  output to MATLAB     │
└──────────────────────┘     └─���────────────────────┘

  1. Octave harness scripts (tests/octave_harness/gen_ref_phase*.m) call the original MATLAB functions with representative inputs and save the outputs as .mat files.

  2. Python test files (tests/test_phase*.py) load those .mat files, call the corresponding Python function with the same inputs, and compare using np.testing.assert_allclose().

  3. Tight tolerances — most tests use rtol=1e-10 to 1e-12. Looser tolerances are used where expected: codec roundtrips (rtol=1e-5 due to quantisation), statistical functions (rtol=1e-6), and histogram-based tests (atol=0.1).

  4. No pre-built reference data is shipped in the repo. The tests/conftest.py session fixture handles cloning, generation, and caching automatically. This means the tests always validate against the real MATLAB source, not stale snapshots.

CI / GitHub Actions

Two workflows run via GitHub Actions:

  • Docs (.github/workflows/docs.yml) — builds and deploys the documentation site to GitHub Pages on every push to master that touches docs/, mkdocs.yml, or pyvoicebox/.

  • Tests (.github/workflows/tests.yml) — installs GNU Octave and runs the full test suite. Triggers on pushes and PRs that touch pyvoicebox/, tests/, or pyproject.toml. Frontend and documentation changes do not trigger a test run.