Tests de Plugin

Référence pour les utilitaires de test, les modèles et l’application lint pour les plugins OpenClaw.

Utilitaires de test

Ces sous-chemins d’assistants de test sont des points d’entrée de source locaux au dépôt pour les tests des plugins intégrés d’OpenClaw. Ce ne sont pas des exports de package pour les plugins tiers.

Import de mock d’API Plugin : openclaw/plugin-sdk/plugin-test-api

Import de contrat d’exécution d’agent : openclaw/plugin-sdk/agent-runtime-test-contracts

Import de contrat de canal : openclaw/plugin-sdk/channel-contract-testing

Import d’assistant de test de canal : openclaw/plugin-sdk/channel-test-helpers

Import de test de cible de canal : openclaw/plugin-sdk/channel-target-testing

Import de contrat Plugin : openclaw/plugin-sdk/plugin-test-contracts

Import de test d’exécution Plugin : openclaw/plugin-sdk/plugin-test-runtime

Import de contrat fournisseur : openclaw/plugin-sdk/provider-test-contracts

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

Import de test d’environnement/réseau : openclaw/plugin-sdk/test-env

Import de fixture générique : openclaw/plugin-sdk/test-fixtures

Import de mock intégré Node : openclaw/plugin-sdk/test-node-mocks

Préférez les sous-chemins ciblés ci-dessous pour les nouveaux tests de plugins. Le barrel large openclaw/plugin-sdk/testing sert uniquement à la compatibilité héritée. Les garde-fous du dépôt rejettent les nouveaux imports réels depuis plugin-sdk/testing et plugin-sdk/test-utils ; ces noms ne restent que comme surfaces de compatibilité obsolètes pour les tests d’enregistrements de compatibilité.

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

Exports disponibles

Les suites de contrats des plugins groupés utilisent également des sous-chemins de test du SDK pour les helpers de registre, manifeste, artefacts publics et fixtures d'exécution réservés aux tests. Les suites propres au cœur qui dépendent de l'inventaire OpenClaw groupé restent sous src/plugins/contracts. Conservez les nouveaux tests d'extension sur un sous-chemin SDK ciblé et documenté comme 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 ou plugin-sdk/test-fixtures, plutôt que d'importer directement le barrel de compatibilité large plugin-sdk/testing, les fichiers src/** du dépôt, ou les passerelles test/helpers/* du dépôt.

Types

Les sous-chemins de test ciblés réexportent aussi des types utiles dans les fichiers de test :

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

Résolution des cibles de test

Utilisez installCommonResolveTargetErrorCases pour ajouter les cas d'erreur standard de résolution des cibles de canal :

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

Modèles de test

Tester les contrats d'enregistrement

Les tests unitaires qui passent un mock api écrit à la main à register(api) n'exercent pas les portes d'acceptation du chargeur d'OpenClaw. Ajoutez au moins un test de fumée adossé au chargeur pour chaque surface d'enregistrement dont votre plugin dépend, en particulier les hooks et les capacités exclusives comme la mémoire.

Le vrai chargeur fait échouer l'enregistrement du plugin lorsque des métadonnées requises sont manquantes ou qu'un plugin appelle une API de capacité qu'il ne possède pas. Par exemple, api.registerHook(...) exige un nom de hook, et api.registerMemoryCapability(...) exige que le manifeste du plugin ou l'entrée exportée déclare kind: "memory".

Tester l'accès à la configuration d'exécution

Préférez le mock d'exécution de plugin partagé depuis openclaw/plugin-sdk/channel-test-helpers lors du test de plugins de canal groupés. Ses mocks obsolètes runtime.config.loadConfig() et runtime.config.writeConfigFile(...) lèvent une erreur par défaut afin que les tests détectent toute nouvelle utilisation des API de compatibilité. Ne remplacez ces mocks que lorsque le test couvre explicitement le comportement de compatibilité hérité.

Test unitaire d'un plugin de canal

 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 unitaire d'un plugin de fournisseur

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

Mocker l'exécution du plugin

Pour le code qui utilise createPluginRuntimeStore, mockez l'exécution dans les 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();

Tester avec des stubs par instance

Préférez les stubs par instance à la mutation de prototype :

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

Tests de contrat (plugins dans le dépôt)

Les plugins groupés disposent de tests de contrat qui vérifient la propriété des enregistrements :

pnpm test -- src/plugins/contracts/

Ces tests vérifient :

• Quels plugins enregistrent quels fournisseurs
• Quels plugins enregistrent quels fournisseurs vocaux
• L'exactitude de la forme d'enregistrement
• La conformité du contrat d'exécution

Exécuter des tests limités à un périmètre

Pour un plugin spécifique :

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

Pour les tests de contrat uniquement :

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

Application par lint (plugins dans le dépôt)

Trois règles sont appliquées par pnpm check pour les plugins dans le dépôt :

1. Aucune importation racine monolithique -- le barrel racine openclaw/plugin-sdk est rejeté
2. Aucune importation directe depuis src/ -- les plugins ne peuvent pas importer directement ../../src/
3. Aucune auto-importation -- les plugins ne peuvent pas importer leur propre sous-chemin plugin-sdk/<name>

Les plugins externes ne sont pas soumis à ces règles de lint, mais il est recommandé de suivre les mêmes modèles.

Configuration de test

OpenClaw utilise Vitest avec des seuils de couverture V8. Pour les tests de plugins :

# 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

Si les exécutions locales provoquent une pression mémoire :

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Liens associés

• Vue d'ensemble du SDK -- conventions d'importation
• Plugins de canal SDK -- interface des plugins de canal
• Plugins de fournisseur SDK -- hooks des plugins de fournisseur
• Créer des plugins -- guide de prise en main