跳转至

测试

OpenClaw 插件的测试工具、模式和 lint 强制检查参考。

Tip

正在寻找测试示例? how-to 指南包含实际测试示例: 频道插件测试 和 提供商插件测试。

测试工具

这些子路径是 OpenClaw 自身捆绑插件测试的仓库本地源码入口。它们不是面向第三方插件发布的 package.json 导出项,并且可能导入 Vitest 或其他仅限仓库使用的测试依赖。

import {
  shouldAckReaction,
  removeAckReactionAfterReply,
} from "openclaw/plugin-sdk/channel-feedback";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";
import { AUTH_PROFILE_RUNTIME_CONTRACT } from "openclaw/plugin-sdk/agent-runtime-test-contracts";
import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing";
import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers";
import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts";
import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime";
import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts";
import { getProviderHttpMocks } from "openclaw/plugin-sdk/provider-http-test-mocks";
import { createOpenClawTestState } from "openclaw/plugin-sdk/test-state";
import { withEnv, withFetchPreconnect, withServer } from "openclaw/plugin-sdk/test-env";
import { isLiveTestEnabled } from "openclaw/plugin-sdk/test-live";
import { createRequestCaptureJsonFetch } from "openclaw/plugin-sdk/test-media-understanding";
import {
  bundledPluginRoot,
  createCliRuntimeCapture,
  runDirectImportSmoke,
  typedCases,
} from "openclaw/plugin-sdk/test-fixtures";
import { mockNodeBuiltinModule } from "openclaw/plugin-sdk/test-node-mocks";

捆绑插件测试应使用这些聚焦的子路径。旧的 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 提供真实会话和订阅者 fixture,使用 reply-payload-testing 进行 payload 构造和投递结算,使用 plugin-test-runtime 提供 hook 运行器和注册表。这些 helper 会复用其核心归属模块;请显式注册会话 fixture 生命周期。当已发布的运行时子路径已经暴露所需操作时,请使用这些子路径。

在关闭保留的插件运行时句柄后,调用 resetPluginRuntimeStateForTest(),并等待来自 plugin-test-runtime 的 waitForPluginCacheRetirement(true),以包含借用的缓存代际。在删除 fixture 文件或恢复环境之前,断言其 failures 数组为空。被拒绝或失败的退役必须保持 fixture 完整。

等待来自 channel-ingress-test-runtime 或 plugin-state-test-runtime 的 listChannelIngressQueueAccountIdsForTests。它使用共享的只读 worker,并且不会创建缺失的状态。在删除 fixture 的状态目录之前,请等待异步数据库清理完成。

对于直接 worker fixture,请将 process-runtime 中的 resolveRuntimeWorkerUrl 与 test-env 中的 resolveRuntimeWorkerThreadExecArgv 配对使用。这样可以保持源码 worker 和构建后 worker 使用运行时所有者的启动参数。

当测试或 hook 延迟加载 compiled-subprocess 声明时,请在收集阶段通过 import "openclaw/plugin-sdk/compiled-subprocess-testing"; 预加载它。这个仓库本地、非生产子路径没有导出项,它让 worker 准备工作保持在测试截止时间之外,同时不会在 mock 或模块重置之前绑定被测对象。仅在已经加载声明的测试中使用它。

可用导出

导出 用途
createTestPluginApi 为直接注册单元测试构建最小插件 API mock。从 plugin-sdk/plugin-test-api 导入
AUTH_PROFILE_RUNTIME_CONTRACT 用于原生 agent 运行时适配器的共享 auth-profile 契约 fixture。从 plugin-sdk/agent-runtime-test-contracts 导入
DELIVERY_NO_REPLY_RUNTIME_CONTRACT 用于原生 agent 运行时适配器的共享投递抑制契约 fixture。从 plugin-sdk/agent-runtime-test-contracts 导入
OUTCOME_FALLBACK_RUNTIME_CONTRACT 用于原生 agent 运行时适配器的共享回退分类契约 fixture。从 plugin-sdk/agent-runtime-test-contracts 导入
createParameterFreeTool 为原生运行时契约测试构建动态工具 schema fixture。从 plugin-sdk/agent-runtime-test-contracts 导入
expectChannelInboundContextContract 断言频道入站上下文形状。从 plugin-sdk/channel-contract-testing 导入
installChannelOutboundPayloadContractSuite 安装频道出站 payload 契约用例。从 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-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 断言音乐提供商声明了显式生成/编辑能力。从 plugin-sdk/provider-test-contracts 导入
导出 用途
mockSuccessfulDashscopeVideoTask 安装一个成功的 DashScope 兼容视频任务响应。从 plugin-sdk/provider-test-contracts 导入。
getProviderHttpMocks 访问可选启用的提供商 HTTP/认证 Vitest 模拟。从 plugin-sdk/provider-http-test-mocks 导入。
installProviderHttpMockCleanup 在每个测试后重置提供商 HTTP/认证模拟。从 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 导入。
createRequestCaptureJsonFetch 在媒体辅助测试中捕获 JSON fetch 请求。从 plugin-sdk/test-media-understanding 导入。
isLiveTestEnabled 控制可选启用的实时提供商测试。从 plugin-sdk/test-live 导入。
collectProviderApiKeys 发现实时提供商测试的凭据。从 plugin-sdk/test-live-auth 导入。
parseProviderModelMap 解析音乐/视频实时测试模型覆盖。从 plugin-sdk/test-media-generation 导入。
withServer 针对一次性本地 HTTP 服务器运行测试。从 plugin-sdk/test-env 导入。
createMockIncomingRequest 构建最小传入 HTTP 请求对象。从 plugin-sdk/test-env 导入。
withFetchPreconnect 在安装预连接钩子的情况下运行 fetch 测试。从 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 构建提供商用量 fetch 测试夹具。从 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 解析捆绑插件的 source 或 dist 测试夹具路径。从 plugin-sdk/test-fixtures 导入。
mockNodeBuiltinModule 安装窄范围的 Node 内置 Vitest 模拟。从 plugin-sdk/test-node-mocks 导入。
createSandboxTestContext 构建沙箱测试上下文。从 plugin-sdk/test-fixtures 导入。
writeSkill 写入 skill 测试夹具。从 plugin-sdk/test-fixtures 导入。
makeAgentAssistantMessage 构建 agent 转录消息测试夹具。从 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 下。

对于频道账户策略测试,来自 openclaw/plugin-sdk/channel-test-helpers 的 createAccountPolicyInheritanceCases() 每次调用都会返回四行字面量继承行,并带有全新的对象和数组,同时保留被省略的策略字段。 将其与 validateTestChannelConfig(channelId, channelConfig) 一起使用,后者 通过宿主配置边界验证经过 schema 解析的频道数据。每个 插件测试仍负责自己的 schema 解析、账户解析器和断言, 包括检查被省略的账户策略保持缺失。

对于完整的零用量输入,来自 openclaw/plugin-sdk/test-fixtures 的 createZeroUsageFixture() 返回全新的用量和嵌套成本对象,不包含可选的遥测字段。保持预期用量值显式。

类型

聚焦测试子路径还会重新导出在测试文件中有用的类型:

import type {
  ChannelAccountSnapshot,
  ChannelGatewayContext,
} from "openclaw/plugin-sdk/channel-contract";
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
import type { MockFn, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/plugin-test-runtime";

测试目标解析

使用 installCommonResolveTargetErrorCases 为频道目标解析添加标准错误用例:

import { describe } from "vitest";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";

describe("my-channel target resolution", () => {
  installCommonResolveTargetErrorCases({
    resolveTarget: ({ to, mode, allowFrom }) => {
      // Your channel's target resolution logic
      return myChannelResolveTarget({ to, mode, allowFrom });
    },
    implicitAllowFrom: ["user1", "user2"],
  });

  // Add channel-specific test cases
  it("should resolve @username targets", () => {
    // ...
  });
});

测试模式

测试注册契约

将手写的 api 模拟传递给 register(api) 的单元测试不会执行 OpenClaw 加载器的准入检查。对于插件依赖的每个注册接口, 至少添加一个由加载器支持的冒烟测试,尤其是 hooks 和诸如 memory 之类的独占能力。

当必需元数据缺失,或插件调用了它不拥有的能力 API 时, 真实加载器会使插件注册失败。例如, api.registerHook(...) 需要 hook 名称,而 api.registerMemoryCapability(...) 要求插件清单或导出入口声明 kind: "memory"。

测试运行时配置访问

优先使用来自 openclaw/plugin-sdk/plugin-test-runtime 的共享插件运行时模拟。其运行时配置辅助函数模拟当前的 快照和变更 API。

单元测试频道插件

import { describe, it, expect, vi } from "vitest";

describe("my-channel plugin", () => {
  it("should resolve account from config", () => {
    const cfg = {
      channels: {
        "my-channel": {
          token: "test-token",
          allowFrom: ["user1"],
        },
      },
    };

    const account = myPlugin.setup.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("should inspect account without materializing secrets", () => {
    const cfg = {
      channels: {
        "my-channel": { token: "test-token" },
      },
    };

    const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
    expect(inspection.configured).toBe(true);
    expect(inspection.tokenStatus).toBe("available");
    // No token value exposed
    expect(inspection).not.toHaveProperty("token");
  });
});

单元测试提供商插件

对于解析提供商端点能力的捆绑目录测试,请在文件或套件作用域中从 openclaw/plugin-sdk/plugin-test-runtime 调用 useProviderCatalogMetadata(new URL(".", import.meta.url))。它会一次性准备插件的 manifest 元数据,在每个测试前后安装并清除该快照,并在断言期间拒绝 Jiti 加载。这样可在不改变提供商行为的情况下,避免冷运行时发现影响目录测试时限。

当某个用例需要验证其他提供商的端点时,请传入额外的 manifest 根目录,例如 useProviderCatalogMetadata(new URL(".", import.meta.url), new URL("../google/", import.meta.url))。在路由特定用例中断言端点类型,以免缺失的元数据将提供商路由变成非预期的自定义端点用例。

import { describe, it, expect } from "vitest";

describe("my-provider plugin", () => {
  it("should resolve dynamic models", () => {
    const model = myProvider.resolveDynamicModel({
      modelId: "custom-model-v2",
      // ... context
    });

    expect(model.id).toBe("custom-model-v2");
    expect(model.provider).toBe("my-provider");
    expect(model.api).toBe("openai-completions");
  });

  it("should return catalog when API key is available", async () => {
    const result = await myProvider.catalog.run({
      resolveProviderApiKey: () => ({ apiKey: "test-key" }),
      // ... context
    });

    expect(result?.provider?.models).toHaveLength(2);
  });
});

模拟插件运行时

对于使用 createPluginRuntimeStore 的代码,请在测试中模拟运行时:

import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "test-plugin",
  errorMessage: "test runtime not set",
});

// In test setup
const mockRuntime = {
  agent: {
    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
    // ... other mocks
  },
  config: {
    current: vi.fn(() => ({}) as const),
    mutateConfigFile: vi.fn(),
    replaceConfigFile: vi.fn(),
  },
  // ... other namespaces
} as unknown as PluginRuntime;

store.setRuntime(mockRuntime);

// After tests
store.clearRuntime();

使用每实例存根进行测试

优先使用每实例存根,而不是修改原型:

// Preferred: per-instance stub
const client = new MyChannelClient();
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });

// Avoid: prototype mutation
// MyChannelClient.prototype.sendMessage = vi.fn();

契约测试(仓库内插件)

捆绑插件包含用于验证注册所有权的契约测试:

pnpm test src/plugins/contracts/

这些测试会断言:

  • 哪些插件注册哪些提供商
  • 哪些插件注册哪些语音提供商
  • 注册结构正确性
  • 运行时契约合规性

运行范围测试

针对特定插件:

pnpm test <bundled-plugin-root>/my-channel/

仅运行契约测试:

pnpm test src/plugins/contracts/shape.contract.test.ts
pnpm test src/plugins/contracts/auth-choice.contract.test.ts
pnpm test src/plugins/contracts/runtime-seams.contract.test.ts

Lint 强制执行(仓库内插件)

scripts/run-additional-boundary-checks.mts 会在 CI 中运行一组 lint:plugins:* 导入边界检查;每个检查也可以在本地单独运行:

命令 强制规则
pnpm run lint:plugins:no-monolithic-plugin-sdk-entry-imports 捆绑插件不能导入单体 openclaw/plugin-sdk 根 barrel。
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 覆盖率报告。对于插件测试:

# Run all tests
pnpm test

# Run specific plugin tests
pnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts

# Run with a specific test name filter
pnpm test <bundled-plugin-root>/my-channel/ -t "resolves account"

# Run with coverage
pnpm test:coverage

如果本地运行导致内存压力:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw