MongoDB Matrix Resmoke Suites 实战指南：用映射文件与 Overrides 组合复用测试套件

MongoDB Matrix Resmoke Suites 实战指南用映射文件与 Overrides 组合复用测试套件【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo导读Matrix Resmoke Suites 是 MongoDB 仓库buildscripts/resmokeconfig/matrix_suites中一套用于**组合、复用和批量生成测试套件suite**的机制它以普通 suite 文件为base_suite基座通过overrides、excludes、eval、extends四类修改器叠加差异化配置再由generate-matrix-suites命令自动生成完整套件文件。读完本文你将掌握 matrix suite 映射文件的完整写法、四种修改器的语义与优先级、生成与校验流程并能读懂仓库中 268 个映射文件和 43 个 override 文件的真实工程实践。一、Matrix Suites 是什么从复制粘贴到声明式组合在 MongoDB 的测试体系中普通测试套件suite是配置测试如何运行的 YAML 文件包含test_kind、selector、executor等核心字段详见 buildscripts/resmokeconfig/suites/README.md。随着测试矩阵膨胀多版本、多分片、加密、多 mongos 等组合逐份复制并手工维护这些 suite 文件会产生大量重复。Matrix Suites 正是为了解决这一痛点每个 matrix suite 由一个映射文件mapping file 若干 override 文件组合而成。映射文件声明以哪个 suite 为底座、叠加哪些修改器目标是在不复制 suite 定义的前提下让大多数 suite 由可复用的片段完全组合出来。base_suite来自 buildscripts/resmokeconfig/suites 目录而修改器片段统一存放在 buildscripts/resmokeconfig/matrix_suites/overrides 目录中。Matrix suite 与普通 suite 完全兼容对于 resmoke.py 的所有功能list-suites、find-suites、run --suites[SUITE]matrix suite 的行为与普通 suite 一致——因为它们最终会被展开成普通 suite 文件。生成的 suite 文件中带有matrix_suite: true标记例如 aggregation_pqs_hints.yml。二、目录结构与文件流转buildscripts/resmokeconfig/matrix_suites/ ├── mappings/ # 268 个映射文件声明 base_suite 修改器 ├── overrides/ # 43 个 YAML 文件存放可复用的修改器片段 ├── generated_suites/ # 生成的完整 suite可直接被 resmoke 运行 ├── OWNERS.yml └── README.md # 本文对应的原始文档从目录统计可以看出这套机制的规模化程度268 个映射文件涵盖聚合、change_streams、并发、分片、多版本、索引构建等主题43 个 override 文件如encryption.yml、query_settings.yml、change_streams.yml、kill_primary.yml提供了细粒度复用单元。映射文件编写完成后必须执行生成命令产出对应的 generated suite。三、编写映射文件结构与四种修改器映射文件本身就是一个 YAML suite 定义包含base_suite必填、一组修改器列表以及可选的description字段该描述会随本地 resmoke 调用输出也会写入生成的 suite 文件。一个真实的映射文件示例aggregation_pqs_hints.ymlbase_suite: aggregation description: - Test the correctness of query settings application by emulating cursor hints with setQuerySettings commands. This suite runs aggregation tests using a replica set fixture. excludes: - query_settings.common_aggregation_excludes eval: - query_settings.eval_cursor_hints_to_query_settings overrides: - query_settings.replica_sets_fixture - query_settings.test_data_cursor_hints_to_query_settings每个修改器字段使用**点分隔记法dot-delimited notation**表示文件.字段例如query_settings.replica_sets_fixture指向 overrides/query_settings.yml 中name: replica_sets_fixture的片段文档中举的encryption.mongodfixture_ese则对应 overrides/encryption.yml 中同名的片段。所有修改器引用的字段都必须存在于overrides目录的某个 YAML 文件中。override 文件的结构是一个顶层列表每一项由name和value组成value是待注入的 YAML 子树- name: mongodfixture_ese value: executor: fixture: mongod_options: enableEncryption: encryptionKeyFile: src/mongo/db/modules/enterprise/jstests/encryptdb/libs/ekf2下面逐个详解四种修改器的语义。3.1 overrides整树覆盖 base_suite 字段overrides中引用的所有字段会覆盖base_suite中对应位置的字段。它的优先级最高优先于excludes与eval。多个 override 按映射文件中列出的顺序依次处理因此顺序很重要如果多个 override 试图写入 base_suite 的同一字段后者生效。从 change_streams_secondary_reads.yml 可以看到典型用法base_suite: change_streams overrides: - change_streams.mongos_passthrough - change_streams.secondary_reads - change_streams.disable_write_noops - change_streams.base_eval其中change_streams.mongos_passthroughoverrides/change_streams.yml一次性覆盖了executor.archive.hooks、executor.hooks、executor.fixture三个子树——把基座 suite 的 replica set 夹具整体替换为ShardedClusterFixturenum_shards: 2、num_mongos: 3。3.2 excludes追加排除条件excludes中引用的字段会追加到 base_suite 的selector.exclude_with_any_tags与selector.exclude_files上按映射文件中指定的顺序追加。修改器字段中只允许这两个键例如- name: secondary_reads_excludes value: exclude_with_any_tags: - assumes_read_preference_unchanged - does_not_support_causal_consistency exclude_files: - jstests/change_streams/only_wake_getmore_for_relevant_changes.js实战中这些排除列表往往非常庞大且有详细注释例如 overrides/query_settings.yml 中的common_core_excludes逐条解释了排除原因使用查询设置或索引过滤器的测试会被本 suite 覆盖断言执行指标数量的测试会因额外命令失败等。3.3 eval追加 shell 的 eval 脚本eval中引用的字段会追加到 base_suite 的executor.config.shell_options.eval按映射文件中指定的顺序追加。典型值是一段在 shell 中执行的 JS 代码通常用于load()/import()覆盖方法override methods例如- name: secondary_reads_eval value: eval: await import(jstests/libs/override_methods/set_read_preference_secondary.js);映射文件change_streams_secondary_reads.yml中组合多个 evaleval: - change_streams.secondary_reads_eval - change_streams.causal_consistency_eval3.4 extends按路径追加列表extends引用的字段必须都是列表并会追加到同一路径下的对应键。它排在最后应用晚于其他修改器且被扩展的键必须已存在并且是列表否则会出错。这是四种修改器中语义最精确的一个它只做追加不改写、不覆盖。示例见 change_streams_pre_images_replica_sets_kill_secondary_jscore_passthrough.ymlextends: - change_streams_pre_images_remover.enable_pre_images_hook3.5 修改器组合一览修改器作用于 base_suite 的位置语义优先级overrides任意字段整树覆盖最高先于 excludes/eval 处理excludesselector.exclude_with_any_tags、selector.exclude_files追加中evalexecutor.config.shell_options.eval追加中extends任意已存在的列表键按路径追加最后应用且要求键已存在四、生成 Matrix Suites映射文件并不是直接可运行的 suite——编写完成后必须生成对应的 matrix suite 文件。生成产物位于buildscripts/resmokeconfig/matrix_suites/generated_suites目录每个生成文件顶部都有醒目的自动生成声明########################################################## # THIS IS A GENERATED FILE -- DO NOT MODIFY. # IF YOU WISH TO MODIFY THIS SUITE, MODIFY THE CORRESPONDING MATRIX SUITE MAPPING FILE # AND REGENERATE THE MATRIX SUITES. # # matrix suite mapping file: buildscripts/resmokeconfig/matrix_suites/mappings/aggregation_pqs_hints.yml # regenerate matrix suites: buildscripts/resmoke.py generate-matrix-suites ##########################################################生成命令为buildscripts/resmoke.py generate-matrix-suites注意该命令会直接覆盖磁盘上现有的 generated suites 文件因此执行前务必确认没有对这些文件保留任何未保存的修改。生成的套件文件可以为了本地测试而手工编辑但必须与映射文件保持一致否则校验会失败见下一节。生成后的文件是完整、可直接运行的 suite例如 aggregation_pqs_hints.yml 将 base_suite 的 roots、excludes、fixture、hooks、eval 与所有修改器合并为一份自洽的 YAML并额外带有matrix_suite: true标记、description以及基础 suite 自带的RunQueryStats、ValidateCollections、CleanEveryN等 hooks。4.1 生成的 suite 如何工作以aggregation_pqs_hints为例生成的 suite 体现了 matrix 机制的完整合并效果selector继承aggregationbase_suite 的 rootsjstests/aggregation/**/*.js与基础 excludesjstests/aggregation/extras/*.js等再追加query_settings.common_aggregation_excludes的排除文件与标签executor.fixture被query_settings.replica_sets_fixture覆盖为ReplicaSetFixturenum_nodes: 2开启enableTestCommandsexecutor.config.shell_options.evalbase_suite 的检测脚本与query_settings.eval_cursor_hints_to_query_settings的覆盖方法按序拼接global_vars.TestData写入isHintsToQuerySettingsSuite: true供测试运行时读取。这正印证了文档的核心设计目标——最大程度复用 suite 片段避免定义重复。五、校验机制映射文件与生成文件的同步保障所有 matrix suite 在每次被运行时都会被校验确保映射文件与生成的 suite 文件保持同步。仓库在 commit queue 中安排了resmoke_validation_tests任务专门保证这些文件通过校验同时从 matrix_suites/OWNERS.yml 可以看到连generated_suites/OWNERS.yml本身也是由buildscripts/resmoke.py generate-matrix-suites自动再生成的——这保证了目录内的所有权配置同样不会与手工修改脱节。因此对生成文件进行任何本地编辑后都应在提交前重新生成或恢复确保 CI 校验通过。六、源码层面的佐证从映射到生成的关键环节虽然 matrix suite 的展开逻辑由 buildscripts/resmoke.py 驱动但从仓库现有文件可以确认以下事实映射文件是唯一事实来源每个 generated suite 头部都写明了其对应的映射文件路径与再生成命令见上文的自动生成声明任何对生成的修改都必须回溯到映射文件。override 是细粒度的可复用单元43 个 override 文件中的片段被 268 个映射文件交叉引用。例如encryption.yml提供的mongodfixture_ese、mongodfixture_gcm、testdata_ese、testdata_gcm等片段可被任何需要加密测试的 suite 组合引用change_streams.yml的mongos_passthrough则被大量 change_streams 映射文件复用。组合式命名体现矩阵化思想generated_suites 中的文件名如change_streams_sharded_collections_passthrough_last_continuous_new_old_old_new.yml直观地展示了功能维度 × 多版本维度的矩阵组合方式这正是用映射文件声明、按需组合生成才能低成本维护的规模。七、FAQ 与进一步阅读关于使用者/作者体验的问题文档指向 #server-testing 频道MongoDB 内部协作渠道。深入理解普通 suite 字段请阅读 buildscripts/resmokeconfig/suites/README.md其中详细说明了test_kind、selector、executor、hooks、fixture、archive 等 suite 顶层字段的语义——这些正是base_suite与修改器共同作用的对象。实际动手浏览 mappings 与 overrides 目录中的真实文件对照本文的四种修改器逐例分析再运行buildscripts/resmoke.py generate-matrix-suites观察合并结果是掌握这套机制最快的方式。补充说明本文所述命令与文件均以当前仓库实际内容为准。执行generate-matrix-suites会覆写generated_suites目录下的文件请确保在干净的工作区中操作并在提交前通过resmoke_validation_tests类校验。【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考