Test dei Plugin

Riferimento per utilità di test, pattern e applicazione del lint per i Plugin OpenClaw.

Utilità di test

Questi sottopercorsi di helper di test sono entrypoint sorgente locali del repo per i test dei Plugin inclusi di OpenClaw. Non sono esportazioni del pacchetto per Plugin di terze parti e possono importare Vitest o altre dipendenze di test solo del repo.

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

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

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

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

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

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

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

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

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

Import del test ambiente/rete: openclaw/plugin-sdk/test-env

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

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

All'interno del repo OpenClaw, per i nuovi test dei Plugin inclusi preferisci i sottopercorsi mirati qui sotto. Il barrel ampio openclaw/plugin-sdk/testing è solo per compatibilità legacy. Le protezioni del repo rifiutano nuovi import reali da plugin-sdk/testing e plugin-sdk/test-utils; quei nomi rimangono 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"; 

Esportazioni disponibili

Le suite di contratto dei Plugin integrati usano anche sottopercorsi di test dell'SDK per helper di fixture solo per test per registro, manifesto, artefatti pubblici e runtime. Le suite solo core che dipendono dall'inventario OpenClaw integrato restano sotto src/plugins/contracts. Mantieni i nuovi test delle estensioni su un sottopercorso SDK focalizzato 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 repository o i bridge test/helpers/* del repository.

Tipi

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

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

Test della risoluzione dei target

Usa installCommonResolveTargetErrorCases per aggiungere casi di errore standard per la risoluzione dei target di 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 un mock api scritto a mano a register(api) 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, soprattutto hook e capacità esclusive come la memoria.

Il loader reale fa fallire la registrazione del Plugin quando mancano metadati obbligatori o un Plugin chiama un'API di capacità che non possiede. Per esempio, api.registerHook(...) richiede un nome di hook e api.registerMemoryCapability(...) richiede che il manifesto 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/plugin-test-runtime. 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 quei 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, crea un 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 stub per istanza invece della 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 repository)

I Plugin integrati 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
• La correttezza della forma della registrazione
• La 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 repository)

Tre regole sono applicate da pnpm check per i Plugin nel repository:

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

I Plugin esterni non sono soggetti a queste regole di lint, ma si consiglia di 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 importazione
• Plugin di canale SDK -- interfaccia dei Plugin di canale
• Plugin provider SDK -- hook dei Plugin provider
• Creazione di Plugin -- guida introduttiva