MongoDB Resmoke 测试套件Test Suites配置指南从 YAML 字段到源码级解析【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo导读在 MongoDB 服务器仓库中Resmoke是官方测试执行框架而Test Suites测试套件则是它的调度中枢——以 YAML 配置文件的形式定义运行哪些测试、如何运行。本文以 buildscripts/resmokeconfig/suites/README.md 为骨架完整讲解套件配置文件的全部字段test_kind、selector、executor、hooks、fixture、archive并结合真实套件配置与 selector.py 等源码实现帮助你从零编写、理解并调试一个可运行的 Resmoke 套件。一、什么是 Test SuiteTest suites 是配置测试组group运行哪些测试以及如何运行的 YAML 配置文件。这些文件存放在仓库的 buildscripts/resmokeconfig/suites 目录下当前仓库共包含 344 个.yml套件文件。一个 YAML 套件文件需要回答三件事测试类型这些测试是什么种类test_kind测试范围套件包含哪些测试文件selector的roots、include/exclude规则运行方式如何执行这些测试executor下的 shell 选项、hooks、fixture、失败归档策略。YAML 文件列举了套件所包含的测试文件以及要使用的测试 fixture 及其配置、shell 选项、hooks 等等。套件名就是文件名本身——例如my_suite.yml的套件名即为my_suite。二、最小示例理解套件的最小骨架原文档给出的最小示例my_suite.ymltest_kind: js_test selector: roots: - jstests/mytests/**/*.js executor: config: shell_options: nodb: 这个最小配置传递了三条信息套件名由文件名确定即my_suite测试范围包含jstests/mytests目录下的所有 JS 测试文件**/*.js递归匹配任意层级运行方式测试通过一个传入了nodb: 选项的 mongo shell 运行。这里出现了一个关键约定flag 类参数必须写成空字符串值例如nodb: Resmoke 会据此把参数以纯标志flag形式传给 shell而不是keyvalue形式。这一约定在文档的executor.config.shell_options一节中有明确说明并在后文详述。三、带占位符的完整结构示例下面是原文档给出的、展示套件整体结构的完整示例test_kind: js_test selector: roots: - jstests/mytests/**/*.js executor: config: shell_options: nodb: global_vars: TestData: defaultReadConcernLevel: null hooks: - class: ValidateCollections - class: CleanEveryN n: 20 fixture: class: ShardedClusterFixture num_shards: 2 archive: tests: true hooks: - ValidateCollections它展示了套件的四大组成部分test_kind测试类型、selector测试筛选、executor执行方式内含config/hooks/fixture/archive四个子块。后文逐一拆解每个字段。四、test_kind声明测试类型test_kind表示该套件运行的测试种类test_kind: js_test它决定了 Resmoke 如何解释selector中的测试文件、以及executor.config的配置结构。不同test_kind对应不同的 TestCase 实现类全部继承自 Python 的unittest.TestCase。完整的支持清单见 buildscripts/resmokelib/testing/testcases/README.md常用类型包括test_kind对应 TestCase说明js_testJSTestCaseJS 集成测试约 75% 的套件使用此类型见 jstests/README.mdcpp_unit_testCPPUnitTestCaseC 单元测试cpp_integration_testCPPIntegrationTestCaseC 集成测试cpp_libfuzzer_testCPPLibfuzzerTestCaseC libfuzzer 模糊测试db_testDBTestCasedbtestpy_testPyTestCasePython 测试fsm_workload_test/parallel_fsm_workload_testFSMWorkloadTestCaseFSM 并发工作负载测试benchmark_testBenchmarkTestCaseBenchmark 测试all_versions_js_testAllVersionsJSTestCase多版本透传multiversion passthrough套件使用的js_test别名会在副本集与分片集群的所有版本组合下运行其独特命名会被任务生成逻辑识别tla_plus_testTLAPlusTestCaseTLA 规格的模型检查json_schema_test、sdam_json_test、server_selection_json_test对应的 JSON 驱动测试规范驱动的 JSON 测试sleep_test、mongos_test、pretty_printer_test等专用 TestCase特殊用途测试注意与 fixture 生命周期相关的FixtureTestCase系列FixtureSetupTestCase、FixtureTeardownTestCase、FixtureAbortTestCase会被 Resmoke 内部用于协调 fixture 的启动/关闭因此一次运行中你会看到额外的测试——fixture 启动 1 个 你的 N 个测试 fixture 关闭 1 个共显示 N2 个通过。其中FixtureAbortTestCase会在测试失败且配置了归档时被动态生成向每个 mongod 进程发送SIGABRT详见 buildscripts/resmokelib/testing/testcases/README.md。五、selector精确控制测试的收录与排除selector决定套件收录/排除哪些测试文件。其内部规则在 buildscripts/resmokelib/selector.py 中实现TestFileExplorer负责文件系统操作通过globstar做 glob 展开。原文档示例selector: roots: - jstests/aggregation/**/*.js exclude_files: - jstests/aggregation/extras/*.js - jstests/aggregation/data/*.js exclude_with_any_tags: - requires_pipeline_optimizationselector.roots必填一个或多个测试文件路径决定套件候选范围。支持 glob 通配**表示任意层级目录。如果提供一个不带 glob 的路径则该路径必须真实存在否则 Resmoke 会报错——对应 selector.py 中的_DO_NOT_MATCH_ANY_EXISTING_TEST_FILES_MESSAGE错误信息Pattern(s) and/or filename(s) in ... do not match any existing test files。selector.root一个包含 glob 模式的文件每行一个模式通常由cpp_unit_test类套件使用通常是build/unittests.txt。它指定要考虑纳入套件的测试。如果未指定其他选项这些测试就是要运行的测试。这里同样支持 glob 模式且很常见。selector.include_files字符串列表glob 模式。只把这一子集包含进套件。这些文件即使会被 tag 规则排除也会被强制包含。如果在此指定的测试未出现在roots中会报错对应_DO_NOT_MATCH_ANY_TEST_FILES_FROM_ROOTS_MESSAGE...do not match any test files fromroots。selector.exclude_files字符串列表glob 模式。把这一列表的测试从套件中排除。这些文件即使会被 tag 规则包含也会被强制排除。同样如果指定的测试未包含在roots中会报错。selector.include_with_any_tags字符串列表。只有 tag 列表中包含这些 tag 中任意一个的 jstest 才会被收录除非被文件名规则排除。要查看所有套件中引用到的 tags可运行./buildscripts/resmoke.py list-tags该命令在 buildscripts/resmokelib/run/init.py 中实现它会遍历所有套件文件、解析其中的 tag 注释块并输出 tag 名及其文档说明矩阵matrix套件因归属不明确会被忽略。selector.exclude_with_any_tags字符串列表。任何定义了包含这些 tag 中任意一个的 jstest 都会被排除除非被文件名规则包含。真实示例见 buildscripts/resmokeconfig/suites/sharding.ymlselector: roots: - jstests/sharding/**/*.js - src/mongo/db/modules/enterprise/jstests/sharding/range_deleter_script_with_shard_keys.js exclude_files: - jstests/sharding/**/libs/**/*.js exclude_with_any_tags: # The default suite runs change streams as v2; v1-pinned tests use scaffolding (e.g. # shardedAggregateHangBeforeEstablishingShardCursors) that v2 doesnt trigger. - assumes_change_streams_v1筛选规则的优先级从上述字段语义可以总结出筛选逻辑由 selector.py 的过滤管线实现roots/root确定候选集合include_with_any_tags/exclude_with_any_tags按tag过滤include_files/exclude_files按文件名glob强制兜底且优先级高于 tag 规则will be excluded even if they would otherwise be included by tags / 反之亦然若 include/exclude 中的文件不在 roots 候选集合内直接报错。六、executor定义测试的执行方式executor定义测试如何被执行。它包含四个子块config、hooks、fixture、archive。executor.config该节包含每个测试的附加配置。其结构会因test_kind不同而有显著差异——具体结构需查看对应test_kind在buildscripts/resmokelib/testing/testcases目录中的实现testcases/README.md 列出了全部类型。最常见的js_test使用shell_options定制运行测试时的 mongo shell。原文档示例config: shell_options: global_vars: TestData: defaultReadConcernLevel: null nodb: gssapiServiceName: mockservice eval: - var testingReplication true; load(jstests/libs/override_methods/set_read_and_write_concerns.js); load(jstests/libs/override_methods/enable_causal_consistency_without_read_pref.js);executor.config.shell_options除global_vars之外的任何参数都会被直接传递给 mongo shell 可执行文件。它支持两类传参方式flags标志值必须是空字符串如上面nodb: Resmoke 会将其作为纯 flag 传给 shell命名参数named arguments如gssapiServiceName: mockservice会以--gssapiServiceNamemockservice形式传递。executor.config.shell_options.global_varsglobal_vars会被作为传给--eval的字符串的基础。shell_options.eval中指定的任何内容会追加在其后。Resmoke 会把对象格式化确保它们能作为字符串被正确求值evaluate。global_vars用于设置全局变量。其中TestData对象是一个特殊的全局变量用于承载测试数据。TestData的各个部分可通过以下途径更新resmoke 命令行调用.yml套件文件如上所示**运行期间runtime**由测试代码本身修改。全局TestData对象会被**智能合并merged intelligently**并提供给正在运行的js_test。键冲突key collision时行为可能因场景而异但总体优先级顺序是(1) resmoke 命令行 (2) [suite].yml (3) 运行时/默认值eval也可以用来运行 shell 中的通用 JavaScript 代码你可以直接内联 JS 代码也可以把代码放到单独的脚本中并用load()加载——原文档示例中的load(jstests/libs/override_methods/...js)正是 MongoDB 测试中大量使用的override methods通过加载 JS 覆盖方法改变测试行为如设置读写关注点、启用因果一致性。executor.hooksHooks 是在每个测试的内容边界before/after/between tests运行特定逻辑的机制。完整的 hooks 清单见 buildscripts/resmokelib/testing/hooks/README.md。关键约定.yml中的 hook 名必须与其 Python 类名一致参数可以写在.yml中会传给 hook 的构造函数但hook_logger和fixture参数会被自动注入不应写在.yml中所有 hook 继承自 buildscripts/resmokelib/testing/hooks/interface.py 的Hook基类可覆写以下空方法之一或多个before_suite、before_test、after_test、after_suite。至少必须覆写一个否则 hook 什么也不做。原文档示例hooks: - class: CheckReplOplogs - class: CheckReplDBHash - class: ValidateCollections - class: CleanEveryN n: 20 - class: MyHook param1: something param2: somethingelse常用 hooks 速览详见 hooks/README.mdhook 类名作用ValidateCollections对集合运行完整校验full validationCheckReplOplogs检查local.oplog.rs在主节点与从节点上一致CheckReplDBHash检查各副本集成员的 dbhash 一致CleanEveryN运行 N 个测试后重启 fixturen: 20CleanupConcurrencyWorkloads删除所有数据库可按exclude_dbs排除并发测试专用ContinuousStepdown定期对副本集发送replSetStepDown命令制造主节点降级PeriodicKillSecondaries周期性杀掉副本集的从节点RunQueryStats每个测试后运行$queryStats并在每个测试前清空 query stats storeWaitForReplication等待复制完成SimulateCrash模拟崩溃BackgroundInitialSync/IntermediateInitialSync后台/中间初始同步需要ReplicaSetFixture以start_initial_sync_nodeTrue启动FuzzRuntimeParameters定期连接节点发送setParameter使用 Config Fuzzer 随机化参数真实示例buildscripts/resmokeconfig/suites/aggregation.yml 中不仅使用了 hooks还给出了一个重要的顺序约束注释Be sure to run the hooks which depend on the fixture being alive before the CleanEveryN hook. That way the fixture restart cant cause any trouble for the other hooks.务必让依赖 fixture 存活的 hooks 排在CleanEveryN之前这样 fixture 重启才不会干扰其他 hooks。executor.fixture指定在测试周围运行的测试 fixture即测试拓扑。class子字段对应 fixture 的 Python 类名其余所有子字段都会传给 fixture 的构造函数具体子字段因 fixture 而异。完整的 fixtures 清单见 buildscripts/resmokelib/testing/fixtures/README.mdfixture 类名拓扑MongoDFixture单机 mongodstandaloneReplicaSetFixture副本集ShardedClusterFixture分片集群MultiReplicaSetFixture/MultiShardedClusterFixture多副本集 / 多分片集群ExternalFixture连接外部非 resmoke 管理的集群MongoTFixture在 mongod 旁运行一个 mongotBulkWriteFixture为 JSTests 提供一组集群YesFixture派生多个yes可执行文件生成大量日志原文档示例fixture: class: ShardedClusterFixture num_shards: 2 mongos_options: bind_ip_all: set_parameters: enableTestCommands: 1 mongod_options: bind_ip_all: set_parameters: enableTestCommands: 1 periodicNoopIntervalSecs: 1 writePeriodicNoops: true这里num_shards: 2创建 2 个分片mongos_options/mongod_options分别配置 mongos 与 mongod 的启动参数其中set_parameters用于设置服务器参数enableTestCommands: 1启用测试专用命令——几乎所有测试套件都会开启它periodicNoopIntervalSecs与writePeriodicNoops则用于控制 noop 写入以推进 oplog 时间戳。真实单机示例见 aggregation.ymlfixture: class: MongoDFixture mongod_options: set_parameters: enableTestCommands: 1 internalQueryStatsSampleRate: 1.0 internalQueryStatsWriteCmdSampleRate: 1 internalQueryStatsErrorsAreCommandFatal: trueexecutor.archive失败时数据文件可以上传到 S3。失败的定义是hook 或 test 抛出了异常。归档会在以下两种情况下发生本节的hooks列表中任一 hook 抛出异常若tests: true则套件中任一 test 抛出异常。archive: hooks: - Hook1 - Hook2 tests: trueexecutor.archive.hooks指定要归档的 hook 类名列表设为true表示归档所有hooks。executor.archive.tests指定要归档的测试文件列表支持通配符wildcard选择设为true表示归档所有tests。真实示例见 buildscripts/resmokeconfig/suites/sharding.yml它对 resharding 相关测试做了定向归档executor: archive: tests: - jstests/sharding/*reshard*.js补充归档机制与上文提到的FixtureAbortTestCase联动——当 Resmoke 检测到测试失败且配置了归档时会动态生成一个FixtureAbortTestCase立即执行向每个 mongod 进程发送SIGABRT然后再归档数据文件。七、真实套件aggregation.yml 完整剖析我们以 buildscripts/resmokeconfig/suites/aggregation.yml全文件仅 33 行作为最小可读的真实范例把前面所有字段串起来test_kind: js_test description: | This suite runs the tests in the aggregation sub-directory against a standalone mongod fixture. selector: roots: - jstests/aggregation/**/*.js exclude_files: - jstests/aggregation/extras/*.js - jstests/aggregation/data/*.js executor: archive: hooks: - ValidateCollections config: shell_options: eval: await import(jstests/libs/override_methods/detect_spawning_own_mongod.js); hooks: # Be sure to run the hooks which depend on the fixture being alive before the CleanEveryN hook. # That way the fixture restart cant cause any trouble for the other hooks. - class: RunQueryStats - class: ValidateCollections - class: CleanEveryN n: 20 fixture: class: MongoDFixture mongod_options: set_parameters: enableTestCommands: 1 internalQueryStatsSampleRate: 1.0 internalQueryStatsWriteCmdSampleRate: 1 internalQueryStatsErrorsAreCommandFatal: true解读description虽然不是必填字段但多数套件会提供人类可读的描述原文档未展开此处补充——它同样出现在大量真实套件中selector收录jstests/aggregation/**/*.js排除 extras 与 data 两个辅助目录hooks每个测试后运行RunQueryStats收集查询统计与ValidateCollections校验集合完整性每 20 个测试用CleanEveryN重启 fixture注意RunQueryStats与ValidateCollections必须排在CleanEveryN之前archiveValidateCollectionshook 失败时归档数据文件fixture单机MongoDFixture开启测试命令并配置查询统计相关服务器参数。八、从配置到执行源码级关键路径理解套件如何被消费有助于排查配置问题套件发现与解析buildscripts/resmokelib/suitesconfig.py 与 buildscripts/resmokelib/config.py 负责加载buildscripts/resmokeconfig/suites下的 YAML 文件并构建套件对象测试筛选buildscripts/resmokelib/selector.py 实现roots展开基于globstar、include/exclude 校验不匹配即报错、tag 过滤测试执行buildscripts/resmokelib/testing/suite.py 驱动套件运行启动 fixture → 依次执行每个 test围绕其运行 hooks 的before_test/after_test→ 结束后 teardown fixturetest_kind 分派test_kind映射到 buildscripts/resmokelib/testing/testcases 中的具体 TestCase 实现如js_test→JSTestCaseexecutor.config的结构由该实现决定hooks 与 fixture 注册hooks/fixture中的class字段按 Python 类名查找对应实现hooks 见 buildscripts/resmokelib/testing/hooksfixtures 见 buildscripts/resmokelib/testing/fixtures。九、调试与辅助命令查看套件引用的所有 tags 及其文档./buildscripts/resmoke.py list-tags该命令会遍历所有套件文件、收集 tag 注释并输出去重后的 tag 文档实现见 buildscripts/resmokelib/run/init.py。运行一个指定套件以套件文件名不带.yml传入./buildscripts/resmoke.py run --suitesaggregation在命令行覆盖TestData命令行设置优先级高于套件.yml可在不修改套件文件的情况下临时改变测试行为例如--shellTestData相关参数。自测参考Resmoke 各组件自身的单元测试位于 buildscripts/tests/resmokelib/testing/testcasesselector 等逻辑的测试也在 buildscripts/tests/resmokelib 下可作为理解字段语义的行为契约。十、速查表套件字段一览字段作用关键点test_kind测试类型常用js_test约 75% 套件完整清单见 testcases/README.mdselector.roots候选测试路径列表支持 glob非 glob 路径必须存在selector.root含 glob 的列表文件常用于cpp_unit_test如build/unittests.txtselector.include_files强制包含glob不在 roots 中会报错selector.exclude_files强制排除glob不在 roots 中会报错selector.include_with_any_tags按 tag 收录resmoke.py list-tags可查全部 tagselector.exclude_with_any_tags按 tag 排除优先级低于文件名规则executor.config.shell_options传给 mongo shell 的参数flag 用命名参数直接传executor.config.shell_options.global_vars作为--eval基础字符串TestData是特殊全局变量优先级命令行 yml 运行时/默认executor.hooks测试边界执行逻辑类名必须与 Python 类一致hook_logger/fixture自动注入executor.fixture测试拓扑class对应 Python 类名其余子字段进构造函数executor.archive.hooks失败时归档哪些 hook 数据可设true归档全部executor.archive.tests失败时归档哪些测试数据支持通配符可设true归档全部延伸阅读buildscripts/resmokelib/testing/testcases/README.md ——test_kind全部类型及对应 TestCase 实现buildscripts/resmokelib/testing/hooks/README.md —— 全部 hooks 及 Hook 接口before_suite/before_test/after_test/after_suitebuildscripts/resmokelib/testing/fixtures/README.md —— 全部 fixtures 及接口层次buildscripts/resmokeconfig/suites —— 344 个真实套件配置可直接作为模板参考jstests/README.md —— JS 测试编写指南【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考