// Run the pynetbox test suite — unit tests only, integration tests against a live NetBox in Docker, or both. Covers how to pick the right command, pass options, and interpret failures.
| name | run-tests |
| description | Run the pynetbox test suite — unit tests only, integration tests against a live NetBox in Docker, or both. Covers how to pick the right command, pass options, and interpret failures. |
| version | 1 |
Run the pynetbox test suite. Choose the scope that fits your situation.
| 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/ |
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 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 outputIntegration 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-versions accepts a comma-separated list (4.3,4.4,4.5).--no-cleanup leaves the container running — useful for inspecting state after a failure.-p no:docker --url-override http://localhost:8000 skips Docker and targets an existing instance.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.
The GitHub Actions workflow (py3.yml) runs the full matrix:
Reproducing a specific cell locally:
# Example: Python 3.12 + NetBox 4.3
python3.12 -m pytest tests/ --netbox-versions 4.3
| 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 |