Référence pour les utilitaires de test, les modèles et l’application lint pour les plugins OpenClaw.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.
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é.
Exports disponibles
| Export | Objectif |
|---|---|
createTestPluginApi | Cré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_CONTRACT | Fixture 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_CONTRACT | Fixture 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_CONTRACT | Fixture de contrat de classification de repli partagée pour les adaptateurs de runtime d’agent natifs. Importer depuis plugin-sdk/agent-runtime-test-contracts |
createParameterFreeTool | Cré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 |
expectChannelInboundContextContract | Vérifier la forme du contexte entrant de canal. Importer depuis plugin-sdk/channel-contract-testing |
installChannelOutboundPayloadContractSuite | Installer les cas de contrat de payload sortant de canal. Importer depuis plugin-sdk/channel-contract-testing |
createStartAccountContext | Créer des contextes de cycle de vie de compte de canal. Importer depuis plugin-sdk/channel-test-helpers |
installChannelActionsContractSuite | Installer les cas de contrat génériques d’action de message de canal. Importer depuis plugin-sdk/channel-test-helpers |
installChannelSetupContractSuite | Installer les cas de contrat génériques de configuration de canal. Importer depuis plugin-sdk/channel-test-helpers |
installChannelStatusContractSuite | Installer les cas de contrat génériques de statut de canal. Importer depuis plugin-sdk/channel-test-helpers |
expectDirectoryIds | Vérifier les ids de répertoire de canal depuis une fonction de liste de répertoires. Importer depuis plugin-sdk/channel-test-helpers |
assertBundledChannelEntries | Vérifier que les points d’entrée de canal groupés exposent le contrat public attendu. Importer depuis plugin-sdk/channel-test-helpers |
formatEnvelopeTimestamp | Formater des horodatages d’enveloppe déterministes. Importer depuis plugin-sdk/channel-test-helpers |
expectPairingReplyText | Vérifier le texte de réponse d’appairage de canal et en extraire le code. Importer depuis plugin-sdk/channel-test-helpers |
describePluginRegistrationContract | Installer les vérifications du contrat d’inscription de plugin. Importer depuis plugin-sdk/plugin-test-contracts |
registerSingleProviderPlugin | Inscrire un plugin de fournisseur dans les smoke tests du chargeur. Importer depuis plugin-sdk/plugin-test-runtime |
registerProviderPlugin | Capturer tous les types de fournisseurs depuis un plugin. Importer depuis plugin-sdk/plugin-test-runtime |
registerProviderPlugins | Capturer les inscriptions de fournisseurs sur plusieurs plugins. Importer depuis plugin-sdk/plugin-test-runtime |
requireRegisteredProvider | Vérifier qu’une collection de fournisseurs contient un id. Importer depuis plugin-sdk/plugin-test-runtime |
createRuntimeEnv | Créer un environnement de runtime CLI/plugin mocké. Importer depuis plugin-sdk/plugin-test-runtime |
createPluginSetupWizardStatus | Créer des helpers de statut de configuration pour les plugins de canal. Importer depuis plugin-sdk/plugin-test-runtime |
describeOpenAIProviderRuntimeContract | Installer les vérifications de contrat de runtime de famille de fournisseurs. Importer depuis plugin-sdk/provider-test-contracts |
expectPassthroughReplayPolicy | Vé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 |
runRealtimeSttLiveTest | Exécuter un test de fournisseur STT en temps réel live avec des fixtures audio partagées. Importer depuis plugin-sdk/provider-test-contracts |
normalizeTranscriptForMatch | Normaliser la sortie de transcription live avant les assertions floues. Importer depuis plugin-sdk/provider-test-contracts |
expectExplicitVideoGenerationCapabilities | Vé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 |
expectExplicitMusicGenerationCapabilities | Vérifier que les fournisseurs de musique déclarent des capacités explicites de génération/édition. Importer depuis plugin-sdk/provider-test-contracts |
mockSuccessfulDashscopeVideoTask | Installer une réponse de tâche vidéo réussie compatible avec DashScope. Importer depuis plugin-sdk/provider-test-contracts |
getProviderHttpMocks | Accéder aux mocks Vitest HTTP/auth de fournisseur avec opt-in. Importer depuis plugin-sdk/provider-http-test-mocks |
installProviderHttpMockCleanup | Réinitialiser les mocks HTTP/auth de fournisseur après chaque test. Importer depuis plugin-sdk/provider-http-test-mocks |
installCommonResolveTargetErrorCases | Cas de test partagés pour la gestion des erreurs de résolution de cible. Importer depuis plugin-sdk/channel-target-testing |
shouldAckReaction | Vérifier si un canal doit ajouter une réaction d’accusé de réception. Importer depuis plugin-sdk/channel-feedback |
removeAckReactionAfterReply | Supprimer la réaction d’accusé de réception après la livraison de la réponse. Importer depuis plugin-sdk/channel-feedback |
createTestRegistry | Créer une fixture de registre de plugins de canal. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers |
createEmptyPluginRegistry | Créer une fixture de registre de plugins vide. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers |
setActivePluginRegistry | Installer une fixture de registre pour les tests de runtime de plugin. Importer depuis plugin-sdk/plugin-test-runtime ou plugin-sdk/channel-test-helpers |
createRequestCaptureJsonFetch | Capturer les requêtes fetch JSON dans les tests de helper média. Importer depuis plugin-sdk/test-env |
withServer | Exécuter des tests avec un serveur HTTP local jetable. Importer depuis plugin-sdk/test-env |
createMockIncomingRequest | Créer un objet de requête HTTP entrante minimal. Importer depuis plugin-sdk/test-env |
withFetchPreconnect | Exécuter des tests fetch avec les hooks de préconnexion installés. Importer depuis plugin-sdk/test-env |
withEnv / withEnvAsync | Modifier temporairement les variables d’environnement. Importer depuis plugin-sdk/test-env |
createTempHomeEnv / withTempHome / withTempDir | Créer des fixtures de test de système de fichiers isolées. Importer depuis plugin-sdk/test-env |
createMockServerResponse | Créer un mock minimal de réponse de serveur HTTP. Importer depuis plugin-sdk/test-env |
createCliRuntimeCapture | Capturer la sortie du runtime CLI dans les tests. Importer depuis plugin-sdk/test-fixtures |
importFreshModule | Importer un module ESM avec un jeton de requête frais pour contourner le cache des modules. Importer depuis plugin-sdk/test-fixtures |
bundledPluginRoot / bundledPluginFile | Résoudre les chemins de fixtures de source ou de dist de plugin groupé. Importer depuis plugin-sdk/test-fixtures |
mockNodeBuiltinModule | Installer des mocks Vitest étroits pour les modules intégrés Node. Importer depuis plugin-sdk/test-node-mocks |
createSandboxTestContext | Cré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 |
makeAgentAssistantMessage | Créer des fixtures de messages de transcription d’agent. Importer depuis plugin-sdk/test-fixtures |
peekSystemEvents / resetSystemEventsForTest | Inspecter et réinitialiser les fixtures d’événements système. Importer depuis plugin-sdk/test-fixtures |
sanitizeTerminalText | Assainir la sortie du terminal pour les assertions. Importer depuis plugin-sdk/test-fixtures |
countLines / hasBalancedFences | Vérifier la forme de la sortie de découpage. Importer depuis plugin-sdk/test-fixtures |
runProviderCatalog | Exécuter un hook de catalogue de fournisseurs avec des dépendances de test |
resolveProviderWizardOptions | Résoudre les choix de l’assistant de configuration du fournisseur dans les tests de contrat |
resolveProviderModelPickerEntries | Résoudre les entrées du sélecteur de modèle du fournisseur dans les tests de contrat |
buildProviderPluginMethodChoice | Créer des ids de choix de l’assistant de fournisseur pour les assertions |
setProviderWizardProvidersResolverForTest | Injecter des fournisseurs d’assistant de fournisseur pour des tests isolés |
createProviderUsageFetch | Créer des fixtures de récupération de l’utilisation du fournisseur |
useFrozenTime / useRealTime | Geler et restaurer les minuteurs pour les tests sensibles au temps. Importer depuis plugin-sdk/test-env |
createTestWizardPrompter | Créer un prompteur d’assistant de configuration simulé |
createRuntimeTaskFlow | Créer un état de flux de tâches d’exécution isolé |
typedCases | Préserver les types littéraux pour les tests pilotés par table. Importer depuis plugin-sdk/test-fixtures |
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 :Résolution des cibles de test
UtilisezinstallCommonResolveTargetErrorCases pour ajouter les cas d’erreur standard de
résolution des cibles de canal :
Modèles de test
Tester les contrats d’enregistrement
Les tests unitaires qui passent un mockapi é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é depuisopenclaw/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
Test unitaire d’un plugin de fournisseur
Mocker l’exécution du plugin
Pour le code qui utilisecreatePluginRuntimeStore, mockez l’exécution dans les tests :
Tester avec des stubs par instance
Préférez les stubs par instance à la mutation de prototype :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 :- 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 :Application par lint (plugins dans le dépôt)
Trois règles sont appliquées parpnpm check pour les plugins dans le dépôt :
- Aucune importation racine monolithique — le barrel racine
openclaw/plugin-sdkest rejeté - Aucune importation directe depuis
src/— les plugins ne peuvent pas importer directement../../src/ - Aucune auto-importation — les plugins ne peuvent pas importer leur propre sous-chemin
plugin-sdk/<name>
Configuration de test
OpenClaw utilise Vitest avec des seuils de couverture V8. Pour les tests de plugins :Liens associés
- Vue d’ensemble du SDK — conventions d’importation
- Plugins de canal SDK — interface des plugins de canal
- Plugins de fournisseur SDK — hooks des plugins de fournisseur
- Créer des plugins — guide de prise en main