// Run NetBox's Django test suite locally. Use when the user asks to run tests, run a specific test module/class/method, or verify changes pass before opening a PR.
Step-by-step guide for removing a configuration parameter from NetBox, covering both static parameters (settings.py) and dynamic parameters (database-backed). Use when the user asks to remove, delete, or deprecate a configuration option or setting.
Step-by-step checklist for removing a field from an existing NetBox model, covering all required touch points (model, migration, serializer, forms, filterset, table, panel/template, search, GraphQL, tests, docs). Use when the user asks to remove or delete a field or attribute from an existing model.
Step-by-step guide for adding a new configuration parameter to NetBox, covering both static parameters (settings.py) and dynamic parameters (database-backed, editable via the admin UI). Use when the user asks to add a new configuration option, setting, or parameter to NetBox.
Step-by-step guide for removing an existing model from NetBox, covering all required touch points in safe deletion order (tests, docs, nav, search, GraphQL, API, views, URLs, forms, filterset, table, choices, model, migration). Use when the user asks to remove, delete, or deprecate a model or object type from NetBox.
Step-by-step checklist for adding a new field to an existing NetBox model, covering all required touch points (model, migration, validation, serializer, forms, filterset, table, panel/template, search, GraphQL, tests, docs). Use when the user asks to add a field or attribute to an existing model.
Step-by-step guide for adding a new model to NetBox, including all required components (model, filterset, serializer, views, forms, tables, GraphQL, tests, docs, navigation). Use when the user asks to add a new model or object type to NetBox.
| name | run-tests |
| description | Run NetBox's Django test suite locally. Use when the user asks to run tests, run a specific test module/class/method, or verify changes pass before opening a PR. |
NetBox uses django.test.TestCase (not pytest). The suite is invoked via manage.py test from the repo root. CI runs this exact command in .github/workflows/ci.yml.
From the repo root, with the venv active:
NETBOX_CONFIGURATION=netbox.configuration_testing python netbox/manage.py test netbox/ --parallel
--parallel runs test processes in parallel and is used in CI. Drop it to debug failures that only appear in parallel mode.
netbox/netbox/netbox).configuration.py in place — copy from the example and fill in DATABASE, REDIS, SECRET_KEY, ALLOWED_HOSTS. This file is gitignored and must never be committed.pip install -r requirements.txt.NETBOX_CONFIGURATION set to netbox.configuration_testing — the test config sets DATABASES, REDIS, and PLUGINS appropriately.If any of these are missing, surface the gap to the user — do not silently skip.
Run a single app's tests:
NETBOX_CONFIGURATION=netbox.configuration_testing python netbox/manage.py test dcim --parallel
Run a single module, class, or method (Django dotted-path target):
NETBOX_CONFIGURATION=netbox.configuration_testing python netbox/manage.py test dcim.tests.test_api
NETBOX_CONFIGURATION=netbox.configuration_testing python netbox/manage.py test dcim.tests.test_api.RackTestCase
NETBOX_CONFIGURATION=netbox.configuration_testing python netbox/manage.py test dcim.tests.test_api.RackTestCase.test_list_objects
Speed options:
--keepdb — skip DB rebuild between runs (safe for most iterative work)--parallel — run tests in parallel across CPU cores (used in CI; don't combine with --keepdb without testing first)--failfast — stop on first failure-v 2 — print each test name as it runs| Module | Coverage area |
|---|---|
test_api.py | REST API endpoints (CRUD, filtering, bulk operations) |
test_filtersets.py | FilterSet fields and query behavior |
test_models.py | Model methods, validation, constraints |
test_views.py | UI views (list, create, edit, delete, bulk actions) |
test_forms.py | Form validation |
test_tables.py | Table column rendering |
Specialized modules in some apps: test_cablepaths.py (dcim), test_lookups.py (ipam).
Always generate migrations before running tests; the test DB build will fail if migrations are missing:
python netbox/manage.py makemigrations
Never write migrations manually — let Django generate them.
coverage run --source="netbox/" netbox/manage.py test netbox/ --parallel
coverage report --skip-covered --omit '*/migrations/*,*/tests/*'
django.test.TestCase; switching to pytest requires pytest-django configured against NetBox's settings, which is not set up. Run via manage.py test to match CI.NETBOX_CONFIGURATION. Without it, Django loads configuration.py (the production config), which likely has a different database or may not exist in dev environments.--parallel for full-suite runs. CI runs parallel; running without it locally can mask race conditions (rare) and is slower on multi-core machines.AGENTS.md — Testing and development sections..github/workflows/ci.yml — Authoritative CI invocation.netbox/netbox/configuration_testing.py — Test configuration used by the runner.