Chainlink CRE 冒烟测试套件 CI 与套件维护指南自动发现、矩阵拓扑与并行化实践【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink本文围绕 Chainlink 仓库中 Local CREChainlink Runtime Environment冒烟测试套件在持续集成CI中的设计与维护展开系统讲解.github/workflows/cre-system-tests.yaml工作流的自动发现机制、system-tests/tests/smoke/cre包的命名与放置约定、拓扑矩阵与按测试覆盖、以及新增测试和问题排查的完整流程。读完本文你将掌握如何为 CRE 冒烟套件新增一个可被 CI 自动拾取并正确匹配拓扑的测试并理解并行开关CRE_TEST_PARALLEL_ENABLED背后的源码实现。套件定位可发现、可重复、跨拓扑CRE 冒烟套件的设计目标有三点可发现discoverable、可重复repeatable、可跨多种拓扑运行across multiple topologies。这意味着新增测试时不需要在一个手工维护的清单里逐条登记——CI 会从测试目录中自动发现测试函数并基于支持的拓扑矩阵为每个测试分配运行环境。Auto-DiscoveryCI 如何自动发现测试三层流水线从 cre-system-tests.yaml 的源码结构看整个 CI 流程分三层发现测试CI 在system-tests/tests/smoke/cre目录下扫描测试函数构建矩阵将测试与受支持的拓扑、测试入口点做笛卡尔积生成矩阵逐项执行每个矩阵单元使用与拓扑匹配的配置运行对应测试。源码级的发现实现工作流中define-test-matrixjob 的核心是一行 grep 命令cre-system-tests.yaml 第 143 行test_names$(grep -rh -oP ^func \K(Test|Example)[^(] system-tests/tests/smoke/cre/*_test.go | grep -v Test_Upgrade | grep -v ^TestMain$)它扫描所有*_test.go文件中以func Test/func Example开头的函数名并排除Test_Upgrade升级测试有独立的运行通道与TestMain。随后通过 jq 将测试名与拓扑 JSON 组合成矩阵并为每个矩阵单元生成带test_id、runs_on16 核 64GB 的 m7i/m8i runner的条目。也就是说只要新测试满足发现条件它就会自动进入 CI 矩阵无需在 workflow 中登记。这正是文档强调的你不必在一个特制列表中手工注册每个新的 CRE 冒烟测试。命名与放置约定为了让自动发现机制稳定工作新测试必须遵循两条硬性约定cre_suite_test.go 中的实际实现全部符合目录测试必须放在system-tests/tests/smoke/cre包内chain 家族子目录如evm/、solana/、aptos/、stellar/也位于该包树下命名使用Test_CRE_前缀。从当前仓库的测试文件看实际前缀已演化为Test_CRE_V2_例如Test_CRE_V2_EVM_Write_LogTrigger、Test_CRE_V2_Suite_Bucket_A、Test_CRE_V2_Sharding该前缀正是 grep 发现命令与 workflow 中按测试名做拓扑覆盖匹配的依据风格沿用包内既有模式组织 setup 与 helper 调用。举例来说位于 cre_suite_test.go 第 36 行 的Test_CRE_V2_Suite_Bucket_A、第 279 行 的Test_CRE_V2_Aptos_Suite、第 339 行 的Test_CRE_V2_Sharding都是典型的可发现入口点。架构模式一次环境创建多次测试复用套件采用分离式架构这是它保持廉价和快速的关键环境创建每拓扑只做一次Local CRE 环境节点、合约、DON 拓扑针对某个拓扑启动一次多个测试复用该环境同一拓扑运行内的多个测试共享已部署的合约与节点成本收益相比为每个单独测试重建 Local CRE这种共享显著降低资源开销与总运行时间。在源码中Test_CRE_V2_Stellar_Suitecre_suite_test.go 第 287 行是这一模式的典型代表它先基于 stellar 拓扑配置创建一次testEnv然后在其下并行运行GetLatestLedger、ReadContract、StellarWrite、StellarDataFeedsWrite四个子测试共享同一套环境。并行执行与共享资源开关只在允许并行并行执行由环境变量CRE_TEST_PARALLEL_ENABLED控制。其底层实现在 t_helpers.go 第 944-947 行func ParallelEnabled() bool { v : strings.TrimSpace(strings.ToLower(os.Getenv(CRE_TEST_PARALLEL_ENABLED))) return v 1 || v true || v yes }接受1、true、yes三种取值。注意这个开关只是授予并行权限并不强制并行每个测试仍然自行决定是否安全地调用t.Parallel()。在 cre_suite_test.go 第 24-28 行var ( parallelEnabled t_helpers.ParallelEnabled() // topology is used in test names topology os.Getenv(TOPOLOGY_NAME) )parallelEnabled在包初始化时读取一次topology从环境变量TOPOLOGY_NAME注入并用于测试命名例如t.Run(Proof Of Reserve - topology, ...)。哪些场景并行哪些保持串行从 cre_suite_test.go 第 75-187 行 的runSuiteScenario可以看出立即并行Proof Of Reserve、HTTP Trigger Action、HTTP Action CRUD、Consensus 等场景在parallelEnabled为真时调用t.Parallel()保持串行依赖不可共享基础设施的场景不调用t.Parallel()。例如Test_CRE_V2_Sharding第 339 行标注了//nolint:paralleltest // subtests share the same sharding config因为其子测试共享同一个分片配置Test_CRE_V2_Solana_Write第 235 行标注隔离本地 CRE 环境运行Vault DON 场景则通过共享 fixture 实现部分共享、部分按子测试重建环境见第 86-129 行。CI 侧workflow 在运行测试时显式注入cre-system-tests.yaml 第 415 行PARALLEL_COUNT: 10 CRE_TEST_PARALLEL_ENABLED: true即以-test.parallel10的并行度运行同时把RUN_QUARANTINED_TESTS设为trueCI 始终运行被隔离的测试。CI 支持的拓扑与按测试覆盖默认拓扑CRE 工作流默认对所有测试运行workflow-gateway-capabilities拓扑。在 workflow 的TOPOLOGIES_JSONcre-system-tests.yaml 第 90-92 行中对应[ {topology:workflow-gateway-capabilities,configs:configs/workflow-gateway-capabilities-don.toml} ]即默认拓扑与配置对workflow-gateway-capabilities/configs/workflow-gateway-capabilities-don.toml。本地默认配置见 core/scripts/cre/environment/configs/workflow-gateway-capabilities-don.toml。按测试的显式覆盖某些测试必须替换默认拓扑需要在 workflow 的PER_TEST_TOPOLOGIES_JSON中显式声明。当前仓库中的真实覆盖映射包括测试入口点拓扑配置Test_CRE_V2_Aptos_Suiteworkflow-gateway-aptosconfigs/workflow-gateway-don-aptos.tomlTest_CRE_V2_Stellar_Suiteworkflow-gateway-stellarconfigs/workflow-gateway-don-stellar.tomlTest_CRE_V2_Solana_Write/Solana_LogTrigger/Solana_Read_*workflowconfigs/workflow-don-solana.tomlTest_CRE_V2_Sharding/ShardingWithHttpTriggerworkflow-gateway-shardedconfigs/workflow-gateway-sharded-don.tomlTest_CRE_V2_ShardManualAssignmentworkflow-gateway-sharded-manualconfigs/workflow-gateway-sharded-manual.tomlTest_CRE_V2_ShardRingOCROverridesworkflow-gateway-sharded-ringocr-overridesconfigs/workflow-gateway-sharded-ringocr-overrides.tomlTest_CRE_V2_Module_Cacheworkflow-gateway-cache-testconfigs/workflow-gateway-don-cache-test.tomlTest_CRE_V2_HTTP_Action_Multi_Gatewayworkflow-gateway-capabilities-multi-gatewayconfigs/workflow-gateway-capabilities-multi-gateway-don.tomlTest_CRE_V2_ConfidentialWorkflows_Relayworkflow-gateway-capabilities-confidential-workflowsconfigs/workflow-gateway-capabilities-don-confidential-workflows.tomlTest_CRE_V2_Suite_Bucket_B默认 workflow-gateway-capabilities-vault-stall-purge对应的 vault-stall-purge 配置矩阵构建逻辑会先为所有测试挂上默认拓扑再剔除那些在 per-test 映射中出现过的测试最后把映射中的测试按各自拓扑追加进矩阵见 cre-system-tests.yaml 第 150-163 行 的 jq 逻辑。因此如果一个新测试只适配非默认拓扑只写测试代码是不够的——你还必须在 workflow 矩阵中为它添加显式覆盖让 CI 以匹配的topology与configs组合运行它。保持拓扑无关的原则在条件允许时测试应尽量做到拓扑无关topology-agnostic。只有当工作流确实依赖不同的链家族或拓扑布局时才使用按测试的拓扑覆盖。例如Test_CRE_V2_HTTP_Action_Multi_Gateway会在非 multi-gateway 拓扑下通过t.Skipf跳过cre_suite_test.go 第 156-158 行而Test_CRE_V2_Suite_Bucket_B通过拓扑判断在默认拓扑与 vault-stall-purge 拓扑下选择不同的 vault 配置第 93-99 行体现了同一测试、多拓扑自适应的写法。新增一个冒烟测试的完整清单结合文档的七步指引与源码现状新增测试的操作路径如下放置把测试放在system-tests/tests/smoke/cre冒烟包内注意边缘场景、负面条件的用例应放在regression包冒烟包只放 happy path 与健全性检查见 cre_suite_test.go 第 18-22 行命名遵循Test_CRE_当前实现为Test_CRE_V2_前缀约定复用 helper优先使用共享辅助函数例如 t_helpers.go 中的SetupTestEnvironmentWithPerTestKeys、CompileAndDeployWorkflow、UniqueWorkflowName、ParallelEnabled等它们封装了环境创建、workflow 编译部署、命名去重与并行判断决定入口点判断测试属于现有 bucket如Test_CRE_V2_Suite_Bucket_A/B/C还是需要新的入口点非默认拓扑时加覆盖在.github/workflows/cre-system-tests.yaml的PER_TEST_TOPOLOGIES_JSON中添加显式矩阵覆盖验证矩阵确认测试在预期的拓扑矩阵下能正确运行可参考 grep 发现逻辑确认函数名可被拾取显式外部依赖保持外部依赖镜像、外部服务、secret清晰可查CI 中不可假设本地独有条件。关于测试入口点的组织值得说明的是较大的冒烟套件被拆分为运行时长均衡的 bucketTest_CRE_V2_Suite_Bucket_A/B/C定义于 system-tests/tests/smoke/cre/config/bucketing.goEVM Read 套件另有独立的 bucket 注册表system-tests/tests/smoke/cre/evm/evmread/config/bucketing.go。使用分桶入口点可以获得更短的本地反馈循环和更稳定的 CI 运行时长相关运行方式详见 docs/local-cre/system-tests/running-tests.md。排查CI 没有拾取到测试如果新增测试没有被 CI 拾取按以下顺序检查函数名以Test_开头确认函数名符合 grep 发现正则^func \K(Test|Example)[^(]且未被Test_Upgrade/TestMain排除规则误伤文件位于冒烟包确认文件在system-tests/tests/smoke/cre下*_test.go后缀是 grep 的扫描范围包可编译确认go build/go vet通过否则矩阵生成后的运行阶段会直接失败无本地独有假设确认测试不依赖 CI 中不存在的本地条件。一个容易踩的坑是端口冲突——多数冒烟测试的 ChIP test sink 默认绑定 gRPC 端口50051若同时以默认端口启动 Chip Ingress stack 会导致 sink 启动失败因此默认冒烟流程不要启用--with-chip-ingress-stack详见 running-tests.md 中关于端口冲突的说明。此外若测试在非默认拓扑下运行还应核对PER_TEST_TOPOLOGIES_JSON中的覆盖是否生效、TOPOLOGY_NAME是否被正确传入workflow 通过env: TOPOLOGY_NAME: ${{ matrix.tests.topology }}注入见 cre-system-tests.yaml 第 411 行。运行与调试的实用补充CI 中每个矩阵 job 的运行时长为 10 分钟其中测试本身预留 7 分钟TEST_TIMEOUT: 7m。本地运行完整套件建议预留约 20 分钟源码构建镜像场景。本地调试时可用如下模式缩小范围CTF_LOG_LEVELdebug \ go test ./system-tests/tests/smoke/cre -timeout 20m -run ^Test_CRE_V2_Suite_Bucket_A$该命令保持拓扑与 workflow 设置不变仅收窄到单个入口点。工作流失败时还会自动收集 Docker 容器日志并上传为 artifacttest-logs-${{ matrix.tests.test_name }}-${{ matrix.tests.topology }}可据此定位环境层面的故障。小结CRE 冒烟套件的 CI 维护模式可以概括为约定优于登记测试放对目录、取对名字就会被.github/workflows/cre-system-tests.yaml的 grep jq 矩阵自动发现默认拓扑统一、按测试覆盖例外并行由CRE_TEST_PARALLEL_ENABLED授权、由每个测试自行决策。理解这套机制后无论是新增跨链测试、调整分桶还是排查发现失败都能在源码层面找到明确依据。相关核心文件工作流定义 .github/workflows/cre-system-tests.yaml、套件入口 system-tests/tests/smoke/cre/cre_suite_test.go、共享 helper system-tests/tests/test-helpers/t_helpers.go。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考