Test dei Plugin

Riferimento per utilità, modelli e applicazione delle regole di lint per i Plugin di OpenClaw.

Utilità di test

Questi sottopercorsi sono punti di ingresso al codice sorgente locale del 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 riservate al repository.

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

Per i nuovi test dei Plugin inclusi, preferisci questi sottopercorsi specifici. Il barrel generico openclaw/plugin-sdk/testing e l'alias openclaw/plugin-sdk/test-utils servono solo per la compatibilità con il codice legacy: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) rifiuta le nuove importazioni di entrambi dai file di test delle estensioni, ed entrambi restano esclusivamente per i test che documentano la compatibilità.

Esportazioni disponibili

Anche le suite di contratti dei Plugin inclusi usano questi sottopercorsi di test dell'SDK per gli helper di fixture, destinati esclusivamente ai test, relativi a registro, manifest, artefatti pubblici e runtime. Le suite riservate al core che dipendono dall'inventario OpenClaw incluso rimangono invece in src/plugins/contracts.

Tipi

I sottopercorsi dedicati ai test riesportano anche tipi utili nei file di test:

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

Test della risoluzione della destinazione

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

  describe("my-channel target resolution", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Logica di risoluzione della destinazione del tuo canale      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Aggiungi casi di test specifici del canale  it("should resolve @username targets", () => {    // ...  });});

Modelli di test

Test dei contratti di registrazione

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

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

Test dell'accesso alla configurazione del runtime

Preferisci il mock condiviso del runtime del Plugin da openclaw/plugin-sdk/plugin-test-runtime. I mock runtime.config.loadConfig() e runtime.config.writeConfigFile(...) generano un'eccezione per impostazione predefinita, in modo che i test rilevino i nuovi utilizzi delle API di compatibilità deprecate. Sovrascrivi questi mock solo quando il test verifica 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");    // Nessun valore del token esposto    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",      // ... contesto    });     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" }),      // ... contesto    });     expect(result?.provider?.models).toHaveLength(2);  });});

Simulazione del runtime del Plugin

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

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "test runtime not set",}); // 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 spazi dei nomi} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Dopo i teststore.clearRuntime();

Test con stub per istanza

Preferisci 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 proprietà della registrazione:

pnpm test src/plugins/contracts/

Questi test verificano:

• Quali Plugin registrano quali provider
• Quali Plugin registrano quali provider vocali
• La correttezza della struttura di registrazione
• La 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ò anche essere eseguito autonomamente in locale:

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

Configurazione dei test

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

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

Se le esecuzioni locali causano problemi di memoria:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Argomenti correlati

• 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