Tests de Plugin

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

Utilitaires de test

Ces sous-chemins d’assistants de test sont des points d’entrée source locaux au dépôt pour les propres tests de plugins intégrés d’OpenClaw. Ce ne sont pas des exports de paquet pour les plugins tiers, et ils peuvent importer Vitest ou d’autres dépendances de test propres au dépôt.

Importation du mock de l’API Plugin : openclaw/plugin-sdk/plugin-test-api

Importation du contrat du runtime agent : openclaw/plugin-sdk/agent-runtime-test-contracts

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

Importation de l’assistant de test de canal : openclaw/plugin-sdk/channel-test-helpers

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

Importation du contrat de Plugin : openclaw/plugin-sdk/plugin-test-contracts

Importation du test de runtime Plugin : openclaw/plugin-sdk/plugin-test-runtime

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

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

Importation du test d’environnement/réseau : openclaw/plugin-sdk/test-env

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

Importation du mock de module intégré Node : openclaw/plugin-sdk/test-node-mocks

Dans le dépôt OpenClaw, privilégiez les sous-chemins ciblés ci-dessous pour les nouveaux tests de plugins intégrés. Le barrel général openclaw/plugin-sdk/testing est uniquement destiné à la compatibilité héritée. Les garde-fous du dépôt rejettent les nouvelles importations réelles depuis plugin-sdk/testing et plugin-sdk/test-utils ; ces noms ne subsistent 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 aussi des sous-chemins de test du SDK pour les assistants de registre, de manifeste, d'artefact public et de fixtures d'exécution réservés aux tests. Les suites uniquement liées au coeur 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é tel que 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 ponts 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 de cible de test

Utilisez installCommonResolveTargetErrorCases pour ajouter les cas d'erreur standard de résolution de cible 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 transmettent un mock api écrit à la main à register(api) n'exercent pas les garde-fous d'acceptation du chargeur d'OpenClaw. Ajoutez au moins un test de fumée 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 chargeur réel échoue à enregistrer le plugin lorsque des métadonnées requises manquent 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 partagé d'exécution de plugin provenant de openclaw/plugin-sdk/plugin-test-runtime. Ses mocks obsolètes runtime.config.loadConfig() et runtime.config.writeConfigFile(...) lèvent une erreur par défaut afin que les tests détectent tout nouvel usage des API de compatibilité. Ne remplacez ces mocks que lorsque le test couvre explicitement un comportement de compatibilité historique.

Tester unitairement 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");  });});

Tester unitairement 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é au contrat d'exécution

Exécuter des 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 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. Aucun import racine monolithique -- le barrel racine openclaw/plugin-sdk est rejeté
2. Aucun import direct depuis src/ -- les plugins ne peuvent pas importer directement ../../src/
3. Aucun auto-import -- 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 des tests

OpenClaw utilise Vitest avec des seuils de couverture V8. Pour les tests de 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

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

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Connexe

• Vue d'ensemble du SDK -- conventions d'import
• Plugins de canal SDK -- interface de plugin de canal
• Plugins de fournisseur SDK -- hooks de plugin de fournisseur
• Créer des plugins -- guide de démarrage