Passer au contenu principal
Référence pour les utilitaires, les modèles et l’application des règles de lint pour les plugins OpenClaw.
Vous cherchez des exemples de tests ? Les guides pratiques incluent des exemples de tests détaillés : Tests de plugins de canal et Tests de plugins de fournisseur.

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é.
import {
  shouldAckReaction,
  removeAckReactionAfterReply,
} from "openclaw/plugin-sdk/channel-feedback";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";
import { AUTH_PROFILE_RUNTIME_CONTRACT } from "openclaw/plugin-sdk/agent-runtime-test-contracts";
import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing";
import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers";
import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts";
import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime";
import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts";
import { getProviderHttpMocks } from "openclaw/plugin-sdk/provider-http-test-mocks";
import { withEnv, withFetchPreconnect, withServer } from "openclaw/plugin-sdk/test-env";
import {
  bundledPluginRoot,
  createCliRuntimeCapture,
  typedCases,
} from "openclaw/plugin-sdk/test-fixtures";
import { mockNodeBuiltinModule } from "openclaw/plugin-sdk/test-node-mocks";

Exports disponibles

ExportObjectif
createTestPluginApiCréer un mock minimal de l’API Plugin pour les tests unitaires d’enregistrement direct. Importer depuis plugin-sdk/plugin-test-api
AUTH_PROFILE_RUNTIME_CONTRACTFixture de contrat de profil d’authentification partagée pour les adaptateurs d’exécution d’agent natifs. Importer depuis plugin-sdk/agent-runtime-test-contracts
DELIVERY_NO_REPLY_RUNTIME_CONTRACTFixture de contrat de suppression de livraison partagée pour les adaptateurs d’exécution d’agent natifs. Importer depuis plugin-sdk/agent-runtime-test-contracts
OUTCOME_FALLBACK_RUNTIME_CONTRACTFixture de contrat de classification de fallback partagée pour les adaptateurs d’exécution d’agent natifs. Importer depuis plugin-sdk/agent-runtime-test-contracts
createParameterFreeToolCréer des fixtures de schéma d’outil dynamique pour les tests de contrat d’exécution native. Importer depuis plugin-sdk/agent-runtime-test-contracts
expectChannelInboundContextContractVérifier la forme du contexte entrant de canal. Importer depuis plugin-sdk/channel-contract-testing
installChannelOutboundPayloadContractSuiteInstaller les cas de contrat de charge utile sortante de canal. Importer depuis plugin-sdk/channel-contract-testing
createStartAccountContextCréer des contextes de cycle de vie de compte de canal. Importer depuis plugin-sdk/channel-test-helpers
installChannelActionsContractSuiteInstaller les cas de contrat génériques d’action de message de canal. Importer depuis plugin-sdk/channel-test-helpers
installChannelSetupContractSuiteInstaller les cas de contrat génériques de configuration de canal. Importer depuis plugin-sdk/channel-test-helpers
installChannelStatusContractSuiteInstaller les cas de contrat génériques de statut de canal. Importer depuis plugin-sdk/channel-test-helpers
expectDirectoryIdsVérifier les ids de répertoire de canal depuis une fonction de liste de répertoires. Importer depuis plugin-sdk/channel-test-helpers
assertBundledChannelEntriesVérifier que les points d’entrée de canal groupés exposent le contrat public attendu. Importer depuis plugin-sdk/channel-test-helpers
formatEnvelopeTimestampFormater des horodatages d’enveloppe déterministes. Importer depuis plugin-sdk/channel-test-helpers
expectPairingReplyTextVérifier le texte de réponse d’appairage de canal et en extraire le code. Importer depuis plugin-sdk/channel-test-helpers
describePluginRegistrationContractInstaller les vérifications du contrat d’enregistrement de Plugin. Importer depuis plugin-sdk/plugin-test-contracts
registerSingleProviderPluginEnregistrer un Plugin fournisseur dans les tests smoke du chargeur. Importer depuis plugin-sdk/plugin-test-runtime
registerProviderPluginCapturer tous les types de fournisseurs depuis un Plugin. Importer depuis plugin-sdk/plugin-test-runtime
registerProviderPluginsCapturer les enregistrements de fournisseurs sur plusieurs Plugins. Importer depuis plugin-sdk/plugin-test-runtime
requireRegisteredProviderVérifier qu’une collection de fournisseurs contient un id. Importer depuis plugin-sdk/plugin-test-runtime
createRuntimeEnvCréer un environnement d’exécution CLI/Plugin mocké. Importer depuis plugin-sdk/plugin-test-runtime
createPluginRuntimeMockCréer une surface d’exécution de Plugin mockée. Importer depuis plugin-sdk/plugin-test-runtime
createPluginSetupWizardStatusCréer des assistants de statut de configuration pour les Plugins de canal. Importer depuis plugin-sdk/plugin-test-runtime
describeOpenAIProviderRuntimeContractInstaller les vérifications de contrat d’exécution de famille de fournisseurs. Importer depuis plugin-sdk/provider-test-contracts
expectPassthroughReplayPolicyVérifier que les politiques de relecture fournisseur transmettent les outils et métadonnées détenus par le fournisseur. Importer depuis plugin-sdk/provider-test-contracts
runRealtimeSttLiveTestExécuter un test fournisseur STT temps réel en direct avec des fixtures audio partagées. Importer depuis plugin-sdk/provider-test-contracts
normalizeTranscriptForMatchNormaliser la sortie de transcription en direct avant les assertions approximatives. Importer depuis plugin-sdk/provider-test-contracts
expectExplicitVideoGenerationCapabilitiesVérifier que les fournisseurs vidéo déclarent des capacités explicites de mode de génération. Importer depuis plugin-sdk/provider-test-contracts
expectExplicitMusicGenerationCapabilitiesVérifier que les fournisseurs musicaux déclarent des capacités explicites de génération/modification. Importer depuis plugin-sdk/provider-test-contracts
mockSuccessfulDashscopeVideoTaskInstaller une réponse de tâche vidéo réussie compatible DashScope. Importer depuis plugin-sdk/provider-test-contracts
getProviderHttpMocksAccéder aux mocks Vitest HTTP/auth de fournisseur avec opt-in. Importer depuis plugin-sdk/provider-http-test-mocks
installProviderHttpMockCleanupRéinitialiser les mocks HTTP/auth de fournisseur après chaque test. Importer depuis plugin-sdk/provider-http-test-mocks
installCommonResolveTargetErrorCasesCas de test partagés pour la gestion des erreurs de résolution de cible. Importer depuis plugin-sdk/channel-target-testing
shouldAckReactionVérifier si un canal doit ajouter une réaction d’accusé de réception. Importer depuis plugin-sdk/channel-feedback
removeAckReactionAfterReplyRetirer la réaction d’accusé de réception après la livraison de la réponse. Importer depuis plugin-sdk/channel-feedback
createTestRegistryCréer une fixture de registre de Plugin de canal. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers
createEmptyPluginRegistryCréer une fixture de registre de Plugin vide. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers
setActivePluginRegistryInstaller une fixture de registre pour les tests d’exécution de Plugin. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers
createRequestCaptureJsonFetchCapturer les requêtes fetch JSON dans les tests d’assistants média. Importer depuis plugin-sdk/test-env
withServerExécuter des tests contre un serveur HTTP local jetable. Importer depuis plugin-sdk/test-env
createMockIncomingRequestCréer un objet minimal de requête HTTP entrante. Importer depuis plugin-sdk/test-env
withFetchPreconnectExécuter les tests fetch avec les hooks de préconnexion installés. Importer depuis plugin-sdk/test-env
withEnv / withEnvAsyncCorriger temporairement les variables d’environnement. Importer depuis plugin-sdk/test-env
createTempHomeEnv / withTempHome / withTempDirCréer des fixtures de test de système de fichiers isolées. Importer depuis plugin-sdk/test-env
createMockServerResponseCréer un mock minimal de réponse de serveur HTTP. Importer depuis plugin-sdk/test-env
createCliRuntimeCaptureCapturer la sortie d’exécution CLI dans les tests. Importer depuis plugin-sdk/test-fixtures
importFreshModuleImporter un module ESM avec un jeton de requête neuf pour contourner le cache des modules. Importer depuis plugin-sdk/test-fixtures
bundledPluginRoot / bundledPluginFileRésoudre les chemins de fixtures source ou dist de Plugin groupé. Importer depuis plugin-sdk/test-fixtures
mockNodeBuiltinModuleInstaller des mocks Vitest étroits de modules intégrés Node. Importer depuis plugin-sdk/test-node-mocks
createSandboxTestContextCréer des contextes de test de bac à sable. Importer depuis plugin-sdk/test-fixtures
writeSkillÉcrire des fixtures de skill. Importer depuis plugin-sdk/test-fixtures
makeAgentAssistantMessageCréer des fixtures de messages de transcription d’agent. Importer depuis plugin-sdk/test-fixtures
peekSystemEvents / resetSystemEventsForTestInspecter et réinitialiser les fixtures d’événements système. Importer depuis plugin-sdk/test-fixtures
sanitizeTerminalTextNettoyer la sortie de terminal pour les assertions. Importer depuis plugin-sdk/test-fixtures
countLines / hasBalancedFencesVérifier la forme de la sortie de découpage. Importer depuis plugin-sdk/test-fixtures
runProviderCatalogExécuter un hook de catalogue de fournisseurs avec les dépendances de test
resolveProviderWizardOptionsRésoudre les choix de l’assistant de configuration de fournisseur dans les tests de contrat
resolveProviderModelPickerEntriesRésoudre les entrées du sélecteur de modèle de fournisseur dans les tests de contrat
buildProviderPluginMethodChoiceCréer des ids de choix d’assistant fournisseur pour les assertions
setProviderWizardProvidersResolverForTestInjecter les fournisseurs de l’assistant de fournisseur pour les tests isolés
createProviderUsageFetchConstruire des fixtures de récupération d’utilisation des fournisseurs
useFrozenTime / useRealTimeFiger et restaurer les timers pour les tests sensibles au temps. Importer depuis plugin-sdk/test-env
createTestWizardPrompterConstruire un prompteur d’assistant de configuration simulé
createRuntimeTaskFlowCréer un état TaskFlow d’exécution isolé
typedCasesPréserver les types littéraux pour les tests pilotés par table. Importer depuis plugin-sdk/test-fixtures
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 :
import type {
  ChannelAccountSnapshot,
  ChannelGatewayContext,
} from "openclaw/plugin-sdk/channel-contract";
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
import type { MockFn, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/plugin-test-runtime";

Résolution de cible de test

Utilisez installCommonResolveTargetErrorCases pour ajouter les cas d’erreur standard de résolution de cible de canal :
import { describe } from "vitest";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";

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

import { describe, it, expect, vi } from "vitest";

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

import { describe, it, expect } from "vitest";

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 :
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "test-plugin",
  errorMessage: "test runtime not set",
});

// In test setup
const 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 tests
store.clearRuntime();

Tester avec des stubs par instance

Préférez les stubs par instance à la mutation de prototype :
// Preferred: per-instance stub
const 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.ts
pnpm test -- src/plugins/contracts/auth-choice.contract.test.ts
pnpm 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 tests
pnpm test

# Run specific plugin tests
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts

# Run with a specific test name filter
pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"

# Run with coverage
pnpm test:coverage
Si les exécutions locales provoquent une pression mémoire :
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Connexe