AzerothCore 统一测试框架（Test Framework）完全指南：Bash 脚本与 C++ 单元测试的一体化实践

AzerothCore 统一测试框架Test Framework完全指南Bash 脚本与 C 单元测试的一体化实践【免费下载链接】azerothcore-wotlkComplete Open Source and Modular solution for MMO项目地址: https://gitcode.com/GitHub_Trending/az/azerothcore-wotlkAzerothCore 在其apps/test-framework/目录下提供了一套集中式的测试框架用于统一编写、运行和管理项目内所有 Bash 脚本的测试并集成了 AzerothCore 自身的 C 单元测试。本文以该框架的官方文档 apps/test-framework/README.md 为主体结合 run-bash-tests.sh、test-main.sh、run-core-tests.sh 及bats_libs、helpers等源码实现完整讲解框架结构、命令行用法、测试编写规范、模块接入方法与 CI/CD 集成方案。读完本文你将能够基于 BATS 为任意 AzerothCore 模块编写测试并通过./acore.sh test统一执行 Bash 测试与核心单元测试。框架定位与整体结构AzerothCore 的构建、安装、Docker 启动等环节由大量 Bash 脚本承担例如apps/compiler/compiler.sh、apps/startup-scripts中的服务管理脚本等。为保证这些脚本在持续演进中行为稳定项目将测试能力集中沉淀在apps/test-framework/形成一套框架、多模块复用的测试基础设施。框架目录结构如下与官方 README 一致apps/test-framework/ ├── test-main.sh # Unified test framework entry point统一测试框架入口交互式菜单 ├── run-bash-tests.sh # Bash test runner for BATS testsBATS 测试运行器 ├── run-core-tests.sh # AzerothCore unit test runnerC 单元测试运行器 ├── README.md # This documentation本文档 ├── bats_libs/ # Custom BATS libraries自定义 BATS 库 │ ├── acore-support.bash # Test setup and helpers测试环境搭建与辅助函数 │ └── acore-assert.bash # Custom assertions自定义断言 └── helpers/ # Test utilities测试工具 └── test_common.sh # Common test functions and setup公共测试函数与环境准备从源码结构看这一分层设计意图清晰test-main.sh是统一入口它加载apps/bash_shared/includes.sh与apps/bash_shared/menu_system.sh通过菜单系统在bash运行 BATS 测试、core运行核心单元测试、quit退出三个选项间路由run-bash-tests.sh是通用测试运行器脚本头部注释即AzerothCore Universal Test Runner负责参数解析、测试目录发现、并行度控制与 BATS 命令组装run-core-tests.sh负责查找并执行$BUILDPATH/src/test/unit_tests二进制bats_libs/与helpers/是测试编写层的公共资产被各模块的.bats测试文件通过load引用。快速开始三种运行路径官方文档给出了三种从不同目录发起测试的方式均可直接照用。方式一通过 acore.sh推荐acore.sh的test子命令由 apps/installer/main.sh 路由到test-main.sh# 进入统一测试框架的交互式菜单 ./acore.sh test # 直接运行全部 Bash 测试 ./acore.sh test bash --all # 运行 AzerothCore C 单元测试 ./acore.sh test core方式二从任意模块目录# 运行当前模块的测试 ../test-framework/run-bash-tests.sh --dir .方式三从 test-framework 目录# 运行所有模块的全部测试 ./run-bash-tests.sh --all # 运行指定模块测试 ./run-bash-tests.sh startup-scripts # 列出可用模块 ./run-bash-tests.sh --list # 带调试信息运行 ./run-bash-tests.sh --all --debug方式四从项目根目录# 运行所有测试 apps/test-framework/run-bash-tests.sh --all # 运行特定模块 apps/test-framework/run-bash-tests.sh startup-scripts # 带 verbose 输出 apps/test-framework/run-bash-tests.sh startup-scripts --verbose两种测试类型框架同时支持两类测试Bash Tests基于 BATSBash Automated Testing System的脚本测试覆盖 compiler、startup-scripts、docker、installer 等 Bash 模块Core TestsAzerothCore 的 C 单元测试即src/test/下编译产出的unit_tests二进制。统一测试框架交互式菜单test-main.sh是统一入口。其菜单数据以key|short|description三元组定义源码第 13-17 行menu_items( bash|b|Run Bash tests core|c|Run AzerothCore tests quit|q|Exit from this menu )bash调用bash $CURRENT_PATH/run-bash-tests.sh ${:---all}。注意默认参数为--all即直接通过菜单进入时默认运行全部模块的 Bash 测试core调用bash $CURRENT_PATH/run-core-tests.sh $执行核心单元测试quit输出Goodbye!并退出。菜单系统由apps/bash_shared/menu_system.sh提供通用实现handle_menu_command作为命令处理器被注入体现了框架菜单定义与逻辑解耦的设计。run-bash-tests.sh通用测试运行器详解run-bash-tests.sh是框架的核心执行引擎其工作流程为解析参数 → 校验 BATS → 发现测试目录 → 收集测试文件 → 组装 BATS 命令 → 并行执行。参数解析与帮助信息脚本支持长短两种形式的参数show_help()给出了完整清单参数短形式说明--help-h显示帮助信息--verbose-v开启 verbose 输出对应 BATS--verbose-run--tap-t使用 TAP 输出格式面向 CI/CD--pretty-p使用 pretty 输出格式默认--filter-f仅运行匹配 pattern 的测试--count-c仅显示测试数量统计--debug-d开启调试模式失败时显示详细输出--list-l列出可用测试模块--jobs-j设置并行任务数默认取 CPU 核心数--dir-在指定目录中运行测试--all-运行所有模块的全部测试此外位置参数中的*.bats会被识别为单个测试文件其余参数被当作模块名。并行度自动检测脚本启动时通过ACORE_TEST_CORES环境变量控制并行度源码第 11-20 行优先使用nprocmacOS 上回退到sysctl -n hw.ncpu两者都不可用时回退为单核。该变量也可通过--jobs num显式覆盖非法数值会直接报错退出。测试目录发现策略find_test_directories()按优先级处理四种情况--all用find $PROJECT_ROOT/apps -type d -name test递归查找apps/下所有名为test的目录--dir path依次尝试$PROJECT_ROOT/path/test、path/test、path三种形态均不存在时给出黄色警告指定模块名查找$PROJECT_ROOT/apps/module/test无任何参数若当前目录是test-framework默认回退到apps/startup-scripts/test若当前目录下有./test则使用之否则提示使用--all或指定模块。测试文件收集与过滤收集阶段默认抓取测试目录下所有*.bats文件若指定了--filter则用grep -l $FILTER找出内容中包含该 pattern 的测试文件——这意味着过滤匹配的是文件内容而非仅文件名。--count模式下不执行测试仅统计test声明的总数total$(grep -c ^test file 2/dev/null || echo 0)输出Total tests、Test files、Test directories三行统计信息适合快速确认测试规模。BATS 命令组装与执行最终执行命令的形态为源码第 261-281 行BATS_CMDbats --jobs $ACORE_TEST_CORES BATS_CMD --formatter tap # --tap 时 BATS_CMD --formatter pretty # --pretty 时默认 BATS_CMD --verbose-run # --verbose 时 BATS_CMD --filter $FILTER # --filter 时--debug模式下会先回显完整命令Command: $BATS_CMD便于排查命令行层面的问题。执行结果以退出码区分成功输出绿色✅ All tests passed!失败输出红色❌ Some tests failed!并透传 BATS 的退出码--debug失败时还会提示使用--verbose --filter test_name定位单个用例。编写测试结构与约定基础测试骨架每个.bats测试文件的标准结构如下与 README 一致#!/usr/bin/env bats # Load the AzerothCore test framework load ../../test-framework/bats_libs/acore-support load ../../test-framework/bats_libs/acore-assert setup() { acore_test_setup # Standard setup # 或根据被测对象选择专用 setup # startup_scripts_setup # For startup scripts # compiler_setup # For compiler tests # docker_setup # For docker tests } teardown() { acore_test_teardown } test my test description { run my_command assert_success assert_output expected output }真实模块如 apps/compiler/test/test_compiler.bats正是沿用了这一模式setup()中调用compiler_setup并导出SCRIPT_DIR与COMPILER_SCRIPT变量teardown()中统一调用acore_test_teardown清理环境。测试用例中会同时兼容超时退出码124与成功退出码0体现了对交互式脚本测试的务实处理。专用 Setup 函数acore-support.bash提供了五类 setup按被测模块选用acore_test_setup所有测试的基础 setup。内部依次执行setup_test_env准备临时目录与标准环境变量、create_acore_binaries生成 authserver、worldserver、cmake、make、mapextractor、vmap4extractor、vmap4assembler、mmaps_generator 等模拟二进制、create_acore_configs生成 authserver.conf、worldserver.conf、config.sh 模拟配置startup_scripts_setup在基础 setup 之上额外生成test-server模拟二进制与test-server.conf内含Database.Info、LoginDatabaseInfo、CharacterDatabaseInfo三项典型数据库连接配置用于服务管理脚本测试compiler_setup在基础 setup 之上模拟 gcc、g、ninja 三个编译工具并预置$TEST_DIR/build/CMakeCache.txt内容为CMAKE_BUILD_TYPE:STRINGRelWithDebInfo使编译脚本可以在无真实工具链的环境下被测试docker_setup在基础 setup 之上模拟 docker、docker-compose 命令并生成最小化的Dockerfile与docker-compose.ymlextractor_setup在基础 setup 之上创建client/{Maps,vmaps,mmaps,dbc}目录结构与.map、.dbc示例数据文件供数据提取器测试使用。自定义断言acore-assert.bash提供了一组面向 AzerothCore 场景的断言函数签名与用途如下# 断言二进制存在且可执行 assert_binary_exists $TEST_DIR/bin/authserver # 断言服务器启动成功匹配 type.*starting 模式 assert_acore_server_started $output authserver # 断言配置被加载匹配 config.*file 或 file assert_config_loaded $output authserver.conf # 断言退出码等于期望值 assert_exit_code $status 0 # 断言输出包含错误模式 assert_error_message $output error.*pattern # 断言文件/目录已创建 assert_file_created $file assert_directory_created $dir # 断言输出包含成功消息默认模式success|completed|finished|done assert_success_message $output # 断言构建成功匹配 Build completed|compilation successful|build.*success|make.*success assert_build_success $output # 断言服务器响应匹配 type.*initialized 或 type.*ready assert_server_responsive $output worldserver # 断言发生超时BATS 约定退出码 124 assert_timeout $status # 断言日志文件包含期望内容失败时回显日志前 20 行 assert_log_contains $log_file Server started这些断言在失败时都会输出期望模式 vs 实际输出的对比信息大幅降低排错成本。例如assert_timeout专门针对timeout命令包装的长时间运行进程检查退出码是否为 124assert_log_contains在日志缺失或内容不符时自动打印日志片段属于典型的面向诊断设计。测试环境变量框架通过helpers/test_common.sh中的setup_test_env()自动设置以下环境变量源码第 13-30 行变量含义值$TEST_DIR临时测试目录mktemp -d生成内含 bin/etc/logs/data/crashes/build 子目录$AC_TEST_ROOT项目根目录由框架目录向上推导$AC_TEST_APPSapps 目录$AC_TEST_ROOT/apps$BUILDPATH构建目录路径$TEST_DIR/build$SRCPATH源码目录路径$AC_TEST_ROOT$BINPATH二进制目录路径$TEST_DIR/bin$LOGS_PATH日志目录路径$TEST_DIR/logs关键细节setup_test_env会把$TEST_DIR/bin前置到PATH保存原 PATH 到$ORIGINAL_PATH这正是模拟二进制能够顶替真实命令的原理cleanup_test_env在 teardown 时递归删除临时目录并恢复 PATH。辅助函数测试中可用的辅助函数包括# 创建返回指定退出码、运行指定时长的模拟二进制 create_test_binary authserver 0 2 Server started # 创建测试配置写入 $TEST_DIR/etc/ 下 create_test_config authserver.conf Database.Info 127.0.0.1;3306;root;pass;db # 批量创建 AzerothCore 专属模拟二进制与配置 create_acore_binaries create_acore_configs # 为启动脚本创建 conf-name.sh 配置含 BINPATH/SERVERBIN/CONFIG/LOGS_PATH 等 create_test_script_config test test-server # 带超时运行命令并捕获输出 run_with_timeout 5s my_command # 轮询等待条件成立默认超时 10 秒、间隔 1 秒 wait_for_condition test -f $TEST_DIR/ready 10 1 # 失败时输出状态码、输出内容与 TEST_DIR 目录清单 debug_on_failure # 打印当前测试环境信息写到 BATS 的 fd 3 print_test_env # 判断是否处于测试模式由 BATS_TEST_FILENAME 或 TEST_DIR 触发 is_test_mode其中create_test_binary生成的脚本会依次打印启动消息、运行时长消息、额外输出再以指定退出码退出精确模拟真实守护进程的行为run_with_timeout本质是run timeout duration $的封装与assert_timeout配套使用可验证进程应在超时后被终止的场景。模块接入为新模块添加测试官方文档给出的三步接入流程在模块中创建test/目录mkdir apps/my-module/test创建以.bats结尾的测试文件touch apps/my-module/test/test_my_feature.bats按上文规范编写测试load两个库、定义setup/teardown、声明test用例。接入后可立即通过任意入口运行# 从模块目录运行 ../test-framework/run-bash-tests.sh --dir . # 从测试框架目录运行 ./run-bash-tests.sh my-module # 从项目根目录运行 apps/test-framework/run-bash-tests.sh my-module从run-bash-tests.sh的发现逻辑可知模块只需满足apps/module/test/目录内存在.bats文件这一约定即可被--all自动收录无需任何注册步骤——这正是框架零样板、低门槛接入设计的体现。当前仓库中已接入测试的模块包括 startup-scriptstest_startup_scripts.bats、compilertest_compiler.bats、docker、installertest_module_commands.bats等可作为新模块测试的参考范本。输出格式与 CI/CD 集成输出格式控制# Pretty 输出默认 ./run-bash-tests.sh --pretty # TAP 输出面向 CI/CD ./run-bash-tests.sh --tap # Verbose Debug 输出 ./run-bash-tests.sh --verbose --debugTAPTest Anything Protocol是 CI 系统广泛支持的测试协议每条测试结果以ok/not ok行输出便于流水线解析统计。CI 集成建议官方推荐的方式是将 TAP 输出重定向到文件供 CI 产物收集# 推荐使用 acore.sh 集成 ./acore.sh test bash --tap --all test-results.tap # 直接脚本用法 cd apps/test-framework ./run-bash-tests.sh --all --tap test-results.tap # 或从项目根目录 apps/test-framework/run-bash-tests.sh --all --tap test-results.tap # CI 中运行核心单元测试 ./acore.sh test core由于运行器以 BATS 的退出码作为自身退出码CI 可以直接通过命令退出状态判断构建是否通过无需额外解析。Core 测试C 单元测试运行器run-core-tests.sh是 C 单元测试的执行入口逻辑非常精简但职责明确源码共 20 行删除var/build/obj下所有*.gcda文件避免覆盖率统计出现假阳性加载apps/bash_shared/includes.sh获取$BUILDPATH等环境变量拼接测试二进制路径$BUILDPATH/src/test/unit_tests若二进制不存在输出提示并退出码 1存在则exec执行并透传命令行参数。运行方式# 通过 acore.sh 运行 ./acore.sh test core # 直接脚本用法 apps/test-framework/run-core-tests.sh前置条件运行 Core 测试有两个前提缺一不可项目必须开启单元测试构建在conf/config.sh配合 acore.sh 编译器使用中设置CBUILD_TESTINGON单元测试二进制可用位于$BUILDPATH/src/test/unit_tests。核心测试运行器会检查二进制是否存在执行测试并返回适当的退出码从而无缝融入 CI/CD 流程。C 单元测试源码位于 src/test/由 src/test/CMakeLists.txt 组织构建测试文件分布在src/test/server/、src/test/common/、src/test/mocks/等子目录。命令速查表统一测试框架命令通过 acore.sh./acore.sh test— 进入交互式测试框架菜单./acore.sh test bash [options]— 带选项运行 Bash 测试./acore.sh test core— 运行 AzerothCore C 单元测试Bash 测试命令run-bash-tests.sh基本执行./run-bash-tests.sh --all— 运行所有模块全部测试./run-bash-tests.sh module— 运行指定模块测试./run-bash-tests.sh --dir path— 在指定目录运行测试./run-bash-tests.sh --list— 列出可用模块含各模块测试文件数./run-bash-tests.sh --count— 统计测试数量输出控制./run-bash-tests.sh --verbose— 详细输出含调试信息./run-bash-tests.sh --tap— TAP 格式输出面向 CI/CD./run-bash-tests.sh --debug— 调试模式失败时展示细节./run-bash-tests.sh --pretty— Pretty 输出默认测试过滤./run-bash-tests.sh --filter pattern— 运行内容匹配 pattern 的测试./run-bash-tests.sh module --filter pattern— 在模块内过滤实用功能./run-bash-tests.sh --help— 显示帮助--jobs num/-j num— 指定并行任务数典型开发工作流# 统一测试入口 ./acore.sh test # 交互式菜单 ./acore.sh test bash --all # 全部 Bash 测试 ./acore.sh test core # 核心单元测试 # 开发中高频运行 cd apps/my-module ../test-framework/run-bash-tests.sh --dir . # 调试失败用例 ../test-framework/run-bash-tests.sh --dir . --debug --verbose # 运行特定模式 ../test-framework/run-bash-tests.sh --dir . --filter my-feature # 项目根目录快速全量/统计 ./acore.sh test bash --all # 推荐 apps/test-framework/run-bash-tests.sh --all # 直接脚本 ./acore.sh test bash --count # 推荐 apps/test-framework/run-bash-tests.sh --count # 直接脚本框架收益总结结合官方 README 的说明与源码实现该框架带来以下收益零样板No Boilerplate新测试模块只需创建test/目录与.bats文件即可被自动发现无需注册或配置环境一致Consistent Environment所有测试共用acore_test_setup/acore_test_teardown统一临时目录、PATH 与环境变量工具可复用Reusable Utilities模拟二进制、模拟配置、超时包装、条件等待等函数对所有模块开放集中管理Centralized Management测试基础设施集中在apps/test-framework/升级一处、全模块生效灵活执行Flexible Execution可按单模块、多模块或全量运行支持目录、过滤与并行CI/CD 就绪CI/CD ReadyTAP 输出格式 退出码透传直接对接流水线易于调试Easy Debugging内置--debug、--verbose、debug_on_failure、print_test_env等诊断手段。依赖与环境准备框架的运行时依赖为BATSBash Automated Testing System核心测试引擎标准 Unix 工具find、grep、timeout、mktemp、nproc/sysctl等。若本机未安装 BATSrun-bash-tests.sh会直接报错并给出安装指引。各平台安装方式# Ubuntu/Debian sudo apt update sudo apt install bats # Fedora/RHEL sudo dnf install bats # macOS brew install bats-core # Arch Linux sudo pacman -S bats注意部分发行版自带的 BATS 版本较旧test_compiler.bats中通过bats_require_minimum_version 1.5.0对旧版本做了兼容降级处理type -t检测存在性新编写测试时可参考这一写法以兼顾不同环境。扩展框架贡献新测试工具当需要为框架本身新增公共能力时官方 README 建议遵循以下分层约定公共函数加入 helpers/test_common.shBATS 专属辅助函数加入 bats_libs/acore-support.bash自定义断言加入 bats_libs/acore-assert.bash同步更新本文档README以记录新增功能。这一约定保证了环境准备、通用工具、断言语义、文档四层各自收敛避免功能散落也让新贡献者能够快速判断新函数应归属何处。【免费下载链接】azerothcore-wotlkComplete Open Source and Modular solution for MMO项目地址: https://gitcode.com/GitHub_Trending/az/azerothcore-wotlk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考