tomevault-io run-tests
Run the pynetbox test suite. Choose the scope that fits your situation.
Quick reference
| Goal | Command |
|---|---|
| Unit tests only (no Docker) | pytest tests/unit |
| Older-style unit tests only | pytest tests/test_*.py |
| All unit tests | pytest tests/unit tests/test_*.py |
| Integration tests — default NetBox version (4.4) | pytest tests/integration --netbox-versions 4.4 |
| Integration tests — specific version | pytest tests/integration --netbox-versions 4.5 |
| Integration tests — multiple versions | pytest --netbox-versions 4.3,4.4,4.5 |
| Against an existing NetBox instance | pytest tests/integration -p no:docker --url-override http://localhost:8000 |
| Leave Docker containers running after tests | pytest tests/integration --netbox-versions 4.5 --no-cleanup |
| Lint only | ruff check pynetbox/ tests/ |
| Lint + auto-fix | ruff check --fix pynetbox/ tests/ |
Before running
Activate the virtualenv and confirm dependencies are installed:
source venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt -e .
Integration tests require Docker. Confirm the daemon is running (docker ps) before invoking them.
Unit tests
Unit tests mock all HTTP responses using JSON fixtures in tests/fixtures/. No network access or Docker is needed.
pytest tests/unit tests/test_*.py
Useful flags:
-x— stop on first failure-k <pattern>— run only tests whose name matches the pattern-v— verbose output
Integration tests
Integration tests spin up a netbox-docker container, wait for NetBox to be ready, run end-to-end CRUD operations, and tear down the container on exit.
pytest tests/integration --netbox-versions 4.5
--netbox-versionsaccepts a comma-separated list (4.3,4.4,4.5).- Default version when the flag is omitted: 4.4.
--no-cleanupleaves the container running — useful for inspecting state after a failure.-p no:docker --url-override http://localhost:8000skips Docker and targets an existing instance.
Lint
ruff is the project linter. CI enforces ruff check pynetbox/ tests/ on every push.
ruff check pynetbox/ tests/ # check only
ruff check --fix pynetbox/ tests/ # auto-fix safe issues
Always run the linter before committing; CI will reject lint failures.
CI matrix
The GitHub Actions workflow (py3.yml) runs the full matrix:
- Python versions: 3.12, 3.13, 3.14
- NetBox versions: 4.3, 4.4, 4.5
Reproducing a specific cell locally:
# Example: Python 3.12 + NetBox 4.3
python3.12 -m pytest tests/ --netbox-versions 4.3
Common failure modes
| Symptom | Likely cause | Fix |
|---|---|---|
| Integration tests hang waiting for Docker | Docker not running or image pull stalled | docker ps; check daemon logs |
connection refused on integration tests |
NetBox health check timed out before ready | Re-run; use --no-cleanup and inspect container logs |
ParameterValidationError in unit tests |
Filter param name wrong or fixture out of date | Check the fixture JSON and the parameter name |
Stale .pyc / import errors |
Bytecode cache out of sync after refactor | find . -name '*.pyc' -delete or recreate the venv |
| Lint failure on CI but not locally | Different ruff version |
Pin matches requirements-dev.txt; run pip install -r requirements-dev.txt |
Source: netbox-community/pynetbox — distributed by TomeVault.