Plugin परीक्षण

OpenClaw plugins के लिए test utilities, patterns, और lint enforcement का संदर्भ।

Test utilities

ये test-helper subpaths OpenClaw के अपने bundled plugin tests के लिए repo-local source entrypoints हैं। वे third-party plugins के लिए package exports नहीं हैं, और वे Vitest या अन्य repo-only test dependencies import कर सकते हैं।

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

OpenClaw repo के अंदर, नए bundled plugin tests के लिए नीचे दिए गए focused subpaths को प्राथमिकता दें। विस्तृत openclaw/plugin-sdk/testing barrel केवल legacy compatibility के लिए है। Repo guardrails plugin-sdk/testing और plugin-sdk/test-utils से नए वास्तविक imports को अस्वीकार करते हैं; ये नाम compatibility-record tests के लिए केवल deprecated compatibility surfaces के रूप में रहते हैं।

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

उपलब्ध exports

बंडल किए गए Plugin की कॉन्ट्रैक्ट suites भी केवल-टेस्ट रजिस्ट्री, मैनिफेस्ट, सार्वजनिक-आर्टिफैक्ट, और runtime fixture helpers के लिए SDK testing subpaths का उपयोग करती हैं। केवल-कोर suites जो बंडल किए गए OpenClaw inventory पर निर्भर हैं, src/plugins/contracts के अंतर्गत रहती हैं। नए extension tests को सीधे broad plugin-sdk/testing compatibility barrel, repo src/** files, या repo test/helpers/* bridges import करने के बजाय किसी documented focused SDK subpath जैसे 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 पर रखें।

प्रकार

Focused testing subpaths test files में उपयोगी types को भी फिर से export करते हैं:

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

Testing target resolution

Channel target resolution के लिए standard error cases जोड़ने हेतु 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", () => {    // ...  });});

Testing patterns

Registration contracts की testing

Unit tests जो register(api) को हाथ से लिखा हुआ api mock पास करते हैं, OpenClaw के loader acceptance gates को exercise नहीं करते। आपके Plugin जिस प्रत्येक registration surface पर निर्भर करता है, उसके लिए कम से कम एक loader-backed smoke test जोड़ें, खासकर hooks और memory जैसी exclusive capabilities के लिए।

जब required metadata missing हो या कोई Plugin ऐसी capability API call करे जिसकी ownership उसके पास नहीं है, तो real loader Plugin registration fail कर देता है। उदाहरण के लिए, api.registerHook(...) को hook name चाहिए, और api.registerMemoryCapability(...) के लिए Plugin manifest या exported entry में kind: "memory" declare होना चाहिए।

Runtime config access की testing

openclaw/plugin-sdk/plugin-test-runtime से shared Plugin runtime mock को प्राथमिकता दें। इसके deprecated runtime.config.loadConfig() और runtime.config.writeConfigFile(...) mocks default रूप से throw करते हैं ताकि tests compatibility APIs के नए usage पकड़ सकें। उन mocks को केवल तब override करें जब test स्पष्ट रूप से legacy compatibility behavior cover कर रहा हो।

Channel Plugin की unit testing

 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 की unit testing

 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 का उपयोग करने वाले code के लिए, tests में 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();

Per-instance stubs के साथ testing

Prototype mutation के बजाय per-instance stubs को प्राथमिकता दें:

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

Contract tests (repo के भीतर Plugin)

बंडल किए गए Plugin में contract tests होते हैं जो registration ownership verify करते हैं:

pnpm test -- src/plugins/contracts/

ये tests assert करते हैं:

• कौन-से Plugin कौन-से providers register करते हैं
• कौन-से Plugin कौन-से speech providers register करते हैं
• Registration shape correctness
• Runtime contract compliance

Scoped tests चलाना

किसी specific Plugin के लिए:

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

केवल contract tests के लिए:

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 enforcement (repo के भीतर Plugin)

Repo के भीतर Plugin के लिए pnpm check द्वारा तीन rules enforce किए जाते हैं:

1. Monolithic root imports नहीं -- openclaw/plugin-sdk root barrel reject किया जाता है
2. Direct src/ imports नहीं -- Plugin सीधे ../../src/ import नहीं कर सकते
3. Self-imports नहीं -- Plugin अपना ही plugin-sdk/<name> subpath import नहीं कर सकते

बाहरी Plugin इन lint rules के अधीन नहीं हैं, लेकिन वही patterns follow करने की सलाह दी जाती है।

Test configuration

OpenClaw V8 coverage thresholds के साथ Vitest का उपयोग करता है। Plugin tests के लिए:

# 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

यदि local runs memory pressure पैदा करते हैं:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

संबंधित

• SDK अवलोकन -- import conventions
• SDK Channel Plugins -- channel Plugin interface
• SDK Provider Plugins -- provider Plugin hooks
• Plugins बनाना -- getting started guide