Plugin 테스트

OpenClaw Plugin의 테스트 유틸리티, 패턴 및 린트 강제 적용에 대한 참조입니다.

테스트 유틸리티

이 테스트 헬퍼 하위 경로는 OpenClaw 자체 번들 Plugin 테스트를 위한 리포지토리 로컬 소스 진입점입니다. 타사 Plugin을 위한 패키지 export가 아닙니다.

Plugin API mock import: openclaw/plugin-sdk/plugin-test-api

Agent runtime contract import: openclaw/plugin-sdk/agent-runtime-test-contracts

Channel contract import: openclaw/plugin-sdk/channel-contract-testing

Channel test helper import: openclaw/plugin-sdk/channel-test-helpers

Channel target test import: openclaw/plugin-sdk/channel-target-testing

Plugin contract import: openclaw/plugin-sdk/plugin-test-contracts

Plugin runtime test import: openclaw/plugin-sdk/plugin-test-runtime

Provider contract import: openclaw/plugin-sdk/provider-test-contracts

Provider HTTP mock import: openclaw/plugin-sdk/provider-http-test-mocks

Environment/network test import: openclaw/plugin-sdk/test-env

Generic fixture import: openclaw/plugin-sdk/test-fixtures

Node builtin mock import: openclaw/plugin-sdk/test-node-mocks

새 Plugin 테스트에는 아래의 집중된 하위 경로를 선호하세요. 광범위한 openclaw/plugin-sdk/testing 배럴은 레거시 호환성 전용입니다. 리포지토리 가드레일은 plugin-sdk/testing 및 plugin-sdk/test-utils에서 새 실제 import를 거부합니다. 이 이름들은 호환성 기록 테스트를 위한 폐기 예정 호환성 표면으로만 남아 있습니다.

   shouldAckReaction,  removeAckReactionAfterReply,} from "openclaw/plugin-sdk/channel-feedback";             bundledPluginRoot,  createCliRuntimeCapture,  typedCases,} from "openclaw/plugin-sdk/test-fixtures"; 

사용 가능한 export

번들 Plugin 계약 스위트도 테스트 전용 registry, manifest, public-artifact, runtime fixture 헬퍼를 위해 SDK 테스트 하위 경로를 사용합니다. 번들 OpenClaw 인벤토리에 의존하는 코어 전용 스위트는 src/plugins/contracts 아래에 둡니다. 새 확장 테스트는 넓은 plugin-sdk/testing 호환성 barrel, repo src/** 파일, repo test/helpers/* 브리지를 직접 가져오는 대신 plugin-sdk/plugin-test-api, plugin-sdk/channel-contract-testing, plugin-sdk/agent-runtime-test-contracts, plugin-sdk/channel-test-helpers, plugin-sdk/plugin-test-contracts, plugin-sdk/plugin-test-runtime, plugin-sdk/provider-test-contracts, plugin-sdk/provider-http-test-mocks, plugin-sdk/test-env, plugin-sdk/test-fixtures 같은 문서화된 집중 SDK 하위 경로에 둡니다.

타입

집중 테스트 하위 경로는 테스트 파일에서 유용한 타입도 다시 내보냅니다.

   ChannelAccountSnapshot,  ChannelGatewayContext,} from "openclaw/plugin-sdk/channel-contract";  

테스트 대상 확인

채널 대상 확인을 위한 표준 오류 케이스를 추가하려면 installCommonResolveTargetErrorCases를 사용합니다.

  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 mock을 register(api)에 전달하는 단위 테스트는 OpenClaw의 로더 승인 게이트를 실행하지 않습니다. Plugin이 의존하는 각 등록 표면마다, 특히 hook과 memory 같은 독점 capability에는 로더 기반 smoke test를 하나 이상 추가하세요.

필수 메타데이터가 누락되었거나 Plugin이 소유하지 않은 capability API를 호출하면 실제 로더는 Plugin 등록에 실패합니다. 예를 들어 api.registerHook(...)에는 hook 이름이 필요하고, api.registerMemoryCapability(...)에는 Plugin manifest 또는 내보낸 엔트리가 kind: "memory"를 선언해야 합니다.

runtime config 접근 테스트

번들 채널 Plugin을 테스트할 때는 openclaw/plugin-sdk/channel-test-helpers의 공유 Plugin runtime mock을 선호하세요. deprecated된 runtime.config.loadConfig() 및 runtime.config.writeConfigFile(...) mock은 기본적으로 throw하므로 테스트가 호환성 API의 새 사용을 잡아낼 수 있습니다. 테스트가 레거시 호환성 동작을 명시적으로 다루는 경우에만 해당 mock을 override하세요.

채널 Plugin 단위 테스트

 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");  });});

provider Plugin 단위 테스트

 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);  });});

Plugin runtime mock 처리

createPluginRuntimeStore를 사용하는 코드의 경우 테스트에서 runtime을 mock 처리합니다.

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "test runtime not set",}); // In test setupconst 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 testsstore.clearRuntime();

인스턴스별 stub으로 테스트

prototype 변경보다 인스턴스별 stub을 선호하세요.

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

계약 테스트(repo 내부 Plugin)

번들 Plugin에는 등록 소유권을 검증하는 계약 테스트가 있습니다.

pnpm test -- src/plugins/contracts/

이 테스트들은 다음을 assert합니다.

• 어떤 Plugin이 어떤 provider를 등록하는지
• 어떤 Plugin이 어떤 speech provider를 등록하는지
• 등록 형태의 정확성
• runtime 계약 준수

범위 지정 테스트 실행

특정 Plugin의 경우:

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

계약 테스트만 실행하는 경우:

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

lint 강제(repo 내부 Plugin)

repo 내부 Plugin에는 pnpm check가 세 가지 규칙을 강제합니다.

1. monolithic root import 금지 -- openclaw/plugin-sdk root barrel은 거부됩니다
2. 직접 src/ import 금지 -- Plugin은 ../../src/를 직접 가져올 수 없습니다
3. self-import 금지 -- Plugin은 자신의 plugin-sdk/<name> 하위 경로를 가져올 수 없습니다

외부 Plugin에는 이 lint 규칙이 적용되지 않지만, 같은 패턴을 따르는 것을 권장합니다.

테스트 구성

OpenClaw는 V8 coverage threshold와 함께 Vitest를 사용합니다. Plugin 테스트의 경우:

# Run all testspnpm test # Run specific plugin testspnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts # Run with a specific test name filterpnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account" # Run with coveragepnpm test:coverage

로컬 실행이 메모리 압박을 일으키는 경우:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

관련 문서

• SDK 개요 -- import 규칙
• SDK 채널 Plugin -- 채널 Plugin 인터페이스
• SDK provider Plugin -- provider Plugin hook
• Plugin 빌드 -- 시작 가이드