Test dei Plugin

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

Utility di test

Questi sottopercorsi sono punti di ingresso del codice sorgente locali al repository per i test dei Plugin inclusi in OpenClaw. Non sono esportazioni package.json pubblicate per Plugin di terze parti e possono importare Vitest o altre dipendenze di test disponibili solo nel repository.

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

Usare questi sottopercorsi specifici per i test dei Plugin inclusi. Il precedente barrel openclaw/plugin-sdk/testing era locale al repository, escluso dai pacchetti distribuiti ed è stato rimosso. L'alias legacy openclaw/plugin-sdk/test-utils rimane locale al repository; pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) rifiuta le nuove importazioni di tale alias nei test delle estensioni.

Esportazioni disponibili

Le suite di contratti dei plugin inclusi utilizzano inoltre questi sottopercorsi di test dell'SDK per gli helper di fixture di registro, manifest, artefatti pubblici e runtime riservati ai test. Le suite riservate al core che dipendono dall'inventario OpenClaw incluso rimangono invece in src/plugins/contracts.

Tipi

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

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

Test della risoluzione della destinazione

Usare installCommonResolveTargetErrorCases per aggiungere i casi di errore standard per la risoluzione della destinazione del canale:

  describe("risoluzione della destinazione di my-channel", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Logica di risoluzione della destinazione del canale      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Aggiungere casi di test specifici del canale  it("dovrebbe risolvere le destinazioni @username", () => {    // ...  });});

Modelli di test

Test dei contratti di registrazione

Gli unit test che passano un mock api scritto manualmente a register(api) non esercitano i controlli di accettazione del loader di OpenClaw. Aggiungere almeno uno smoke test basato sul loader per ogni superficie di registrazione da cui dipende il Plugin, in particolare gli hook e le funzionalità esclusive come la memoria.

Il loader reale non riesce a registrare il Plugin quando mancano i metadati obbligatori o un Plugin chiama un'API di una funzionalità che non gli appartiene. Ad esempio, api.registerHook(...) richiede un nome di hook e api.registerMemoryCapability(...) richiede che il manifesto del Plugin o la voce esportata dichiari kind: "memory".

Test dell'accesso alla configurazione in fase di esecuzione

Preferire il mock condiviso del runtime del Plugin fornito da openclaw/plugin-sdk/plugin-test-runtime. I relativi mock runtime.config.loadConfig() e runtime.config.writeConfigFile(...) generano un errore per impostazione predefinita, affinché i test rilevino nuovi utilizzi delle API di compatibilità deprecate. Sovrascrivere questi mock solo quando il test verifica esplicitamente il comportamento di compatibilità legacy.

Unit test di un Plugin di canale

 describe("Plugin my-channel", () => {  it("dovrebbe risolvere l'account dalla configurazione", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("dovrebbe esaminare l'account senza materializzare i segreti", () => {    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");    // Nessun valore del token esposto    expect(inspection).not.toHaveProperty("token");  });});

Unit test di un Plugin provider

 describe("Plugin my-provider", () => {  it("dovrebbe risolvere i modelli dinamici", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... contesto    });     expect(model.id).toBe("custom-model-v2");    expect(model.provider).toBe("my-provider");    expect(model.api).toBe("openai-completions");  });   it("dovrebbe restituire il catalogo quando è disponibile una chiave API", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... contesto    });     expect(result?.provider?.models).toHaveLength(2);  });});

Simulazione del runtime del Plugin

Per il codice che usa createPluginRuntimeStore, simulare il runtime nei test:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "runtime di test non impostato",}); // Nella configurazione del testconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... altri mock  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... altri namespace} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Dopo i teststore.clearRuntime();

Test con stub per istanza

Preferire gli stub per istanza alla modifica del prototipo:

// Preferito: stub per istanzaconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Da evitare: modifica del prototipo// MyChannelClient.prototype.sendMessage = vi.fn();

Test dei contratti (Plugin nel repository)

I Plugin inclusi dispongono di test dei contratti che verificano la titolarità della registrazione:

pnpm test src/plugins/contracts/

Questi test verificano:

• Quali Plugin registrano quali provider
• Quali Plugin registrano quali provider vocali
• Correttezza della struttura di registrazione
• Conformità al contratto del runtime

Esecuzione di test circoscritti

Per un Plugin specifico:

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

Solo per i test dei contratti:

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 delle regole di lint (Plugin nel repository)

scripts/run-additional-boundary-checks.mjs esegue in CI una serie di controlli lint:plugins:* sui confini delle importazioni; ciascuno può essere eseguito anche autonomamente in locale:

I Plugin esterni non sono soggetti a queste regole di lint, ma è consigliabile seguire gli stessi modelli.

Configurazione dei test

OpenClaw usa Vitest 4 con report informativi sulla copertura V8. Per i test dei Plugin:

# Eseguire tutti i testpnpm test # Eseguire i test di un Plugin specificopnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Eseguire con un filtro specifico sul nome del testpnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Eseguire con la coperturapnpm test:coverage

Se le esecuzioni locali causano un'elevata pressione sulla memoria:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Risorse correlate

• Panoramica dell'SDK -- convenzioni di importazione
• Plugin di canale dell'SDK -- interfaccia dei Plugin di canale
• Plugin provider dell'SDK -- hook dei Plugin provider
• Creazione di Plugin -- guida introduttiva