NetBox Scripts Demo - Using Django Tests for NetBox Custom Script Lifecycle Management

Having issues with your NetBox upgrades and Custom Scripts? Need to support scripts across multiple NetBox versions? Need to verify a script’s patch won’t break production? In this advanced demonstration repository, we are showing off the use of Django Tests to identify upgrade issues and version incompatibilities. This allows our team to maintain one common script across multiple instances and keep our production instance stable.

Important Notice

This code is provided as-is for demonstration purposes only, with no support or warranty.

Most business logic has intentionally been removed from the scripts. The repository focuses on:

• Testing methodologies for NetBox scripts
• Script structure and organization
• Django TestCase patterns for script validation

This is not production-ready code and should be used as a reference only.

Overview

The current demo includes four script modules in netbox_scripts/:

1. build_cvs.py

   • Provides campus "push button" building data setup helpers.
   • Creates base test objects (sites, roles, models, interfaces, custom fields).
   • Includes pre-test flow used to generate onboarding artifacts.

2. build_devices.py

   • Implements a campus switch onboarding demo script (CampusNewSwitchScript).
   • Reads onboarding CSV input and validates required headers.
   • Demonstrates ordered processing by role (BSP, CSP, LEAF/CLF).

3. mac_address_change.py

   • Demonstrates a simple NetBox script for MAC update workflows.
   • Includes compatibility handling for NetBox model differences.
   • Includes unit tests for commit behavior.

4. zzCloudTest.py

   • Contains VLAN test utility scripts and performance comparisons.
   • Demonstrates loop vs bulk VLAN assignment on interfaces.
   • Includes setup and cleanup scripts for reusable test fixtures.

Project Structure

network-netbox-demo/
|- Makefile
|- pyproject.toml
|- README.md
|- develop/
|  |- configuration.py
|  |- dev.env
|  |- docker-compose.yml
|  |- docker-entrypoint.sh
|  |- Dockerfile-netbox-demo
|  |- local_settings.py
|  |- requirements.plugins.txt
|  `- run_tests.sh
|- netbox_scripts/
|  |- build_cvs.py
|  |- build_devices.py
|  |- mac_address_change.py
|  `- zzCloudTest.py
`- store_artifacts/
   |- CampusBuilding/
   `- html/

Testing Approach

Tests are embedded with script modules and use Django's test framework with tags.

Tag-Based Test Phases

develop/run_tests.sh runs tests in three phases:

• pre_rkt_test: pre-test setup/fixtures
• rkt_test: primary script tests
• rkt_test_extra: additional/performance-oriented tests

How Tests Are Loaded

run_tests.sh copies any script file containing from django.test import TestCase into NetBox's test path as test_rc_*.py.

Coverage Output

Coverage reports are written to:

• Terminal summary via coverage report
• HTML report under /tmp/store_artifacts/html/ (mounted to store_artifacts/html/ in this repo)

Environment Variables

Common environment variables used by scripts/tests:

• DEBUG: enables script debug defaults in some modules
• ROCKET_IN_CICD_TEST_ENVIRONMENT: signals test/CI mode
• ROCKET_ARTIFACTS_PATH: output path for generated artifacts

Usage

Prerequisites:

• Docker and Docker Compose
• Linux or WSL environment when running locally on Windows

Typical workflow:

# Build containers (default NETBOX_VER is set in Makefile)
make cbuild

# Run tagged tests and generate coverage artifacts
make test

# Start NetBox stack for GUI UAT and debugging
make debug

# Open shell in NetBox container
make bash

# Stop containers
make down

# Remove containers, database and named volumes
make destroy

Key Patterns Demonstrated

• CSV parsing and header validation for script input
• Device, interface, and VLAN test object creation
• Compatibility branching for NetBox version model changes
• Structured logging replacement for test execution visibility
• Performance comparisons for iterative vs bulk ORM operations

Requirements

• NetBox 4.x (Makefile default: v4.3.7)
• Python 3.11 (container base image)
• Django test framework (via NetBox)
• Additional plugin/dependency examples in develop/requirements.plugins.txt

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.

No support is provided for this demonstration code.

NetBox Resources

• NetBox Documentation
• NetBox GitHub Repository