Plugin testen

Referentie voor testhulpprogramma's, patronen en lint-afdwinging voor OpenClaw-plugins.

Testhulpprogramma's

Deze subpaden voor testhelpers zijn repo-lokale broninvoerpunten voor OpenClaw's eigen gebundelde plugintests. Het zijn geen package-exports voor plugins van derden.

Mockimport voor Plugin-API: openclaw/plugin-sdk/plugin-test-api

Import voor agentruntimecontract: openclaw/plugin-sdk/agent-runtime-test-contracts

Import voor kanaalcontract: openclaw/plugin-sdk/channel-contract-testing

Import voor kanaaltesthelper: openclaw/plugin-sdk/channel-test-helpers

Import voor kanaaldoeltest: openclaw/plugin-sdk/channel-target-testing

Import voor Plugin-contract: openclaw/plugin-sdk/plugin-test-contracts

Import voor Plugin-runtimetest: openclaw/plugin-sdk/plugin-test-runtime

Import voor providercontract: openclaw/plugin-sdk/provider-test-contracts

Mockimport voor provider-HTTP: openclaw/plugin-sdk/provider-http-test-mocks

Import voor omgevings-/netwerktest: openclaw/plugin-sdk/test-env

Import voor generieke fixture: openclaw/plugin-sdk/test-fixtures

Mockimport voor ingebouwde Node-module: openclaw/plugin-sdk/test-node-mocks

Geef voor nieuwe plugintests de voorkeur aan de gerichte subpaden hieronder. Het brede barrelbestand openclaw/plugin-sdk/testing is alleen bedoeld voor verouderde compatibiliteit. Repo-guardrails weigeren nieuwe echte imports uit plugin-sdk/testing en plugin-sdk/test-utils; die namen blijven alleen bestaan als verouderde compatibiliteitsoppervlakken voor compatibiliteitsrecordtests.

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

Beschikbare exports

Gebundelde Plugin-contractsuites gebruiken ook SDK-testsubpaden voor helpers voor register-, manifest-, openbaar-artifact- en runtime-fixtures die alleen voor tests zijn. Suites die alleen voor core zijn en afhankelijk zijn van de gebundelde OpenClaw-inventaris blijven onder src/plugins/contracts. Houd nieuwe extensietests op een gedocumenteerd, gericht SDK-subpad zoals 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, of plugin-sdk/test-fixtures in plaats van rechtstreeks de brede compatibiliteitsbarrel plugin-sdk/testing, repo-src/**-bestanden, of repo-test/helpers/*-bridges te importeren.

Typen

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

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

Resolutie van testdoelen

Gebruik installCommonResolveTargetErrorCases om standaard foutgevallen toe te voegen voor resolutie 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

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

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

Runtime-configuratietoegang testen

Geef de voorkeur aan de gedeelde Plugin-runtime-mock uit openclaw/plugin-sdk/channel-test-helpers bij het testen van gebundelde kanaal-Plugins. De verouderde mocks runtime.config.loadConfig() en runtime.config.writeConfigFile(...) geven standaard een fout, zodat tests nieuw gebruik van compatibiliteits-API's onderscheppen. Overschrijf die mocks alleen wanneer de test expliciet legacy-compatibiliteitsgedrag behandelt.

Een kanaal-Plugin 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 provider-Plugin 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 Plugin-runtime mocken

Voor code die createPluginRuntimeStore gebruikt, mock je 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 prototype-mutatie:

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

Contracttests (in-repo Plugins)

Gebundelde Plugins hebben contracttests die registratie-eigenaarschap verifiëren:

pnpm test -- src/plugins/contracts/

Deze tests controleren:

• Welke Plugins welke providers registreren
• Welke Plugins welke speech-providers registreren
• Correctheid van de registratievorm
• Naleving van het runtime-contract

Scoped 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-afdwinging (in-repo Plugins)

Drie regels worden afgedwongen door pnpm check voor in-repo Plugins:

1. Geen monolithische root-imports -- de root-barrel openclaw/plugin-sdk wordt geweigerd
2. Geen directe src/-imports -- Plugins kunnen ../../src/ niet rechtstreeks importeren
3. Geen zelfimports -- Plugins kunnen hun eigen subpad plugin-sdk/<name> niet importeren

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

Testconfiguratie

OpenClaw gebruikt Vitest met V8-dekkingsdrempels. Voor 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

Als lokale runs 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 -- gids om aan de slag te gaan