Chainlink CRE 冒烟测试实战指南本地环境搭建、套件分桶与 CI 维护【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlinkCREChainlink Runtime Environment是 Chainlink 节点核心代码库当前仓库中承载链下计算、工作流编排与跨链能力的一套运行时体系。本指南围绕仓库中system-tests/tests/smoke/cre的 CRE 冒烟测试套件展开说明如何基于 Local CRE 环境运行这些测试、理解其环境引导机制、掌握分桶bucket选择与并行执行规则并在 CI 中正确维护和扩展套件。读完本文你将能够复现官方推荐的本地测试流程、按拓扑与场景精确挑选测试入口并遵循仓库约定新增一条可被 CI 自动发现的冒烟测试。CRE 冒烟测试的定位包级规则与适用边界system-tests/tests/smoke/cre/README.md首先给出了一条贯穿整套测试的“经验法则”Rule of ThumbHappy-path正常路径与 sanity checks健全性检查属于smoke边缘场景与负向条件属于regression。这条规则的完整展开见 docs/local-cre/system-tests/index.mdsmoke 测试覆盖正常路径与健全性检查行为而边界情况、负向条件应放在system-tests/tests/regression/cre包中。该边界也在 cre_suite_test.go 的包注释中被代码化//////////// SMOKE TESTS ///////////// // target happy path and sanity checks // all other tests (e.g. edge cases, negative conditions) // should go to a regression package /////////////////////////////////////从源码结构看冒烟测试目录 system-tests/tests/smoke/cre 下按链族与能力维度组织了大量场景EVM 读写、Solana 读写与日志触发、Aptos、Stellar、Vault、HTTP Action、分片sharding等每个子目录通常带独立go.mod与main.go形成可独立编译运行的分包。这与套件可发现、可复用、可跨拓扑运行的设计目标一致。快速开始五分钟拉起本地冒烟套件仓库 README 给出了最小化的快速启动流程这也是本地验证 CRE 冒烟套件的最短路径cd core/scripts/cre/environment go run . env setup go run . env start --with-chip-ingress-stack go test ./system-tests/tests/smoke/cre -timeout 20m -run ^Test_CRE_命令拆解如下go run . env setup初始化 Local CRE 环境下载依赖镜像、生成配置文件等准备步骤go run . env start启动本地 CRE 环境。--with-chip-ingress-stack会额外拉起 Chip Ingress 观测栈--with-beholder为已废弃的等价旧参数go test以^Test_CRE_前缀正则选中全部 CRE 冒烟测试并给出20m的整体超时预算。关于--with-chip-ingress-stack的端口冲突警告docs/local-cre/system-tests/running-tests.md 特别强调默认冒烟流程不要开启--with-chip-ingress-stack。原因在于多数 CRE 冒烟测试会在默认 gRPC 端口50051上启动 ChIP 测试接收端test sink而 Chip Ingress 栈同样占用该端口两者同时使用默认端口时测试接收端会启动失败。--with-beholder已废弃其行为与--with-chip-ingress-stack相同。仅在以下情况才需要开启 Chip Ingress 栈你正在运行与 Chip Ingress 栈强相关的专项覆盖如CronChipIngressStack场景调试时需要借助该栈观测你通过--grpc-port将 Chip Ingress 改到别的端口把默认50051留给测试接收端。因此官方推荐的常规本地流程是见 running-tests.mdcd core/scripts/cre/environment go run . env setup go run . env start go test ./system-tests/tests/smoke/cre -timeout 20m -run ^Test_CRE_cre_suite_test.go 的头部注释也记录了同样的执行路径先在core/scripts/cre/environment下执行go run . env restart --with-chip-ingress-stack标注 deprecated再在冒烟包内执行go test -timeout 15m -run ^Test_CRE_。测试如何自动引导本地 CRECTF_CONFIGS 的切换机制使用这套套件时你可以手动先启动 Local CRE 再跑测试也可以让测试助手替你引导环境。其底层实现位于 system-tests/tests/test-helpers/before_suite.go核心机制分三步与 index.md 的描述一一对应若CTF_CONFIGS为空助手将其设置为请求的拓扑配置setConfigurationIfMissing在CTF_CONFIGS为空时写入EnvironmentConfigPath并设置默认私钥before_suite.go#L333-L342若 Local CRE 状态文件不存在助手自动执行go run . env startcreateEnvironmentIfNotExists检查状态文件缺失时拼装env start命令并执行before_suite.go#L344-L360环境创建完成后CTF_CONFIGS被切换为本地 CRE 状态文件使测试消费已部署的环境而非原始拓扑 TOMLbefore_suite.go#L320-L331。func createEnvironment(t *testing.T, testConfig *ttypes.TestConfig, flags ...string) { // 1. 未设置 CTF_CONFIGS 时写入拓扑配置路径 setConfigurationIfMissing(testConfig.EnvironmentConfigPath) // 2. 状态文件不存在则自动 env start createEnvironmentIfNotExists(...) // 3. 切换 CTF_CONFIGS 到 Local CRE 状态文件 os.Setenv(CTF_CONFIGS, envconfig.MustLocalCREStateFileAbsPath(...)) }这就是手动启动与助手自举两种方式都能跑通的原因。此外共享环境通过sync.Once保证每个配置路径 flags组合只创建一次环境同一拓扑下的多个测试复用同一套已部署合约与节点before_suite.go#L116-L152这正是下文架构模式中每拓扑创建一次环境的实现基础。本地运行细节超时、调试与 VS Code 配置超时预算运行时长与镜像来源强相关running-tests.md镜像从源码构建时预留约20 分钟使用预构建镜像时运行时间显著缩短。调试单个分桶缩小范围、保留完整拓扑与工作流设置的单测调试模式CTF_LOG_LEVELdebug \ go test ./system-tests/tests/smoke/cre -timeout 20m -run ^Test_CRE_V2_Suite_Bucket_A$CTF_LOG_LEVELdebug会输出更详细的框架日志便于定位环境搭建阶段的失败。VS Code 调试启动配置文档同时给出了可直接使用的 VS Code launch 配置mode: test{ name: Launch CRE V2 Bucket A, type: go, request: launch, mode: test, program: ${workspaceFolder}/system-tests/tests/smoke/cre, args: [-test.run, ^Test_CRE_V2_Suite_Bucket_A$] }环境变量速查表冒烟套件主要依赖以下环境变量来源running-tests.md 及对应源码环境变量作用源码依据CTF_CONFIGS启动前指向拓扑 TOML启动后指向生成的 Local CRE 状态文件本地运行由助手自动切换before_suite.goTOPOLOGY_NAME用于测试名、bucket 标签与日志输出使结果与所测拓扑绑定cre_suite_test.goCTF_LOG_LEVELdebug输出更详细的框架日志—CTF_JD_IMAGE固定 Job Distributor 镜像避免默认本地镜像选择running-tests.mdCTF_CHAINLINK_IMAGE固定 Chainlink 节点镜像dons.go其中CTF_CHAINLINK_IMAGE的消费点可以精确定位system-tests/lib/cre/environment/dons.go 中的ensureGithubTokenForPrivatePlugins会先检查该变量——若通过环境变量提供了镜像则无需本地 Docker 构建否则当节点规格Image为空需要构建时会要求GITHUB_TOKEN存在缺失时尝试通过gh auth token获取以便从私有仓库安装插件。并行执行默认关闭、按场景放行并行执行是显式开启的running-tests.mdCRE_TEST_PARALLEL_ENABLED1但该开关只是允许并行并不会盲目并行化所有用例。在 cre_suite_test.go 中每个场景独立判断是否调用t.Parallel()部分场景如 ProofOfReserve、HTTP Trigger Action、Consensus 等在parallelEnabled为真时立即并行部分场景保持串行因为它们依赖不可共享的基础设施例如 cre_suite_test.go 中共享同一分片配置的 Sharding 系列测试显式标注了//nolint:paralleltest。这与 docs/local-cre/system-tests/ci-and-suite-maintenance.md 中该标志只授权并行每个测试仍需自行判断是否安全调用t.Parallel()的说明一致。拓扑选择默认拓扑与显式覆盖默认本地流程使用的拓扑为core/scripts/cre/environment/configs/workflow-gateway-capabilities-don.toml对应源码中的默认配置GetDefaultTestConfig即指向该文件before_suite.go#L291-L295。仅在你有意覆盖时分片、纯网关、特定链族等覆盖才需要改写CTF_CONFIGS。仓库 configs 目录 中已内置多套可选拓扑workflow-gateway-don.toml、workflow-gateway-don-aptos.toml、workflow-gateway-don-stellar.toml不同链族/网关布局workflow-gateway-sharded-don.toml、workflow-gateway-sharded-manual.toml、workflow-gateway-sharded-ringocr-overrides.toml分片及手动分配、OCR 覆盖workflow-gateway-capabilities-multi-gateway-don.toml多网关路由workflow-gateway-capabilities-don-vault-stall-purge.toml、...-vault-workflow-don-binding-enabled.tomlVault 相关专项拓扑。分桶测试选择从超大入口到运行时均衡较大的 CRE 冒烟套件被拆分为按运行时均衡的多个 bucket而不是一个超大的测试入口running-tests.md。旧版 V2 套件分为三个入口Test_CRE_V2_Suite_Bucket_ATest_CRE_V2_Suite_Bucket_BTest_CRE_V2_Suite_Bucket_C其场景分配定义在 system-tests/tests/smoke/cre/config/bucketing.gosuite-bucket-aProofOfReserve、HTTPTriggerAction、DONTime、Consensussuite-bucket-bVaultDONsuite-bucket-cCronChipIngressStack、HTTPActionCRUD、HTTPActionMultiGateway后者除非TOPOLOGY_NAME包含multi-gateway否则跳过分桶注册表还带有完整性校验ValidateSuiteBucketRegistry会检查每个场景是否恰好被分配到一个 bucket、是否存在重复分配或未分配场景bucketing.go#L100-L126。runSuiteBucket在启动时即调用该校验cre_suite_test.go#L48-L55防止分桶配置漂移。注释中还给出了再平衡的建议在 CI 跑一次依据各用例执行时间重新分配保持 bucket 运行时均衡。多网关 HTTP Action 路由使用多网关拓扑并运行对应测试TOPOLOGY_NAMEworkflow-gateway-capabilities-multi-gateway \ go test ./system-tests/tests/smoke/cre -timeout 20m -run ^Test_CRE_V2_HTTP_Action_Multi_Gateway$注意TOPOLOGY_NAME需包含multi-gateway否则该场景会直接跳过cre_suite_test.go#L154-L164。EVM 读套件EVM 读场景使用独立的 bucket 注册表位于 system-tests/tests/smoke/cre/evm/evmread/config/bucketing.go入口为Test_CRE_V2_EVM_Read_HeavyCallsTest_CRE_V2_EVM_Read_StateQueriesTest_CRE_V2_EVM_Read_TxArtifacts何时使用分桶入口本地反馈循环更短CI 运行时长更稳定套件增长时能以可控方式再平衡各场景的运行时。测试中的工作流优先使用共享助手冒烟测试通常不应自行实现工作流编译、产物拷贝与注册逻辑而应复用共享助手docs/local-cre/system-tests/workflows-in-tests.mdt_helpers.CompileAndDeployWorkflow(...)该助手负责默认将工作流产物拷贝到工作流 DON按需支持额外的产物拷贝目标WithArtifactCopyDONTypes(...)创建工作流产物从已部署环境解析工作流注册表以当前注册表版本注册工作流。工作流编译规则源码级共享编译器位于 system-tests/lib/cre/workflow/compile.go其执行规则与文档描述一致工作流名称必须不少于 10 个字符compile.go#L37-L39Go 工作流构建前先执行go mod tidycompile.go#L115-L119并以CGO_ENABLED0、GOOSwasip1、GOARCHwasm交叉编译为 WASMcompile.go#L121-L127TypeScript 工作流通过bun cre-compile编译compile.go#L95-L110语言由文件扩展名自动识别.ts/.tsx走 TS.go走 Gocompile.go#L83-L93最终产物为 Brotli 压缩 base64 编码输出为.br.b64文件compile.go#L137-L174。配置、密钥与 YAML 工作流工作流配置文件是可选的、与具体被测工作流相关。共享工作流包提供密钥支持会为注册准备针对当前 DON 与能力注册表的加密密钥。该领域还涵盖工作流密钥处理、YAML/DSL 工作流、直接的 JDJob Distributor任务提案流程——这些模式只留给确实需要底层控制的测试标准冒烟路径仍应优先使用CompileAndDeployWorkflow。环境助手二选一Per-Test Keys 还是共享 Root Signer编写测试时比工作流编译更重要的选择是使用哪个环境助手workflows-in-tests.md。场景一SetupTestEnvironmentWithPerTestKeys(...)工作流平面可并行适用于可能并行执行、或执行独立链上写入的工作流平面测试。该路径实现见 before_suite.go#L177-L248为测试生成全新的已注资密钥对注资额为perTestEVMFundingAmountWei 1 ETH将 EVM 客户端与部署者密钥切换为该测试专属签名者通过 seth 新建 per-test 客户端、替换 CLDF deployer key需要时在 v2 工作流注册表上授权该签名者authorizePerTestWorkflowSignerIfNeeded调用UpdateAllowedSigners且对根签名者 nonce 加锁保护从而避免并行测试之间的 nonce 冲突与共享密钥耦合。场景二SetupTestEnvironmentWithConfig(...)控制平面共享根签名者适用于管理员/控制平面或所有权敏感测试必须使用共享 root signer。这是以下流程的更安全选择V1 注册表测试分片与所有权管理操作如ShardConfig的 ownership-admin有意以环境所有者身份执行的测试。经验法则v2 工作流执行测试默认用SetupTestEnvironmentWithPerTestKeys仅当测试需要共享所有者权限、或有意避开 per-test 签名者隔离时才用SetupTestEnvironmentWithConfig。二者的差异同样体现在 before_suite.go 的注释与setupTestEnvironmentWithConfigMode实现中。价格数据源TrueUSD 与 Fake 的实现差异Proof-of-Reserve 相关测试使用共享的PriceProvider抽象包含两种实现workflows-in-tests.mdTrueUSDPriceProvider使用真实 TrueUSD 储备端点主要校验价格是否变为非零FakePriceProvider启动一次共享的 fake HTTP 服务为每条 feed 生成有界序列的测试价格强制校验 auth 头并同时追踪期望价格与实际价格以便严格断言。Fake 实现的源码位于 system-tests/tests/smoke/cre/por_price_provider.go通过sync.Once保证 fake 数据提供者只启动一次避免端口冲突响应体模拟 TrueUSD 的accountName/totalTrust/ripcord/updatedAt字段并通过Authorization头校验请求合法性未授权返回 401。使用建议本地与可重复的冒烟覆盖用 fake provider仅当场景有意验证与真实数据的集成路径时才使用 live provider。CI 与套件维护自动发现与拓扑矩阵自动发现机制ci-and-suite-maintenance.md 描述的高层 CI 流程为CI 自动发现system-tests/tests/smoke/cre下的测试构建拓扑 × 测试入口矩阵每个测试以适配该拓扑的配置运行。这意味着新增 CRE 冒烟测试无需手工登记到专属列表。命名与放置约定测试放在system-tests/tests/smoke/cre包中函数名以Test_CRE_前缀开头遵循现有包内的 setup 与助手使用模式。架构模式每拓扑建一次环境套件采用分离模式ci-and-suite-maintenance.md每个拓扑只创建一次环境多个测试复用该环境已部署合约与节点在拓扑运行内共享。这比每个测试都重建 Local CRE 更便宜、更快——其实现即上文提到的sync.Once共享环境缓存before_suite.go#L116-L152。CI 中的受支持拓扑与逐测试覆盖默认情况下CRE 工作流对workflow-gateway-capabilities拓扑运行测试。部分测试必须用显式的逐测试覆盖替换默认拓扑集合当前示例在.github/workflows/cre-system-tests.yaml中配置Test_CRE_Aptos_Suite→workflow-gateway-aptosTest_CRE_Solana_Suite→workflowTest_CRE_Sharding→workflow-gateway-sharded关键约束若新测试只适用于非默认拓扑仅添加测试代码是不够的还必须在工作流矩阵中显式添加覆盖让 CI 以匹配的topology与configs组合运行它。尽量保持测试拓扑无关仅当工作流确实依赖不同链族或拓扑布局时才使用逐测试拓扑覆盖。新增一条冒烟测试的七步流程按照 ci-and-suite-maintenance.md 的清单将测试放入 smoke 包遵循现有命名约定Test_CRE_前缀优先使用共享助手CompileAndDeployWorkflow、环境助手等决定它属于现有 bucket 还是需要新入口若需要非默认拓扑添加显式的工作流矩阵覆盖验证其在预期的拓扑矩阵下正常工作保持外部依赖显式化。故障排查清单测试逻辑启动前失败running-tests.md确认CTF_CONFIGS值正确确认 Local CRE 状态文件有效确认所需镜像存在重跑go run . env setup开启 debug 日志重跑CTF_LOG_LEVELdebug。CI 未发现测试ci-and-suite-maintenance.md确认函数名以Test_开头确认文件位于 smoke 包内确认包可编译确认测试不依赖 CI 中不存在的本地专属假设。推荐的本地工作流综合 index.md 的建议日常本地验证按以下顺序进行拉起 Local CREgo run . env setupgo run . env start确认目标拓扑默认workflow-gateway-capabilities-don.toml特殊场景按需覆盖运行相关冒烟测试全量^Test_CRE_或精确到分桶/单场景仅在场景确实需要额外信号时才使用 Chip Ingress 栈或观测能力并避开默认50051端口冲突。以上内容均基于当前仓库内文档与源码验证文档骨架来自 system-tests/tests/smoke/cre/README.md 及其链接的 docs/local-cre 长文档实现细节对照了 cre_suite_test.go、bucketing.go、before_suite.go、compile.go 与 dons.go 等源码文件读者可沿这些路径继续深入探索。【免费下载链接】chainlinknode of the decentralized oracle network, bridging on and off-chain computation项目地址: https://gitcode.com/GitHub_Trending/ch/chainlink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考