Plugin testen

Naslaginformatie voor testhulpprogramma's, patronen en lint-handhaving voor OpenClaw- plugins.

Testhulpprogramma's

Deze subpaden zijn lokale broningangen van de repository voor de eigen gebundelde plugintests van OpenClaw. Het zijn geen gepubliceerde package.json-exports voor plugins van derden en ze kunnen Vitest of andere testafhankelijkheden importeren die alleen in de repository beschikbaar zijn.

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

Gebruik deze gerichte subpaden voor tests van gebundelde plugins. De voormalige openclaw/plugin-sdk/testing-barrel was lokaal in de repository, uitgesloten van uitgebrachte pakketten en is verwijderd. De voormalige openclaw/plugin-sdk/test-utils- alias is tegelijk verwijderd. pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) houdt extensietests op de bovenstaande gerichte testsubpaden.

Beschikbare exports

Gebundelde Plugin-contractsuites gebruiken deze SDK-testsubpaden ook voor testhelpers voor alleen-tests-registers, manifesten, openbare artefacten en runtime-fixtures. Suites die uitsluitend voor core 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("oplossing van my-channel-doelen", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // De logica voor het oplossen van doelen van je kanaal      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Kanaalspecifieke testgevallen toevoegen  it("moet @username-doelen oplossen", () => {    // ...  });});

Testpatronen

Registratiecontracten testen

Unittests die een handgeschreven mock van api doorgeven aan register(api), oefenen de acceptatiecontroles van de OpenClaw-loader niet uit. Voeg ten minste één door de loader ondersteunde rooktest toe voor elk registratieoppervlak waarvan je Plugin afhankelijk is, met name hooks en exclusieve mogelijkheden zoals geheugen.

De echte loader laat de Plugin-registratie mislukken wanneer vereiste metadata ontbreekt of een Plugin een capability-API aanroept waarvan deze niet de eigenaar is. Bijvoorbeeld: api.registerHook(...) vereist een hooknaam en api.registerMemoryCapability(...) vereist dat het Plugin-manifest of de geëxporteerde entry kind: "memory" declareert.

Toegang tot runtimeconfiguratie testen

Geef de voorkeur aan de gedeelde mock voor de Plugin-runtime uit openclaw/plugin-sdk/plugin-test-runtime. De helpers voor runtimeconfiguratie modelleren de huidige snapshot- en mutatie-API's.

Een kanaal-Plugin met unittests testen

 describe("my-channel-Plugin", () => {  it("moet account uit configuratie oplossen", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("moet account inspecteren zonder geheimen te materialiseren", () => {    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");    // Geen tokenwaarde blootgesteld    expect(inspection).not.toHaveProperty("token");  });});

Een provider-Plugin met unittests testen

 describe("my-provider-Plugin", () => {  it("moet dynamische modellen oplossen", () => {    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("moet catalogus retourneren wanneer een API-sleutel beschikbaar is", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... context    });     expect(result?.provider?.models).toHaveLength(2);  });});

De Plugin-runtime mocken

Voor code die createPluginRuntimeStore gebruikt, mock je de runtime in tests:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "testruntime niet ingesteld",}); // In de testconfiguratieconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... andere mocks  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... andere naamruimten} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Na de testsstore.clearRuntime();

Testen met stubs per instantie

Geef de voorkeur aan stubs per instantie boven prototypemutatie:

// Aanbevolen: stub per instantieconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Vermijd: prototypemutatie// 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
• Correctheid van de registratievorm
• 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

Lint-handhaving (Plugins in de repository)

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

Externe Plugins vallen niet onder deze lintregels, maar het volgen van dezelfde patronen wordt aanbevolen.

Testconfiguratie

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

# Alle tests uitvoerenpnpm test # Tests voor een specifieke Plugin uitvoerenpnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Uitvoeren met een filter voor een specifieke testnaampnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Uitvoeren met dekkingpnpm test:coverage

Als lokale uitvoeringen geheugendruk veroorzaken:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Gerelateerd

• SDK-overzicht -- importconventies
• SDK-kanaal-Plugins -- interface voor kanaal-Plugins
• SDK-provider-Plugins -- hooks voor provider-Plugins
• Plugins bouwen -- introductiegids