Tests des Plugins

Référence des utilitaires, modèles et règles de lint pour les tests des plugins OpenClaw.

Utilitaires de test

Ces sous-chemins sont des points d’entrée vers le code source local au dépôt pour les tests des plugins intégrés d’OpenClaw. Ils ne sont pas publiés en tant qu’exports package.json pour les plugins tiers et peuvent importer Vitest ou d’autres dépendances de test propres au dépôt.

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

Privilégiez ces sous-chemins ciblés pour les nouveaux tests de plugins intégrés. Le point d’entrée général openclaw/plugin-sdk/testing et l’alias openclaw/plugin-sdk/test-utils ne servent qu’à la compatibilité héritée : pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) rejette tout nouvel import de l’un ou l’autre dans les fichiers de test des extensions, et tous deux sont conservés uniquement pour les tests de vérification de la compatibilité.

Exports disponibles

Les suites de contrats des plugins intégrés utilisent également ces sous-chemins de test du SDK pour les utilitaires de fixtures réservés aux tests concernant le registre, le manifeste, les artefacts publics et l’environnement d’exécution. Les suites réservées au cœur qui dépendent de l’inventaire intégré d’OpenClaw restent plutôt sous src/plugins/contracts.

Types

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

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

Résolution des cibles dans les tests

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

Test des contrats d’enregistrement

Les tests unitaires qui transmettent une simulation api écrite manuellement à register(api) ne mettent pas en œuvre les contrôles d’acceptation du chargeur d’OpenClaw. Ajoutez au moins un test de bon fonctionnement reposant sur le chargeur pour chaque surface d’enregistrement dont dépend votre plugin, en particulier les hooks et les fonctionnalités exclusives telles que la mémoire.

Le véritable chargeur fait échouer l’enregistrement du plugin lorsque des métadonnées requises sont absentes ou qu’un plugin appelle une API de fonctionnalité dont il n’est pas propriétaire. Par exemple, api.registerHook(...) nécessite un nom de hook, et api.registerMemoryCapability(...) nécessite que le manifeste du plugin ou l’entrée exportée déclare kind: "memory".

Test de l’accès à la configuration de l’environnement d’exécution

Préférez la simulation partagée de l’environnement d’exécution du plugin provenant de openclaw/plugin-sdk/plugin-test-runtime. Ses simulations runtime.config.loadConfig() et runtime.config.writeConfigFile(...) lèvent une exception par défaut afin que les tests détectent toute nouvelle utilisation d’API de compatibilité obsolètes. Ne remplacez ces simulations que lorsque le test couvre explicitement un comportement de compatibilité historique.

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

Simulation de l’environnement d’exécution du plugin

Pour le code qui utilise createPluginRuntimeStore, simulez l’environnement d’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();

Tests avec des substituts propres à chaque instance

Préférez les substituts propres à chaque instance à la modification du 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 contrats (plugins du dépôt)

Les plugins intégrés disposent de tests de contrats 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
• La conformité de la structure d’enregistrement
• La conformité au contrat de l’environnement d’exécution

Exécution de tests ciblés

Pour un plugin spécifique :

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

Pour les tests de contrats 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

Contrôles du lint (plugins du dépôt)

scripts/run-additional-boundary-checks.mjs exécute dans la CI un ensemble de contrôles lint:plugins:* portant sur les limites d’importation ; chacun peut également être exécuté séparément en local :

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

Configuration des tests

OpenClaw utilise Vitest 4 avec des rapports informatifs de couverture V8. Pour les tests des 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 sur la mémoire :

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Voir aussi

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