Naar hoofdinhoud gaan

Documentation Index

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

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

Referentie voor testhulpprogramma’s, patronen en lint-afdwinging voor OpenClaw-plugins.
Op zoek naar testvoorbeelden? De handleidingen bevatten uitgewerkte testvoorbeelden: Kanaalplugintests en Providerplugintests.

Testhulpprogramma’s

Deze subpaden voor testhelpers zijn repo-lokale broninvoerpunten voor OpenClaw’s eigen gebundelde plugintests. Het zijn geen package-exports voor plugins van derden. Mockimport voor Plugin-API: openclaw/plugin-sdk/plugin-test-api Import voor agentruntimecontract: openclaw/plugin-sdk/agent-runtime-test-contracts Import voor kanaalcontract: openclaw/plugin-sdk/channel-contract-testing Import voor kanaaltesthelper: openclaw/plugin-sdk/channel-test-helpers Import voor kanaaldoeltest: openclaw/plugin-sdk/channel-target-testing Import voor Plugin-contract: openclaw/plugin-sdk/plugin-test-contracts Import voor Plugin-runtimetest: openclaw/plugin-sdk/plugin-test-runtime Import voor providercontract: openclaw/plugin-sdk/provider-test-contracts Mockimport voor provider-HTTP: openclaw/plugin-sdk/provider-http-test-mocks Import voor omgevings-/netwerktest: openclaw/plugin-sdk/test-env Import voor generieke fixture: openclaw/plugin-sdk/test-fixtures Mockimport voor ingebouwde Node-module: openclaw/plugin-sdk/test-node-mocks Geef voor nieuwe plugintests de voorkeur aan de gerichte subpaden hieronder. Het brede barrelbestand openclaw/plugin-sdk/testing is alleen bedoeld voor verouderde compatibiliteit. Repo-guardrails weigeren nieuwe echte imports uit plugin-sdk/testing en plugin-sdk/test-utils; die namen blijven alleen bestaan als verouderde compatibiliteitsoppervlakken voor compatibiliteitsrecordtests.
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";

Beschikbare exports

ExportDoel
createTestPluginApiBouw een minimale Plugin-API-nabootsing voor directe eenheidstests voor registratie. Importeer uit plugin-sdk/plugin-test-api
AUTH_PROFILE_RUNTIME_CONTRACTGedeelde contractfixture voor auth-profielen voor native agent-runtimeadapters. Importeer uit plugin-sdk/agent-runtime-test-contracts
DELIVERY_NO_REPLY_RUNTIME_CONTRACTGedeelde contractfixture voor leveringsonderdrukking voor native agent-runtimeadapters. Importeer uit plugin-sdk/agent-runtime-test-contracts
OUTCOME_FALLBACK_RUNTIME_CONTRACTGedeelde contractfixture voor fallback-classificatie voor native agent-runtimeadapters. Importeer uit plugin-sdk/agent-runtime-test-contracts
createParameterFreeToolBouw schemafixtures voor dynamische tools voor native runtimecontracttests. Importeer uit plugin-sdk/agent-runtime-test-contracts
expectChannelInboundContextContractControleer de vorm van de inkomende kanaalcontext. Importeer uit plugin-sdk/channel-contract-testing
installChannelOutboundPayloadContractSuiteInstalleer contractgevallen voor uitgaande kanaalpayloads. Importeer uit plugin-sdk/channel-contract-testing
createStartAccountContextBouw kanaalaccountcontexten voor de levenscyclus. Importeer uit plugin-sdk/channel-test-helpers
installChannelActionsContractSuiteInstalleer algemene contractgevallen voor kanaalberichtacties. Importeer uit plugin-sdk/channel-test-helpers
installChannelSetupContractSuiteInstalleer algemene contractgevallen voor kanaalconfiguratie. Importeer uit plugin-sdk/channel-test-helpers
installChannelStatusContractSuiteInstalleer algemene contractgevallen voor kanaalstatus. Importeer uit plugin-sdk/channel-test-helpers
expectDirectoryIdsControleer kanaaldirectory-id’s vanuit een directorylijstfunctie. Importeer uit plugin-sdk/channel-test-helpers
assertBundledChannelEntriesControleer dat gebundelde kanaalentrypoints het verwachte openbare contract blootstellen. Importeer uit plugin-sdk/channel-test-helpers
formatEnvelopeTimestampFormatteer deterministische enveloptijdstempels. Importeer uit plugin-sdk/channel-test-helpers
expectPairingReplyTextControleer de kanaalkoppelingsantwoordtekst en extraheer de code ervan. Importeer uit plugin-sdk/channel-test-helpers
describePluginRegistrationContractInstalleer contractcontroles voor Plugin-registratie. Importeer uit plugin-sdk/plugin-test-contracts
registerSingleProviderPluginRegistreer één provider-Plugin in loader-rooktests. Importeer uit plugin-sdk/plugin-test-runtime
registerProviderPluginLeg alle providersoorten uit één Plugin vast. Importeer uit plugin-sdk/plugin-test-runtime
registerProviderPluginsLeg providerregistraties over meerdere Plugins vast. Importeer uit plugin-sdk/plugin-test-runtime
requireRegisteredProviderControleer dat een providercollectie een id bevat. Importeer uit plugin-sdk/plugin-test-runtime
createRuntimeEnvBouw een nagebootste CLI-/Plugin-runtimeomgeving. Importeer uit plugin-sdk/plugin-test-runtime
createPluginSetupWizardStatusBouw configuratiestatushelpers voor kanaal-Plugins. Importeer uit plugin-sdk/plugin-test-runtime
describeOpenAIProviderRuntimeContractInstalleer runtimecontractcontroles voor providerfamilies. Importeer uit plugin-sdk/provider-test-contracts
expectPassthroughReplayPolicyControleer dat provider-replaybeleid provider-eigen tools en metadata doorgeeft. Importeer uit plugin-sdk/provider-test-contracts
runRealtimeSttLiveTestVoer een live realtime-STT-providertest uit met gedeelde audiofixtures. Importeer uit plugin-sdk/provider-test-contracts
normalizeTranscriptForMatchNormaliseer live transcriptuitvoer vóór fuzzy-controles. Importeer uit plugin-sdk/provider-test-contracts
expectExplicitVideoGenerationCapabilitiesControleer dat videoproviders expliciete mogelijkheden voor generatiemodi declareren. Importeer uit plugin-sdk/provider-test-contracts
expectExplicitMusicGenerationCapabilitiesControleer dat muziekproviders expliciete mogelijkheden voor genereren/bewerken declareren. Importeer uit plugin-sdk/provider-test-contracts
mockSuccessfulDashscopeVideoTaskInstalleer een geslaagde DashScope-compatibele videotaakrespons. Importeer uit plugin-sdk/provider-test-contracts
getProviderHttpMocksGebruik opt-in Vitest-nabootsingen voor provider-HTTP/auth. Importeer uit plugin-sdk/provider-http-test-mocks
installProviderHttpMockCleanupReset provider-HTTP/auth-nabootsingen na elke test. Importeer uit plugin-sdk/provider-http-test-mocks
installCommonResolveTargetErrorCasesGedeelde testgevallen voor foutafhandeling bij doelresolutie. Importeer uit plugin-sdk/channel-target-testing
shouldAckReactionControleer of een kanaal een bevestigingsreactie moet toevoegen. Importeer uit plugin-sdk/channel-feedback
removeAckReactionAfterReplyVerwijder de bevestigingsreactie na levering van het antwoord. Importeer uit plugin-sdk/channel-feedback
createTestRegistryBouw een registryfixture voor kanaal-Plugins. Importeer uit plugin-sdk/plugin-test-runtime of plugin-sdk/channel-test-helpers
createEmptyPluginRegistryBouw een lege Plugin-registryfixture. Importeer uit plugin-sdk/plugin-test-runtime of plugin-sdk/channel-test-helpers
setActivePluginRegistryInstalleer een registryfixture voor Plugin-runtimetests. Importeer uit plugin-sdk/plugin-test-runtime of plugin-sdk/channel-test-helpers
createRequestCaptureJsonFetchLeg JSON-fetchverzoeken vast in mediahelpertests. Importeer uit plugin-sdk/test-env
withServerVoer tests uit tegen een wegwerpbare lokale HTTP-server. Importeer uit plugin-sdk/test-env
createMockIncomingRequestBouw een minimaal inkomend HTTP-verzoekobject. Importeer uit plugin-sdk/test-env
withFetchPreconnectVoer fetch-tests uit met geïnstalleerde preconnect-hooks. Importeer uit plugin-sdk/test-env
withEnv / withEnvAsyncPatch tijdelijk omgevingsvariabelen. Importeer uit plugin-sdk/test-env
createTempHomeEnv / withTempHome / withTempDirMaak geïsoleerde testfixtures voor het bestandssysteem. Importeer uit plugin-sdk/test-env
createMockServerResponseMaak een minimale nabootsing van een HTTP-serverrespons. Importeer uit plugin-sdk/test-env
createCliRuntimeCaptureLeg CLI-runtimeuitvoer vast in tests. Importeer uit plugin-sdk/test-fixtures
importFreshModuleImporteer een ESM-module met een verse querytoken om de modulecache te omzeilen. Importeer uit plugin-sdk/test-fixtures
bundledPluginRoot / bundledPluginFileLos fixturepaden voor gebundelde Plugin-broncode of dist op. Importeer uit plugin-sdk/test-fixtures
mockNodeBuiltinModuleInstalleer smalle Vitest-nabootsingen voor ingebouwde Node-modules. Importeer uit plugin-sdk/test-node-mocks
createSandboxTestContextBouw sandboxtestcontexten. Importeer uit plugin-sdk/test-fixtures
writeSkillSchrijf skillfixtures. Importeer uit plugin-sdk/test-fixtures
makeAgentAssistantMessageBouw berichtfixtures voor agenttranscripten. Importeer uit plugin-sdk/test-fixtures
peekSystemEvents / resetSystemEventsForTestInspecteer en reset systeemeventfixtures. Importeer uit plugin-sdk/test-fixtures
sanitizeTerminalTextOntsmet terminaluitvoer voor controles. Importeer uit plugin-sdk/test-fixtures
countLines / hasBalancedFencesControleer de vorm van chunking-uitvoer. Importeer uit plugin-sdk/test-fixtures
runProviderCatalogVoer een provider-cataloghook uit met testafhankelijkheden
resolveProviderWizardOptionsLos keuzes van de providerconfiguratiewizard op in contracttests
resolveProviderModelPickerEntriesLos provider-modelkiezeritems op in contracttests
buildProviderPluginMethodChoiceBouw keuze-id’s voor de providerwizard voor controles
setProviderWizardProvidersResolverForTestInjecteer providerwizardproviders voor geïsoleerde tests
createProviderUsageFetchBouw testgegevens voor het ophalen van providergebruik
useFrozenTime / useRealTimeBevries en herstel timers voor tijdgevoelige tests. Importeer uit plugin-sdk/test-env
createTestWizardPrompterBouw een gemockte prompter voor de installatiewizard
createRuntimeTaskFlowMaak geïsoleerde runtime-status voor TaskFlow
typedCasesBehoud letterlijke typen voor tabelgestuurde tests. Importeer uit plugin-sdk/test-fixtures
Gebundelde Plugin-contractsuites gebruiken ook SDK-testsubpaden voor helpers voor register-, manifest-, openbaar-artifact- en runtime-fixtures die alleen voor tests zijn. Suites die alleen voor core zijn en afhankelijk zijn van de gebundelde OpenClaw-inventaris blijven onder src/plugins/contracts. Houd nieuwe extensietests op een gedocumenteerd, gericht SDK-subpad zoals 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, of plugin-sdk/test-fixtures in plaats van rechtstreeks de brede compatibiliteitsbarrel plugin-sdk/testing, repo-src/**-bestanden, of repo-test/helpers/*-bridges te importeren.

Typen

Gerichte testsubpaden exporteren ook typen opnieuw die nuttig zijn in testbestanden:
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";

Resolutie van testdoelen

Gebruik installCommonResolveTargetErrorCases om standaard foutgevallen toe te voegen voor resolutie van kanaaldoelen:
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", () => {
    // ...
  });
});

Testpatronen

Registratiecontracten testen

Unit-tests die een handgeschreven api-mock doorgeven aan register(api) oefenen de acceptatiepoorten van de OpenClaw-loader niet uit. Voeg ten minste één door de loader ondersteunde rooktest toe voor elk registratieoppervlak waarvan je Plugin afhankelijk is, vooral hooks en exclusieve mogelijkheden zoals memory. De echte loader laat Plugin-registratie mislukken wanneer vereiste metadata ontbreken of een Plugin een capability-API aanroept waarvan het geen eigenaar is. Bijvoorbeeld: api.registerHook(...) vereist een hooknaam, en api.registerMemoryCapability(...) vereist dat het Plugin-manifest of de geëxporteerde entry kind: "memory" declareert.

Runtime-configuratietoegang testen

Geef de voorkeur aan de gedeelde Plugin-runtime-mock uit openclaw/plugin-sdk/channel-test-helpers bij het testen van gebundelde kanaal-Plugins. De verouderde mocks runtime.config.loadConfig() en runtime.config.writeConfigFile(...) geven standaard een fout, zodat tests nieuw gebruik van compatibiliteits-API’s onderscheppen. Overschrijf die mocks alleen wanneer de test expliciet legacy-compatibiliteitsgedrag behandelt.

Een kanaal-Plugin unit-testen

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

Een provider-Plugin unit-testen

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

De Plugin-runtime mocken

Voor code die createPluginRuntimeStore gebruikt, mock je de runtime in 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();

Testen met stubs per instantie

Geef de voorkeur aan stubs per instantie boven prototype-mutatie:
// Preferred: per-instance stub
const client = new MyChannelClient();
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });

// Avoid: prototype mutation
// MyChannelClient.prototype.sendMessage = vi.fn();

Contracttests (in-repo Plugins)

Gebundelde Plugins hebben contracttests die registratie-eigenaarschap verifiëren:
pnpm test -- src/plugins/contracts/
Deze tests controleren:
  • Welke Plugins welke providers registreren
  • Welke Plugins welke speech-providers registreren
  • Correctheid van de registratievorm
  • Naleving van het runtime-contract

Scoped tests uitvoeren

Voor een specifieke Plugin:
pnpm test -- <bundled-plugin-root>/my-channel/
Alleen voor contracttests:
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

Lint-afdwinging (in-repo Plugins)

Drie regels worden afgedwongen door pnpm check voor in-repo Plugins:
  1. Geen monolithische root-imports — de root-barrel openclaw/plugin-sdk wordt geweigerd
  2. Geen directe src/-imports — Plugins kunnen ../../src/ niet rechtstreeks importeren
  3. Geen zelfimports — Plugins kunnen hun eigen subpad plugin-sdk/<name> niet importeren
Externe Plugins vallen niet onder deze lintregels, maar het volgen van dezelfde patronen wordt aanbevolen.

Testconfiguratie

OpenClaw gebruikt Vitest met V8-dekkingsdrempels. Voor Plugin-tests:
# 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
Als lokale runs geheugendruk veroorzaken:
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Gerelateerd