Plugins testen

Referentie voor testhulpmiddelen, patronen en lintafdwinging voor OpenClaw- plugins.

Testhulpmiddelen

Deze subpaden zijn broncode-ingangspunten binnen de repository voor de eigen meegeleverde plugintests van OpenClaw. Ze worden niet gepubliceerd als package.json-exports voor plugins van derden en kunnen Vitest of andere testafhankelijkheden importeren die alleen binnen de repository beschikbaar zijn.

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

Gebruik bij voorkeur deze gerichte subpaden voor nieuwe tests van meegeleverde plugins. De brede openclaw/plugin-sdk/testing-barrel en de alias openclaw/plugin-sdk/test-utils zijn uitsluitend bedoeld voor verouderde compatibiliteit: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) weigert nieuwe imports van beide in extensietestbestanden, en beide blijven uitsluitend bestaan voor compatibiliteitsregistratietests.

Beschikbare exports

Contracttestsuites voor gebundelde plugins gebruiken deze SDK-testsubpaden ook voor helpers voor uitsluitend in tests gebruikte registers, manifesten, openbare artefacten en runtimefixtures. Suites die uitsluitend voor de kern zijn en afhankelijk zijn van de gebundelde OpenClaw-inventaris, blijven in plaats daarvan onder src/plugins/contracts.

Typen

Gerichte testsubpaden exporteren ook typen opnieuw die nuttig zijn in testbestanden:

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

Oplossing van testdoelen

Gebruik installCommonResolveTargetErrorCases om standaardfoutgevallen toe te voegen voor het oplossen van kanaaldoelen:

  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", () => {    // ...  });});

Testpatronen

Registratiecontracten testen

Unittests die een handgeschreven api-mock aan register(api) doorgeven, testen de acceptatiecontroles van de OpenClaw-lader niet. Voeg voor elk registratieoppervlak waarvan je plugin afhankelijk is minstens één door de lader ondersteunde rooktest toe, vooral voor hooks en exclusieve mogelijkheden zoals geheugen.

De echte lader laat pluginregistratie mislukken wanneer vereiste metadata ontbreekt of een plugin een mogelijkheden-API aanroept waarvan deze geen eigenaar is. Zo vereist api.registerHook(...) bijvoorbeeld een hooknaam en vereist api.registerMemoryCapability(...) dat het pluginmanifest of het geëxporteerde ingangspunt kind: "memory" declareert.

Toegang tot runtimeconfiguratie testen

Geef de voorkeur aan de gedeelde mock voor de pluginruntime uit openclaw/plugin-sdk/plugin-test-runtime. De mocks runtime.config.loadConfig() en runtime.config.writeConfigFile(...) werpen standaard een fout op, zodat tests nieuw gebruik van verouderde compatibiliteits-API's detecteren. Overschrijf die mocks alleen wanneer de test expliciet verouderd compatibiliteitsgedrag behandelt.

Een kanaalplugin unit-testen

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

Een providerplugin unit-testen

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

De pluginruntime mocken

Mock voor code die createPluginRuntimeStore gebruikt de runtime in tests:

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

Testen met stubs per instantie

Geef de voorkeur aan stubs per instantie boven prototypemutatie:

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

Contracttests (plugins in de repository)

Gebundelde plugins hebben contracttests die het eigenaarschap van registraties verifiëren:

pnpm test src/plugins/contracts/

Deze tests controleren:

• Welke plugins welke providers registreren
• Welke plugins welke spraakproviders registreren
• De correctheid van de registratiestructuur
• Naleving van het runtimecontract

Afgebakende tests uitvoeren

Voor een specifieke plugin:

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

Alleen voor contracttests:

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

Lintafdwinging (plugins in de repository)

scripts/run-additional-boundary-checks.mjs voert in CI een reeks lint:plugins:*-controles voor importgrenzen uit; elke controle kan lokaal ook afzonderlijk worden uitgevoerd:

Externe plugins vallen niet onder deze lintregels, maar het wordt aanbevolen dezelfde patronen te volgen.

Testconfiguratie

OpenClaw gebruikt Vitest 4 met informatieve V8-dekkingsrapportage. Voor plugintests:

# 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

Als lokale uitvoeringen geheugendruk veroorzaken:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Gerelateerd

• SDK-overzicht -- importconventies
• SDK-kanaalplugins -- interface voor kanaalplugins
• SDK-providerplugins -- hooks voor providerplugins
• Plugins bouwen -- introductiehandleiding