Passer au contenu principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

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é.
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 d’API de plugin pour les tests unitaires d’inscription directe. Importer depuis plugin-sdk/plugin-test-api
AUTH_PROFILE_RUNTIME_CONTRACTFixture de contrat de profil d’authentification partagé pour les adaptateurs de runtime 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 de runtime d’agent natifs. Importer depuis plugin-sdk/agent-runtime-test-contracts
OUTCOME_FALLBACK_RUNTIME_CONTRACTFixture de contrat de classification de repli partagée pour les adaptateurs de runtime 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 de runtime natif. 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 payload sortant 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’inscription de plugin. Importer depuis plugin-sdk/plugin-test-contracts
registerSingleProviderPluginInscrire un plugin de fournisseur dans les smoke tests 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 inscriptions 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 de runtime CLI/plugin mocké. Importer depuis plugin-sdk/plugin-test-runtime
createPluginSetupWizardStatusCréer des helpers de statut de configuration pour les plugins de canal. Importer depuis plugin-sdk/plugin-test-runtime
describeOpenAIProviderRuntimeContractInstaller les vérifications de contrat de runtime de famille de fournisseurs. Importer depuis plugin-sdk/provider-test-contracts
expectPassthroughReplayPolicyVérifier que les politiques de rejeu de fournisseur transmettent les outils et métadonnées appartenant au fournisseur. Importer depuis plugin-sdk/provider-test-contracts
runRealtimeSttLiveTestExécuter un test de fournisseur STT en temps réel live avec des fixtures audio partagées. Importer depuis plugin-sdk/provider-test-contracts
normalizeTranscriptForMatchNormaliser la sortie de transcription live avant les assertions floues. 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 de musique déclarent des capacités explicites de génération/édition. Importer depuis plugin-sdk/provider-test-contracts
mockSuccessfulDashscopeVideoTaskInstaller une réponse de tâche vidéo réussie compatible avec 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
removeAckReactionAfterReplySupprimer 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 plugins de canal. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers
createEmptyPluginRegistryCréer une fixture de registre de plugins vide. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers
setActivePluginRegistryInstaller une fixture de registre pour les tests de runtime de plugin. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers
createRequestCaptureJsonFetchCapturer les requêtes fetch JSON dans les tests de helper média. Importer depuis plugin-sdk/test-env
withServerExécuter des tests avec un serveur HTTP local jetable. Importer depuis plugin-sdk/test-env
createMockIncomingRequestCréer un objet de requête HTTP entrante minimal. Importer depuis plugin-sdk/test-env
withFetchPreconnectExécuter des tests fetch avec les hooks de préconnexion installés. Importer depuis plugin-sdk/test-env
withEnv / withEnvAsyncModifier 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 du runtime CLI dans les tests. Importer depuis plugin-sdk/test-fixtures
importFreshModuleImporter un module ESM avec un jeton de requête frais pour contourner le cache des modules. Importer depuis plugin-sdk/test-fixtures
bundledPluginRoot / bundledPluginFileRésoudre les chemins de fixtures de source ou de dist de plugin groupé. Importer depuis plugin-sdk/test-fixtures
mockNodeBuiltinModuleInstaller des mocks Vitest étroits pour les 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
sanitizeTerminalTextAssainir la sortie du 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 des dépendances de test
resolveProviderWizardOptionsRésoudre les choix de l’assistant de configuration du fournisseur dans les tests de contrat
resolveProviderModelPickerEntriesRésoudre les entrées du sélecteur de modèle du fournisseur dans les tests de contrat
buildProviderPluginMethodChoiceCréer des ids de choix de l’assistant de fournisseur pour les assertions
setProviderWizardProvidersResolverForTestInjecter des fournisseurs d’assistant de fournisseur pour des tests isolés
createProviderUsageFetchCréer des fixtures de récupération de l’utilisation du fournisseur
useFrozenTime / useRealTimeGeler et restaurer les minuteurs pour les tests sensibles au temps. Importer depuis plugin-sdk/test-env
createTestWizardPrompterCréer un prompteur d’assistant de configuration simulé
createRuntimeTaskFlowCréer un état de flux de tâches 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 é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 :
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 des cibles de test

Utilisez installCommonResolveTargetErrorCases pour ajouter les cas d’erreur standard de résolution des cibles 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 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

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

Test unitaire d’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é 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.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. 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 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

Liens associés