Plugin-Tests

Referenz für Testhilfsprogramme, Muster und Lint-Durchsetzung für OpenClaw- Plugins.

Testhilfsprogramme

Diese Unterpfade sind repo-lokale Quell-Einstiegspunkte für die mitgelieferten Plugin-Tests von OpenClaw. Sie sind keine veröffentlichten package.json-Exporte für Drittanbieter- Plugins und können Vitest oder andere ausschließlich im Repository verfügbare Testabhängigkeiten importieren.

   shouldAckReaction,  removeAckReactionAfterReply,} from "openclaw/plugin-sdk/channel-feedback";               bundledPluginRoot,  createCliRuntimeCapture,  typedCases,} from "openclaw/plugin-sdk/test-fixtures"; 

Verwenden Sie diese gezielten Unterpfade für Tests mitgelieferter Plugins. Das frühere openclaw/plugin-sdk/testing-Barrel war repo-lokal, von ausgelieferten Paketen ausgeschlossen und wurde entfernt. Der frühere Alias openclaw/plugin-sdk/test-utils wurde zusammen damit entfernt. pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) hält Erweiterungstests auf den oben genannten gezielten Test-Unterpfaden.

Verfügbare Exporte

Gebündelte Plugin-Vertragssuiten verwenden diese SDK-Testunterpfade außerdem für reine Testhilfen für Registry, Manifest, öffentliche Artefakte und Runtime-Fixtures. Nur für den Core bestimmte Suiten, die vom gebündelten OpenClaw-Inventar abhängen, verbleiben stattdessen unter src/plugins/contracts.

Typen

Spezifische Testunterpfade re-exportieren außerdem Typen, die in Testdateien nützlich sind:

   ChannelAccountSnapshot,  ChannelGatewayContext,} from "openclaw/plugin-sdk/channel-contract";  

Auflösung von Testzielen

Verwenden Sie installCommonResolveTargetErrorCases, um Standardfehlerfälle für die Auflösung von Kanalzielen hinzuzufügen:

  describe("Zielauflösung für my-channel", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Zielauflösungslogik Ihres Kanals      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Kanalspezifische Testfälle hinzufügen  it("sollte @username-Ziele auflösen", () => {    // ...  });});

Testmuster

Testen von Registrierungsverträgen

Unit-Tests, die einen manuell erstellten api-Mock an register(api) übergeben, prüfen die Akzeptanzprüfungen des OpenClaw-Loaders nicht. Fügen Sie mindestens einen Loader-gestützten Smoke-Test für jede Registrierungsoberfläche hinzu, von der Ihr Plugin abhängt, insbesondere für Hooks und exklusive Fähigkeiten wie Memory.

Der tatsächliche Loader lässt die Plugin-Registrierung fehlschlagen, wenn erforderliche Metadaten fehlen oder ein Plugin eine Capability-API aufruft, die ihm nicht gehört. Beispielsweise erfordert api.registerHook(...) einen Hook-Namen, und api.registerMemoryCapability(...) erfordert, dass das Plugin-Manifest oder der exportierte Einstiegspunkt kind: "memory" deklariert.

Testen des Zugriffs auf die Runtime-Konfiguration

Bevorzugen Sie den gemeinsamen Plugin-Runtime-Mock aus openclaw/plugin-sdk/plugin-test-runtime. Seine Hilfsfunktionen für die Runtime-Konfiguration bilden die aktuellen Snapshot- und Mutations-APIs ab.

Unit-Test eines Kanal-Plugins

 describe("Plugin my-channel", () => {  it("sollte das Konto aus der Konfiguration auflösen", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("sollte das Konto prüfen, ohne Secrets zu materialisieren", () => {    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");    // Kein Token-Wert offengelegt    expect(inspection).not.toHaveProperty("token");  });});

Unit-Test eines Provider-Plugins

 describe("Plugin my-provider", () => {  it("sollte dynamische Modelle auflösen", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... Kontext    });     expect(model.id).toBe("custom-model-v2");    expect(model.provider).toBe("my-provider");    expect(model.api).toBe("openai-completions");  });   it("sollte den Katalog zurückgeben, wenn ein API-Schlüssel verfügbar ist", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... Kontext    });     expect(result?.provider?.models).toHaveLength(2);  });});

Mocking der Plugin-Runtime

Für Code, der createPluginRuntimeStore verwendet, mocken Sie die Runtime in Tests:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "Test-Runtime nicht festgelegt",}); // In der Testeinrichtungconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... weitere Mocks  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... weitere Namespaces} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Nach den Testsstore.clearRuntime();

Testen mit instanzbezogenen Stubs

Bevorzugen Sie instanzbezogene Stubs gegenüber der Mutation des Prototyps:

// Bevorzugt: instanzbezogener Stubconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Vermeiden: Mutation des Prototyps// MyChannelClient.prototype.sendMessage = vi.fn();

Vertragstests (Plugins im Repository)

Gebündelte Plugins verfügen über Vertragstests, die die Eigentümerschaft der Registrierung überprüfen:

pnpm test src/plugins/contracts/

Diese Tests prüfen:

• Welche Plugins welche Provider registrieren
• Welche Plugins welche Sprachanbieter registrieren
• Korrektheit der Registrierungsstruktur
• Einhaltung des Runtime-Vertrags

Ausführen eingegrenzter Tests

Für ein bestimmtes Plugin:

pnpm test <bundled-plugin-root>/my-channel/

Nur für Vertragstests:

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

Lint-Durchsetzung (Plugins im Repository)

scripts/run-additional-boundary-checks.mjs führt in der CI eine Reihe von lint:plugins:*- Prüfungen der Importgrenzen aus; jede davon kann auch lokal eigenständig ausgeführt werden:

Externe Plugins unterliegen diesen Lint-Regeln nicht, es wird jedoch empfohlen, dieselben Muster zu befolgen.

Testkonfiguration

OpenClaw verwendet Vitest 4 mit informativen V8-Coverage-Berichten. Für Plugin-Tests:

# Alle Tests ausführenpnpm test # Tests eines bestimmten Plugins ausführenpnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Mit einem bestimmten Testnamenfilter ausführenpnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Mit Coverage ausführenpnpm test:coverage

Wenn lokale Ausführungen zu hoher Speicherauslastung führen:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Verwandte Themen

• SDK-Übersicht -- Importkonventionen
• SDK-Kanal-Plugins -- Schnittstelle für Kanal-Plugins
• SDK-Provider-Plugins -- Hooks für Provider-Plugins
• Plugins erstellen -- Leitfaden für den Einstieg