本页内容
本页内容
插件 SDK 参考
插件测试
OpenClaw 插件的测试工具、模式和静态检查约束参考。
测试工具
这些子路径是 OpenClaw 自带插件测试的仓库本地源入口点。它们不是面向第三方插件发布的 package.json 导出项,并且它们可能会导入 Vitest 或其他仅限仓库内部使用的测试依赖。
请使用这些专用子路径进行自带插件测试。此前的 openclaw/plugin-sdk/testing 总入口仅供仓库本地使用,会被排除在已发布的软件包之外,现已移除。此前的 openclaw/plugin-sdk/test-utils 别名也已随之移除。pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts)会确保扩展测试使用上面的专用测试子路径。
捆绑通道集成测试可以使用 agent-runtime-test-contracts 进行真实会话和订户固定装置,使用 reply-payload-testing 进行有效负载构建和交付结算,使用 plugin-test-runtime 进行挂钩运行程序和注册。这些帮手重用了他们的核心所有者;显式注册会话装置生命周期。当已公开所需的操作时,使用已发布的运行时子路径。
关闭保留的插件运行时句柄后,调用 resetPluginRuntimeStateForTest() 并等待 plugin-test-runtime 中的 waitForPluginCacheRetirement(true) 以包含借用的缓存生成。在删除夹具文件或恢复环境之前,断言其 failures 数组为空。被拒绝或失败的退赛必须保持赛程完好无损。
等待来自 channel-ingress-test-runtime 或 plugin-state-test-runtime 的 listChannelIngressQueueAccountIdsForTests。它使用共享只读工作线程并保留未创建的缺失状态。在删除设备的状态目录之前加入异步数据库清理。
对于直接工人固定装置,请将 process-runtime 中的 resolveRuntimeWorkerUrl 与 test-env 中的 resolveRuntimeWorkerThreadExecArgv 配对。这使源代码和构建的工作程序保留在运行时所有者的启动参数上。
当测试或挂钩延迟加载已编译的子进程声明时,请使用 import "openclaw/plugin-sdk/compiled-subprocess-testing"; 在集合中预加载它。这个存储库本地的非生产子路径没有导出,并且使工作人员在测试截止日期之外进行准备,而不会在模拟或模块重置之前绑定主题。仅在已加载声明的测试中使用它。
可用导出项
| 导出项 | 用途 |
|---|---|
createTestPluginApi |
构建用于直接注册单元测试的最小插件 API 模拟。导入自 plugin-sdk/plugin-test-api |
AUTH_PROFILE_RUNTIME_CONTRACT |
原生代理运行时适配器共用的身份验证配置文件合同夹具。导入自 plugin-sdk/agent-runtime-test-contracts |
DELIVERY_NO_REPLY_RUNTIME_CONTRACT |
原生代理运行时适配器共用的消息投递抑制合同夹具。导入自 plugin-sdk/agent-runtime-test-contracts |
OUTCOME_FALLBACK_RUNTIME_CONTRACT |
原生代理运行时适配器共用的回退分类合同夹具。导入自 plugin-sdk/agent-runtime-test-contracts |
createParameterFreeTool |
为原生运行时合同测试构建动态工具架构夹具。导入自 plugin-sdk/agent-runtime-test-contracts |
expectChannelInboundContextContract |
断言频道入站上下文结构。导入自 plugin-sdk/channel-contract-testing |
installChannelOutboundPayloadContractSuite |
安装频道出站负载合同测试用例。导入自 plugin-sdk/channel-contract-testing |
createStartAccountContext |
构建频道账户生命周期上下文。导入自 plugin-sdk/channel-test-helpers |
installChannelActionsContractSuite |
安装通用频道消息操作合同测试用例。导入自 plugin-sdk/channel-test-helpers |
installChannelSetupContractSuite |
安装通用频道设置合同测试用例。导入自 plugin-sdk/channel-test-helpers |
installChannelStatusContractSuite |
安装通用频道状态合同测试用例。导入自 plugin-sdk/channel-test-helpers |
expectDirectoryIds |
从目录列表函数断言频道目录 ID。从 plugin-sdk/channel-test-helpers 导入 |
formatEnvelopeTimestamp |
信封时间戳的格式保持一致。从 plugin-sdk/channel-test-helpers 导入 |
expectPairingReplyText |
断言频道配对回复文本并提取其中的代码。导入自 plugin-sdk/channel-test-helpers |
describePluginRegistrationContract |
安装插件注册合同检查。导入自 plugin-sdk/plugin-test-contracts |
registerSingleProviderPlugin |
在加载器冒烟测试中注册单个提供商插件。导入自 plugin-sdk/plugin-test-runtime |
registerProviderPlugin |
捕获单个插件中的所有提供商类型。导入自 plugin-sdk/plugin-test-runtime |
registerProviderPlugins |
捕获多个插件中的提供商注册信息。导入自 plugin-sdk/plugin-test-runtime |
requireRegisteredProvider |
断言提供者集合包含一个 id。从 plugin-sdk/plugin-test-runtime 导入 |
createRuntimeEnv |
构建模拟的 CLI/plugin 运行时环境。从 plugin-sdk/plugin-test-runtime 导入 |
createPluginRuntimeMock |
构建模拟的插件运行时接口。导入自 plugin-sdk/plugin-test-runtime |
createPluginSetupWizardStatus |
为频道插件构建设置状态辅助工具。导入自 plugin-sdk/plugin-test-runtime |
createTestWizardPrompter |
构建模拟的设置向导提示器。导入自 plugin-sdk/plugin-test-runtime |
runProviderCatalog |
使用测试依赖执行提供商目录钩子。导入自 plugin-sdk/plugin-test-runtime |
resolveProviderModelPickerEntries |
在合同测试中解析提供商模型选择器条目。导入自 plugin-sdk/plugin-test-runtime |
buildProviderPluginMethodChoice |
为断言构建提供者向导选择 ID。从 plugin-sdk/plugin-test-runtime 导入 |
setProviderWizardProvidersResolverForTest |
为隔离测试注入提供商向导提供商。导入自 plugin-sdk/plugin-test-runtime |
describeOpenAIProviderRuntimeContract |
安装提供商系列运行时合同检查。导入自 plugin-sdk/provider-test-contracts |
expectPassthroughReplayPolicy |
断言提供商重放策略会透传提供商自有工具和元数据。导入自 plugin-sdk/provider-test-contracts |
runRealtimeSttLiveTest |
使用共用音频夹具运行实时实时 STT 提供商测试。导入自 plugin-sdk/provider-test-contracts |
normalizeTranscriptForMatch |
在模糊断言前规范化实时转录输出。导入自 plugin-sdk/provider-test-contracts |
expectExplicitVideoGenerationCapabilities |
断言视频提供商声明了明确的生成模式能力。导入自 plugin-sdk/provider-test-contracts |
expectExplicitMusicGenerationCapabilities |
断言音乐提供商声明明确的 generation/edit 功能。从 plugin-sdk/provider-test-contracts 导入 |
mockSuccessfulDashscopeVideoTask |
安装成功的 DashScope 兼容视频任务响应。导入自 plugin-sdk/provider-test-contracts |
getProviderHttpMocks |
访问选择加入提供商 HTTP/auth Vitest 模拟。从 plugin-sdk/provider-http-test-mocks 导入 |
installProviderHttpMockCleanup |
每次测试后重置提供程序 HTTP/auth 模拟。从 plugin-sdk/provider-http-test-mocks 导入 |
createOpenClawTestState / withOpenClawTestState / OpenClawTestState |
创建并清理隔离的 OpenClaw 状态、配置、工作区、环境和身份验证配置文件夹具。导入自 plugin-sdk/test-state |
installCommonResolveTargetErrorCases |
用于目标解析错误处理的共用测试用例。导入自 plugin-sdk/channel-target-testing |
shouldAckReaction |
检查频道是否应添加确认反应。导入自 plugin-sdk/channel-feedback |
removeAckReactionAfterReply |
回复投递后移除确认反应。导入自 plugin-sdk/channel-feedback |
createTestRegistry |
构建频道插件注册表夹具。导入自 plugin-sdk/plugin-test-runtime 或 plugin-sdk/channel-test-helpers |
createEmptyPluginRegistry |
构建空的插件注册表夹具。导入自 plugin-sdk/plugin-test-runtime 或 plugin-sdk/channel-test-helpers |
createPluginMetadataSnapshotFixture |
使用对齐的清单和已安装插件视图构建完整的元数据快照。从 plugin-sdk/plugin-test-runtime 导入 |
setActivePluginRegistry |
为插件运行时测试安装注册表夹具。导入自 plugin-sdk/plugin-test-runtime 或 plugin-sdk/channel-test-helpers |
clearActivePluginRegistry |
清除活动注册表装置并等待停用的注册表完成清理。从 plugin-sdk/plugin-test-runtime 导入 |
waitForPluginRegistryRetirement |
观察已开始对替换注册表进行的清理,而无需清除活动装置。从 plugin-sdk/plugin-test-runtime 导入 |
createRequestCaptureJsonFetch |
在媒体辅助工具测试中捕获 JSON 获取请求。导入自 plugin-sdk/test-media-understanding |
isLiveTestEnabled |
控制是否启用选择性提供商实时测试。导入自 plugin-sdk/test-live |
collectProviderApiKeys |
发现提供商实时测试所需的凭据。导入自 plugin-sdk/test-live-auth |
parseProviderModelMap |
解析 music/video 实时测试模型覆盖。从 plugin-sdk/test-media-generation 导入 |
withServer |
针对一次性本地 HTTP 服务器运行测试。导入自 plugin-sdk/test-env |
createMockIncomingRequest |
构建最小的传入 HTTP 请求对象。导入自 plugin-sdk/test-env |
withFetchPreconnect |
在安装预连接钩子的情况下运行获取测试。导入自 plugin-sdk/test-env |
withEnv / withEnvAsync |
临时修改环境变量。导入自 plugin-sdk/test-env |
createTempHomeEnv / withTempHome / withTempDir |
创建隔离的文件系统测试夹具。导入自 plugin-sdk/test-env |
createStagedInputOwnershipFixture |
创建所有者暂存的附件文件和无主的相似文件。从 plugin-sdk/test-env 导入 |
createMockServerResponse |
创建最小的 HTTP 服务器响应模拟。导入自 plugin-sdk/test-env |
createProviderUsageFetch |
构建提供商用量获取夹具。导入自 plugin-sdk/test-env |
useFrozenTime / useRealTime |
为时间敏感型测试冻结并恢复计时器。导入自 plugin-sdk/test-env |
createCliRuntimeCapture |
在测试中捕获 CLI 运行时输出。导入自 plugin-sdk/test-fixtures |
findSourceImportBackedges |
异步检查存储库源静态导入闭包是否存在禁止的依赖项。从 plugin-sdk/test-fixtures 导入 |
runDirectImportSmoke |
在隔离的 Node 进程中运行插件公共表面导入。从 plugin-sdk/test-fixtures 导入 |
importFreshModule |
使用新的查询令牌导入 ESM 模块,以绕过模块缓存。导入自 plugin-sdk/test-fixtures |
bundledPluginRoot / bundledPluginFile |
解析捆绑插件源代码或 dist 夹具路径。导入自 plugin-sdk/test-fixtures |
mockNodeBuiltinModule |
安装范围有限的 Node 内置模块 Vitest 模拟。导入自 plugin-sdk/test-node-mocks |
createSandboxTestContext |
构建沙箱测试上下文。导入自 plugin-sdk/test-fixtures |
writeSkill |
写入技能夹具。导入自 plugin-sdk/test-fixtures |
makeAgentAssistantMessage |
构建代理转录消息夹具。导入自 plugin-sdk/test-fixtures |
peekSystemEvents / resetSystemEventsForTest |
检查并重置系统事件夹具。导入自 plugin-sdk/test-fixtures |
sanitizeTerminalText |
清理终端输出以便断言。导入自 plugin-sdk/test-fixtures |
countLines / hasBalancedFences |
断言分块输出结构。导入自 plugin-sdk/test-fixtures |
typedCases |
为表驱动测试保留字面量类型。导入自 plugin-sdk/test-fixtures |
自带插件合同测试套件也会使用这些 SDK 测试子路径来获取仅供测试使用的注册表、清单、公共产物和运行时夹具辅助工具。 依赖自带 OpenClaw 库存的核心专用套件则仍放在 src/plugins/contracts 下。
对于渠道帐户策略测试,createAccountPolicyInheritanceCases()从openclaw/plugin-sdk/channel-test-helpers每次调用时返回四个带有新对象和数组的文字继承行,保留省略的策略字段。旁边使用它validateTestChannelConfig(channelId, channelConfig),它通过主机配置边界验证架构解析的通道数据。每个插件测试仍然拥有其架构解析、帐户解析器和断言,包括检查是否仍然不存在省略的帐户策略。
对于完整的零使用输入,openclaw/plugin-sdk/test-fixtures 中的 createZeroUsageFixture() 返回新的使用情况和嵌套成本对象,而无需可选的遥测字段。明确预期的使用价值。
类型
重点测试子路径还重新导出测试文件中有用的类型:
测试目标解析
使用 installCommonResolveTargetErrorCases 为频道目标解析添加标准错误案例:
测试模式
测试注册契约
将手写 api mock 传递给 register(api) 的单元测试,不会触发 OpenClaw 加载器的接受门槛。对于插件所依赖的每个注册入口, 至少添加一个基于加载器的冒烟测试,尤其是 hooks 以及诸如内存之类的独占能力。
真实加载器会在缺少必需元数据,或者插件调用了它不拥有的能力 API 时, 拒绝插件注册。例如,api.registerHook(...) 需要提供 hook 名称, 而 api.registerMemoryCapability(...) 则要求插件清单或导出的入口声明 kind: "memory"。
测试运行时配置访问
更喜欢 openclaw/plugin-sdk/plugin-test-runtime 的共享插件运行时模拟。它的运行时配置助手对当前快照和突变 API 进行建模。
频道插件的单元测试
提供者插件的单元测试
对于解析提供程序端点功能的捆绑目录测试,请在文件或套件范围内从 openclaw/plugin-sdk/plugin-test-runtime 调用 useProviderCatalogMetadata(new URL(".", import.meta.url))。它会准备一次插件的清单元数据,安装并清除每个测试周围的快照,并在断言期间拒绝 Jiti 加载。这使得冷运行时发现超出了目录测试截止日期,而无需改变提供程序的行为。
当案例执行另一个提供商的端点时,传递额外的清单根,例如 useProviderCatalogMetadata(new URL(".", import.meta.url), new URL("../google/", import.meta.url))。在特定于路由的情况下断言端点类,以便丢失的元数据无法将提供者路由转变为意外的自定义端点情况。
模拟插件运行时
对于使用 createPluginRuntimeStore 的代码,请在测试中 mock 运行时:
使用按实例 stub 进行测试
优先使用按实例 stub,而不是修改原型:
合同测试(仓库内插件)
捆绑的内置插件包含合同测试,用于验证注册归属:
这些测试会断言:
- 哪些插件注册了哪些提供者
- 哪些插件注册了哪些语音提供者
- 注册结构是否正确
- 运行时契约是否满足要求
为特定范围运行测试
对于特定插件:
仅运行合同测试:
Lint 强制规则(仓库内插件)
scripts/run-additional-boundary-checks.mts 会在 CI 中运行一组 lint:plugins:* 导入边界检查;每项检查也可以在本地单独运行:
| 命令 | 强制要求 |
|---|---|
pnpm run lint:plugins:no-monolithic-plugin-sdk-entry-imports |
捆绑插件不能导入单体的 openclaw/plugin-sdk 根入口文件。 |
pnpm run lint:plugins:no-extension-src-imports |
生产扩展文件不能直接导入仓库的 src/** 目录树(../../src/...)。 |
pnpm run lint:plugins:no-extension-test-core-imports |
扩展测试文件不能导入已移除的 SDK 测试别名或其他仅供核心使用的测试辅助工具。 |
外部插件不受这些 lint 规则约束,但仍建议遵循相同模式。
测试配置
OpenClaw 使用 Vitest 5 和信息性 V8 覆盖率报告。对于插件测试:
如果本地运行导致内存压力:
相关内容
- SDK Overview -- 导入约定
- SDK Channel Plugins -- 通道插件接口
- SDK 提供者 Plugins -- 提供者插件挂钩
- Building Plugins -- 入门指南