NetBox 本地测试套件运行指南从 manage.py test 到与 CI 完全对齐的完整实践【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox本篇技术指南以 NetBox 仓库内置的run-tests技能文档.claude/skills/run-tests/SKILL.md为核心骨架系统讲解如何在本地运行 NetBox 的 Django 测试套件从标准启动命令、运行前置条件、常用变体命令到各应用的标准测试模块划分、模型变更后的迁移处理与覆盖率统计并深入源码与 CI 配置揭示NETBOX_CONFIGURATION的加载机制与测试配置的底层实现。读完本篇你将掌握一套与官方 CI 完全一致、可复现、可调试的本地测试工作流能够在提交 Pull Request 前独立验证代码变更。测试框架与运行入口NetBox 的测试套件基于 Django 自带的django.test.TestCase不使用 pytest。整套测试通过manage.py test从仓库根目录repo root调用官方 CI 在 .github/workflows/ci.yml 中执行的正是这条命令。manage.py本身是一个极简的 Django 管理入口netbox/manage.py它先将DJANGO_SETTINGS_MODULE默认设为netbox.settings再调用django.core.management.execute_from_command_line转发命令行参数os.environ.setdefault(DJANGO_SETTINGS_MODULE, netbox.settings) from django.core.management import execute_from_command_line execute_from_command_line(sys.argv)也就是说所有manage.py test参数最终都交由 Django 的测试执行器处理。理解这一点有助于后续灵活使用各种变体命令。标准启动命令Canonical Command在仓库根目录、且虚拟环境venv已激活的前提下运行完整测试套件的标准命令是NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test netbox/ --parallel两个关键点NETBOX_CONFIGURATIONnetbox.configuration_testing显式指定测试配置模块这是运行测试的前提详见下文「配置加载机制」--parallel让测试进程跨 CPU 核并行执行官方 CI 正是以此模式运行。若某测试仅在并行模式下才失败可去掉该参数进行串行调试。注意这里使用的是python netbox/manage.py而非裸python manage.py因为manage.py位于仓库的netbox/子目录下测试目标netbox/表示对整个应用目录执行测试发现。运行前置条件在按下回车之前请逐一确认以下四项全部就绪任何一项缺失都应立即向用户暴露缺口而不是静默跳过PostgreSQL 与 Redis 可达二者需在localhost的默认端口上可连接凭据为netbox/netbox/netbox即用户名netbox、密码netbox、库名netbox。configuration.py就位从netbox/netbox/configuration_example.py复制一份并填入DATABASE、REDIS、SECRET_KEY、ALLOWED_HOSTS。该文件被 gitignore 忽略严禁提交进版本库。依赖安装完成pip install -r requirements.txt即仓库根目录的 requirements.txt。NETBOX_CONFIGURATION指向测试配置设为netbox.configuration_testing该测试配置已妥善设置DATABASES、REDIS与PLUGINS详见下一节。关于前置条件 2参考 netbox/netbox/configuration_example.py 的注释与结构DATABASES使用 PostgreSQL 引擎CONN_MAX_AGE为 300连接最大存活秒数REDIS分为tasks与caching两个独立配置节分别用于后台任务如 Webhook 事件与缓存官方强烈建议二者使用不同的数据库 ID默认 0 与 1。测试配置 configuration_testing.py 源码解析NETBOX_CONFIGURATIONnetbox.configuration_testing指向 netbox/netbox/configuration_testing.py。文件头部注释明确声明该文件仅作为测试用途的基础配置不用于生产环境。逐一拆解其配置项配置项测试值作用说明ALLOWED_HOSTS[*]允许任意 Host 头便于测试客户端访问DATABASES.default库netbox、用户netbox、密码netbox、HOSTlocalhost、CONN_MAX_AGE300与前置条件 1 的凭据一一对应PLUGINS[netbox.tests.dummy_plugin, netbox.tests.dummy_plugin_b]加载两个哑插件用于测试 NetBox 的插件框架本身RQ{COMMIT_MODE: auto}后台任务队列采用自动提交模式REDIStasks库 0、caching库 1HOSTlocalhost、PORT6379、SSLFalse与生产示例同构指向本地 RedisSECRET_KEY字母数字混合的固定测试密钥仅供测试无安全价值DEFAULT_PERMISSIONS{}无默认权限测试用例自行控制权限API_TOKEN_PEPPERS含1: TEST-VALUE-DO-NOT-USE-...API Token 加盐值标识为测试专用LOGGING仅禁用已有 logger降低测试输出噪音从源码结构看该配置刻意复刻了生产配置的核心骨架DATABASES/REDIS/SECRET_KEY但把安全敏感项替换为固定测试值并把插件指向仓库自带的哑插件——这正是测试套件可以脱离生产实例独立运行的关键。配置加载机制NETBOX_CONFIGURATION 为什么必须设置不设置NETBOX_CONFIGURATION会发生什么答案藏在 netbox/netbox/settings_utils.py 的load_configuration()中。其加载顺序为显式优先若环境变量NETBOX_CONFIGURATION存在则直接导入该模块——explicit environ.get(NETBOX_CONFIGURATION); if explicit: return _import_module(explicit)wheel 安装模式优先加载install_root/conf/configuration.py否则回退到旧路径的netbox/netbox/configuration.py带迁移警告checkout源码模式默认值回退到netbox.configuration模块即netbox/netbox/configuration.py——这是生产配置。随后 netbox/netbox/settings.py 还会做必需的配置参数校验ALLOWED_HOSTS、SECRET_KEY、REDIS缺失即抛ImproperlyConfigured且DATABASE与DATABASES不允许同时出现。结论不设置NETBOX_CONFIGURATION时Django 会加载生产配置configuration.py——它很可能指向不同的数据库甚至在开发环境中根本不存在该文件是 gitignored 的导致测试无法运行或污染生产库。因此每次运行测试都必须显式设置该环境变量。常用变体命令运行单个应用的全部测试NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim --parallel运行单个模块、类或方法Django 点分路径目标NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim.tests.test_api NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim.tests.test_api.RackTestCase NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim.tests.test_api.RackTestCase.test_list_objects三级粒度依次从「整个测试模块」收窄到「测试类」再到「单个测试方法」是日常迭代调试的核心工具。提速选项选项作用注意事项--keepdb跳过测试库重建复用之一次运行留下的数据库对大多数迭代工作安全--parallel跨 CPU 核并行运行CI 使用与--keepdb组合前务必先实测验证--failfast遇首个失败立即停止快速定位首个出错点-v 2每运行一个测试就打印其名称观察执行进度与顺序每个应用的标准测试模块各应用app的测试位于app/tests/目录模块命名与职责遵循统一约定模块覆盖范围test_api.pyREST API 端点增删改查、过滤、批量操作test_filtersets.pyFilterSet 字段与查询行为test_models.py模型方法、校验、约束test_views.pyUI 视图列表、创建、编辑、删除、批量操作test_forms.py表单校验test_tables.py表格列渲染此外部分应用还包含专项测试模块例如 dcim 的test_cablepaths.py线缆路径追踪、ipam 的test_lookups.py自定义查询 lookup。以 netbox/dcim/tests 目录为例实际还扩展出了test_cable_profiles.py、test_channelization.py、test_management_commands.py、test_search.py、test_signals.py等说明这套「标准六件套 专项模块」的约定在各应用中被一致遵守并持续丰富。模型变更之后先生成迁移再跑测试任何模型Model字段或结构变更后必须先执行迁移生成否则测试库构建阶段会因缺少迁移而直接失败python netbox/manage.py makemigrations务必遵循「迁移由 Django 自动生成绝不手写」的原则。CI 中更是用python netbox/manage.py makemigrations --check来校验是否存在未生成迁移的模型变更见 .github/workflows/ci.yml本地开发时养成同样的习惯能提前暴露「改了模型忘了建迁移」的问题。覆盖率统计与 CI 对齐运行覆盖率统计的推荐命令coverage run --sourcenetbox/ netbox/manage.py test netbox/ --parallel coverage report --skip-covered --omit */migrations/*,*/tests/*--sourcenetbox/只统计netbox/目录下的代码--skip-covered跳过 100% 覆盖的文件减少输出--omit排除迁移文件与测试文件自身避免干扰。CI 的做法可作参照.github/workflows/ci.yml在 Python 3.14 这一矩阵项上以coverage run netbox/manage.py test netbox/ --parallel采集数据随后coverage combine合并、coverage report输出报告。同时 CI 会额外安装coverage tblib其中tblib用于在并行模式下传递异常 traceback。为什么这样选择设计决策解读原文档给出了三条核心设计决策结合源码可以更深入地理解其动机不要用 pytest 替代测试套件基于django.test.TestCase改用 pytest 需要针对 NetBox 的 settings 配置pytest-django而该配置并未建立。继续使用manage.py test才能与 CI 行为完全一致。必须设置NETBOX_CONFIGURATION如「配置加载机制」一节所述settings_utils.py 中显式环境变量优先级最高不设置就会回退到生产配置netbox.configuration这在开发环境中往往指向错误的数据库或根本不存在。全量套件使用--parallelCI 就是并行运行的本地串行跑不仅多核机器上更慢还可能掩盖少数情况下才会出现的并发竞态问题。需要定位这类问题时再改用串行模式复现。与官方 CI 的完整对齐若想确认本地行为与 CI 一致可对照 .github/workflows/ci.yml 的testjob 逐项核对环境变量NETBOX_CONFIGURATION: netbox.configuration_testingci.yml服务容器redis映射 6379 端口、postgres以netbox/netbox初始化并暴露 5432 端口ci.yml——与本地前置条件一致安装requirements.txt及coverage tblibmakemigrations --check校验迁移完整性collectstatic --no-input收集静态文件SVG 渲染类测试直接读取 CSS运行python netbox/manage.py test netbox/ --parallel覆盖率仅由 Python 3.14 矩阵项承担一次。测试矩阵覆盖 Python 3.12 / 3.13 / 3.14且仅当改动涉及netbox/**/*.py、requirements*.txt、pyproject.toml时才触发体现了 CI 对「Python 变更才跑 Python 测试」的精细控制。参考资料AGENTS.md —— 仓库开发规范中的测试章节含常用命令速查与故障排查提示.github/workflows/ci.yml —— 官方 CI 的权威测试调用netbox/netbox/configuration_testing.py —— 测试执行所用的配置模块netbox/netbox/configuration_example.py —— 本地configuration.py的复制模板netbox/netbox/settings_utils.py ——NETBOX_CONFIGURATION加载优先级实现【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
NetBox 本地测试套件运行指南从 manage.py test 到与 CI 完全对齐的完整实践【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox本篇技术指南以 NetBox 仓库内置的run-tests技能文档.claude/skills/run-tests/SKILL.md为核心骨架系统讲解如何在本地运行 NetBox 的 Django 测试套件从标准启动命令、运行前置条件、常用变体命令到各应用的标准测试模块划分、模型变更后的迁移处理与覆盖率统计并深入源码与 CI 配置揭示NETBOX_CONFIGURATION的加载机制与测试配置的底层实现。读完本篇你将掌握一套与官方 CI 完全一致、可复现、可调试的本地测试工作流能够在提交 Pull Request 前独立验证代码变更。测试框架与运行入口NetBox 的测试套件基于 Django 自带的django.test.TestCase不使用 pytest。整套测试通过manage.py test从仓库根目录repo root调用官方 CI 在 .github/workflows/ci.yml 中执行的正是这条命令。manage.py本身是一个极简的 Django 管理入口netbox/manage.py它先将DJANGO_SETTINGS_MODULE默认设为netbox.settings再调用django.core.management.execute_from_command_line转发命令行参数os.environ.setdefault(DJANGO_SETTINGS_MODULE, netbox.settings) from django.core.management import execute_from_command_line execute_from_command_line(sys.argv)也就是说所有manage.py test参数最终都交由 Django 的测试执行器处理。理解这一点有助于后续灵活使用各种变体命令。标准启动命令Canonical Command在仓库根目录、且虚拟环境venv已激活的前提下运行完整测试套件的标准命令是NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test netbox/ --parallel两个关键点NETBOX_CONFIGURATIONnetbox.configuration_testing显式指定测试配置模块这是运行测试的前提详见下文「配置加载机制」--parallel让测试进程跨 CPU 核并行执行官方 CI 正是以此模式运行。若某测试仅在并行模式下才失败可去掉该参数进行串行调试。注意这里使用的是python netbox/manage.py而非裸python manage.py因为manage.py位于仓库的netbox/子目录下测试目标netbox/表示对整个应用目录执行测试发现。运行前置条件在按下回车之前请逐一确认以下四项全部就绪任何一项缺失都应立即向用户暴露缺口而不是静默跳过PostgreSQL 与 Redis 可达二者需在localhost的默认端口上可连接凭据为netbox/netbox/netbox即用户名netbox、密码netbox、库名netbox。configuration.py就位从netbox/netbox/configuration_example.py复制一份并填入DATABASE、REDIS、SECRET_KEY、ALLOWED_HOSTS。该文件被 gitignore 忽略严禁提交进版本库。依赖安装完成pip install -r requirements.txt即仓库根目录的 requirements.txt。NETBOX_CONFIGURATION指向测试配置设为netbox.configuration_testing该测试配置已妥善设置DATABASES、REDIS与PLUGINS详见下一节。关于前置条件 2参考 netbox/netbox/configuration_example.py 的注释与结构DATABASES使用 PostgreSQL 引擎CONN_MAX_AGE为 300连接最大存活秒数REDIS分为tasks与caching两个独立配置节分别用于后台任务如 Webhook 事件与缓存官方强烈建议二者使用不同的数据库 ID默认 0 与 1。测试配置 configuration_testing.py 源码解析NETBOX_CONFIGURATIONnetbox.configuration_testing指向 netbox/netbox/configuration_testing.py。文件头部注释明确声明该文件仅作为测试用途的基础配置不用于生产环境。逐一拆解其配置项配置项测试值作用说明ALLOWED_HOSTS[*]允许任意 Host 头便于测试客户端访问DATABASES.default库netbox、用户netbox、密码netbox、HOSTlocalhost、CONN_MAX_AGE300与前置条件 1 的凭据一一对应PLUGINS[netbox.tests.dummy_plugin, netbox.tests.dummy_plugin_b]加载两个哑插件用于测试 NetBox 的插件框架本身RQ{COMMIT_MODE: auto}后台任务队列采用自动提交模式REDIStasks库 0、caching库 1HOSTlocalhost、PORT6379、SSLFalse与生产示例同构指向本地 RedisSECRET_KEY字母数字混合的固定测试密钥仅供测试无安全价值DEFAULT_PERMISSIONS{}无默认权限测试用例自行控制权限API_TOKEN_PEPPERS含1: TEST-VALUE-DO-NOT-USE-...API Token 加盐值标识为测试专用LOGGING仅禁用已有 logger降低测试输出噪音从源码结构看该配置刻意复刻了生产配置的核心骨架DATABASES/REDIS/SECRET_KEY但把安全敏感项替换为固定测试值并把插件指向仓库自带的哑插件——这正是测试套件可以脱离生产实例独立运行的关键。配置加载机制NETBOX_CONFIGURATION 为什么必须设置不设置NETBOX_CONFIGURATION会发生什么答案藏在 netbox/netbox/settings_utils.py 的load_configuration()中。其加载顺序为显式优先若环境变量NETBOX_CONFIGURATION存在则直接导入该模块——explicit environ.get(NETBOX_CONFIGURATION); if explicit: return _import_module(explicit)wheel 安装模式优先加载install_root/conf/configuration.py否则回退到旧路径的netbox/netbox/configuration.py带迁移警告checkout源码模式默认值回退到netbox.configuration模块即netbox/netbox/configuration.py——这是生产配置。随后 netbox/netbox/settings.py 还会做必需的配置参数校验ALLOWED_HOSTS、SECRET_KEY、REDIS缺失即抛ImproperlyConfigured且DATABASE与DATABASES不允许同时出现。结论不设置NETBOX_CONFIGURATION时Django 会加载生产配置configuration.py——它很可能指向不同的数据库甚至在开发环境中根本不存在该文件是 gitignored 的导致测试无法运行或污染生产库。因此每次运行测试都必须显式设置该环境变量。常用变体命令运行单个应用的全部测试NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim --parallel运行单个模块、类或方法Django 点分路径目标NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim.tests.test_api NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim.tests.test_api.RackTestCase NETBOX_CONFIGURATIONnetbox.configuration_testing python netbox/manage.py test dcim.tests.test_api.RackTestCase.test_list_objects三级粒度依次从「整个测试模块」收窄到「测试类」再到「单个测试方法」是日常迭代调试的核心工具。提速选项选项作用注意事项--keepdb跳过测试库重建复用之一次运行留下的数据库对大多数迭代工作安全--parallel跨 CPU 核并行运行CI 使用与--keepdb组合前务必先实测验证--failfast遇首个失败立即停止快速定位首个出错点-v 2每运行一个测试就打印其名称观察执行进度与顺序每个应用的标准测试模块各应用app的测试位于app/tests/目录模块命名与职责遵循统一约定模块覆盖范围test_api.pyREST API 端点增删改查、过滤、批量操作test_filtersets.pyFilterSet 字段与查询行为test_models.py模型方法、校验、约束test_views.pyUI 视图列表、创建、编辑、删除、批量操作test_forms.py表单校验test_tables.py表格列渲染此外部分应用还包含专项测试模块例如 dcim 的test_cablepaths.py线缆路径追踪、ipam 的test_lookups.py自定义查询 lookup。以 netbox/dcim/tests 目录为例实际还扩展出了test_cable_profiles.py、test_channelization.py、test_management_commands.py、test_search.py、test_signals.py等说明这套「标准六件套 专项模块」的约定在各应用中被一致遵守并持续丰富。模型变更之后先生成迁移再跑测试任何模型Model字段或结构变更后必须先执行迁移生成否则测试库构建阶段会因缺少迁移而直接失败python netbox/manage.py makemigrations务必遵循「迁移由 Django 自动生成绝不手写」的原则。CI 中更是用python netbox/manage.py makemigrations --check来校验是否存在未生成迁移的模型变更见 .github/workflows/ci.yml本地开发时养成同样的习惯能提前暴露「改了模型忘了建迁移」的问题。覆盖率统计与 CI 对齐运行覆盖率统计的推荐命令coverage run --sourcenetbox/ netbox/manage.py test netbox/ --parallel coverage report --skip-covered --omit */migrations/*,*/tests/*--sourcenetbox/只统计netbox/目录下的代码--skip-covered跳过 100% 覆盖的文件减少输出--omit排除迁移文件与测试文件自身避免干扰。CI 的做法可作参照.github/workflows/ci.yml在 Python 3.14 这一矩阵项上以coverage run netbox/manage.py test netbox/ --parallel采集数据随后coverage combine合并、coverage report输出报告。同时 CI 会额外安装coverage tblib其中tblib用于在并行模式下传递异常 traceback。为什么这样选择设计决策解读原文档给出了三条核心设计决策结合源码可以更深入地理解其动机不要用 pytest 替代测试套件基于django.test.TestCase改用 pytest 需要针对 NetBox 的 settings 配置pytest-django而该配置并未建立。继续使用manage.py test才能与 CI 行为完全一致。必须设置NETBOX_CONFIGURATION如「配置加载机制」一节所述settings_utils.py 中显式环境变量优先级最高不设置就会回退到生产配置netbox.configuration这在开发环境中往往指向错误的数据库或根本不存在。全量套件使用--parallelCI 就是并行运行的本地串行跑不仅多核机器上更慢还可能掩盖少数情况下才会出现的并发竞态问题。需要定位这类问题时再改用串行模式复现。与官方 CI 的完整对齐若想确认本地行为与 CI 一致可对照 .github/workflows/ci.yml 的testjob 逐项核对环境变量NETBOX_CONFIGURATION: netbox.configuration_testingci.yml服务容器redis映射 6379 端口、postgres以netbox/netbox初始化并暴露 5432 端口ci.yml——与本地前置条件一致安装requirements.txt及coverage tblibmakemigrations --check校验迁移完整性collectstatic --no-input收集静态文件SVG 渲染类测试直接读取 CSS运行python netbox/manage.py test netbox/ --parallel覆盖率仅由 Python 3.14 矩阵项承担一次。测试矩阵覆盖 Python 3.12 / 3.13 / 3.14且仅当改动涉及netbox/**/*.py、requirements*.txt、pyproject.toml时才触发体现了 CI 对「Python 变更才跑 Python 测试」的精细控制。参考资料AGENTS.md —— 仓库开发规范中的测试章节含常用命令速查与故障排查提示.github/workflows/ci.yml —— 官方 CI 的权威测试调用netbox/netbox/configuration_testing.py —— 测试执行所用的配置模块netbox/netbox/configuration_example.py —— 本地configuration.py的复制模板netbox/netbox/settings_utils.py ——NETBOX_CONFIGURATION加载优先级实现【免费下载链接】netboxThe premier source of truth powering network automation. Open source under Apache 2. Try NetBox Cloud free: https://netboxlabs.com/products/free-netbox-cloud/项目地址: https://gitcode.com/gh_mirrors/ne/netbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
