Test dei Plugin

Riferimento per utility di test, pattern e applicazione del lint per i plugin di OpenClaw.

Utility di test

Questi sottopercorsi degli helper di test sono entrypoint sorgente locali al repository per i test dei plugin inclusi in OpenClaw. Non sono export del pacchetto per plugin di terze parti.

Import del mock dell'API del Plugin: openclaw/plugin-sdk/plugin-test-api

Import del contratto del runtime dell'agente: openclaw/plugin-sdk/agent-runtime-test-contracts

Import del contratto del canale: openclaw/plugin-sdk/channel-contract-testing

Import dell'helper di test del canale: openclaw/plugin-sdk/channel-test-helpers

Import del test del target del canale: openclaw/plugin-sdk/channel-target-testing

Import del contratto del Plugin: openclaw/plugin-sdk/plugin-test-contracts

Import del test del runtime del Plugin: openclaw/plugin-sdk/plugin-test-runtime

Import del contratto del provider: openclaw/plugin-sdk/provider-test-contracts

Import del mock HTTP del provider: openclaw/plugin-sdk/provider-http-test-mocks

Import dei test di ambiente/rete: openclaw/plugin-sdk/test-env

Import della fixture generica: openclaw/plugin-sdk/test-fixtures

Import del mock integrato di Node: openclaw/plugin-sdk/test-node-mocks

Preferisci i sottopercorsi mirati di seguito per i nuovi test dei plugin. Il barrel ampio openclaw/plugin-sdk/testing è solo compatibilità legacy. Le protezioni del repository rifiutano nuovi import reali da plugin-sdk/testing e plugin-sdk/test-utils; quei nomi restano solo come superfici di compatibilità deprecate per i test dei record di compatibilità.

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

Export disponibili

Le suite di contratto dei plugin in bundle usano anche i sottopercorsi di test dell’SDK per helper solo per test relativi a registry, manifest, artefatti pubblici e fixture di runtime. Le suite solo core che dipendono dall’inventario OpenClaw in bundle restano in src/plugins/contracts. Mantieni i nuovi test delle estensioni su un sottopercorso SDK mirato e documentato, come 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 o plugin-sdk/test-fixtures, invece di importare direttamente il barrel di compatibilità ampio plugin-sdk/testing, i file src/** del repo o i bridge test/helpers/* del repo.

Tipi

I sottopercorsi di test mirati riesportano anche tipi utili nei file di test:

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

Risoluzione dei target di test

Usa installCommonResolveTargetErrorCases per aggiungere casi di errore standard per la risoluzione dei target del canale:

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

Pattern di test

Test dei contratti di registrazione

I test unitari che passano a register(api) un mock api scritto a mano non esercitano i gate di accettazione del loader di OpenClaw. Aggiungi almeno uno smoke test basato sul loader per ogni superficie di registrazione da cui dipende il tuo plugin, in particolare hook e capability esclusive come la memoria.

Il loader reale fa fallire la registrazione del plugin quando mancano metadati obbligatori o quando un plugin chiama un’API di capability che non possiede. Per esempio, api.registerHook(...) richiede un nome di hook, e api.registerMemoryCapability(...) richiede che il manifest del plugin o l’entry esportata dichiari kind: "memory".

Test dell’accesso alla configurazione di runtime

Preferisci il mock condiviso del runtime del plugin da openclaw/plugin-sdk/channel-test-helpers quando testi i plugin di canale in bundle. I suoi mock deprecati runtime.config.loadConfig() e runtime.config.writeConfigFile(...) generano un errore per impostazione predefinita, così i test intercettano nuovi usi delle API di compatibilità. Sovrascrivi questi mock solo quando il test copre esplicitamente il comportamento di compatibilità legacy.

Test unitario di un plugin di canale

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

Test unitario di un plugin provider

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

Mock del runtime del plugin

Per il codice che usa createPluginRuntimeStore, esegui il mock del runtime nei test:

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

Test con stub per istanza

Preferisci gli stub per istanza alla mutazione del prototipo:

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

Test di contratto (plugin nel repo)

I plugin in bundle hanno test di contratto che verificano la proprietà della registrazione:

pnpm test -- src/plugins/contracts/

Questi test verificano:

• Quali plugin registrano quali provider
• Quali plugin registrano quali provider vocali
• Correttezza della forma della registrazione
• Conformità al contratto di runtime

Esecuzione di test con ambito limitato

Per un plugin specifico:

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

Solo per i test di contratto:

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

Applicazione del lint (plugin nel repo)

Tre regole sono applicate da pnpm check per i plugin nel repo:

1. Nessun import monolitico dalla root -- il barrel root openclaw/plugin-sdk viene rifiutato
2. Nessun import diretto da src/ -- i plugin non possono importare direttamente ../../src/
3. Nessun self-import -- i plugin non possono importare il proprio sottopercorso plugin-sdk/<name>

I plugin esterni non sono soggetti a queste regole di lint, ma è consigliato seguire gli stessi pattern.

Configurazione dei test

OpenClaw usa Vitest con soglie di copertura V8. Per i test dei 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

Se le esecuzioni locali causano pressione sulla memoria:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Correlati

• Panoramica dell’SDK -- convenzioni di import
• Plugin di canale SDK -- interfaccia dei plugin di canale
• Plugin provider SDK -- hook dei plugin provider
• Creazione di plugin -- guida introduttiva