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 de code source locaux au dépôt pour les tests des plugins intégrés d’OpenClaw. Ce ne sont pas des exports package.json publiés pour les plugins tiers, et ils 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"; 

Utilisez ces sous-chemins ciblés pour les tests des plugins intégrés. L’ancien baril openclaw/plugin-sdk/testing, local au dépôt, était exclu des paquets distribués et a été supprimé. L’alias historique openclaw/plugin-sdk/test-utils reste local au dépôt ; pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) rejette les nouveaux imports de cet alias dans les tests d’extensions.

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 de registre, de manifeste, d’artefacts publics et d’environnement d’exécution réservés aux tests. Les suites propres au cœur qui dépendent de l’inventaire OpenClaw intégré restent sous src/plugins/contracts à la place.

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";  

Test de la résolution des cibles

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

  describe("résolution des cibles de my-channel", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Logique de résolution des cibles de votre canal      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Ajouter des cas de test propres au canal  it("doit résoudre les cibles @username", () => {    // ...  });});

Modèles de test

Test des contrats d’enregistrement

Les tests unitaires qui transmettent une simulation api écrite manuellement à register(api) ne font pas intervenir les contrôles d’acceptation du chargeur d’OpenClaw. Ajoutez au moins un test de bon fonctionnement adossé au chargeur pour chaque surface d’enregistrement dont dépend votre plugin, en particulier les hooks et les capacité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 capacité dont il n’est pas propriétaire. 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".

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

Privilégiez 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 des API de compatibilité obsolètes. Ne remplacez ces simulations que lorsque le test porte explicitement sur un comportement de compatibilité hérité.

Test unitaire d’un plugin de canal

 describe("plugin my-channel", () => {  it("doit résoudre le compte depuis la configuration", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("doit inspecter le compte sans matérialiser les 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");    // Aucune valeur de jeton exposée    expect(inspection).not.toHaveProperty("token");  });});

Test unitaire d’un plugin de fournisseur

 describe("plugin my-provider", () => {  it("doit résoudre les modèles dynamiques", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... contexte    });     expect(model.id).toBe("custom-model-v2");    expect(model.provider).toBe("my-provider");    expect(model.api).toBe("openai-completions");  });   it("doit renvoyer le catalogue lorsqu’une clé d’API est disponible", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... contexte    });     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: "environnement d’exécution de test non défini",}); // Dans la préparation du testconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... autres simulations  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... autres espaces de noms} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Après les testsstore.clearRuntime();

Tests avec des substituts propres à chaque instance

Privilégiez les substituts propres à chaque instance plutôt que la modification du prototype :

// Recommandé : substitut propre à l’instanceconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // À éviter : modification du prototype// MyChannelClient.prototype.sendMessage = vi.fn();

Tests de contrat (plugins du dépôt)

Les plugins intégré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 de synthèse vocale
• La conformité de la structure d’enregistrement
• Le respect du contrat 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 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 des règles de lint (plugins du dépôt)

scripts/run-additional-boundary-checks.mjs exécute un ensemble de contrôles lint:plugins:* des frontières d’importation dans l’intégration continue ; 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 de plugins :

# Exécuter tous les testspnpm test # Exécuter les tests d’un plugin spécifiquepnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Exécuter avec un filtre sur un nom de test spécifiquepnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Exécuter avec la couverturepnpm 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 démarrage