Plugin-Tests

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

Test-Hilfsprogramme

Diese Test-Helfer-Unterpfade sind repo-lokale Quell-Entrypoints für OpenClaws eigene mitgelieferte Plugin-Tests. Sie sind keine Paketexporte für Drittanbieter-Plugins.

Plugin-API-Mock-Import: openclaw/plugin-sdk/plugin-test-api

Agent-Runtime-Contract-Import: openclaw/plugin-sdk/agent-runtime-test-contracts

Channel-Contract-Import: openclaw/plugin-sdk/channel-contract-testing

Channel-Test-Helfer-Import: openclaw/plugin-sdk/channel-test-helpers

Channel-Target-Test-Import: openclaw/plugin-sdk/channel-target-testing

Plugin-Contract-Import: openclaw/plugin-sdk/plugin-test-contracts

Plugin-Runtime-Test-Import: openclaw/plugin-sdk/plugin-test-runtime

Provider-Contract-Import: openclaw/plugin-sdk/provider-test-contracts

Provider-HTTP-Mock-Import: openclaw/plugin-sdk/provider-http-test-mocks

Umgebungs-/Netzwerk-Test-Import: openclaw/plugin-sdk/test-env

Generischer Fixture-Import: openclaw/plugin-sdk/test-fixtures

Node-Builtin-Mock-Import: openclaw/plugin-sdk/test-node-mocks

Bevorzugen Sie für neue Plugin-Tests die fokussierten Unterpfade unten. Das breite openclaw/plugin-sdk/testing-Barrel dient nur der Legacy-Kompatibilität. Repo-Guardrails lehnen neue echte Importe aus plugin-sdk/testing und plugin-sdk/test-utils ab; diese Namen bleiben nur als veraltete Kompatibilitätsoberflächen für Kompatibilitäts-Record-Tests bestehen.

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

Verfügbare Exporte

Test-Suites für gebündelte Plugins verwenden außerdem SDK-Testunterpfade für test-only Registry-, Manifest-, Public-Artifact- und Runtime-Fixture-Helfer. Core-only Suites, die vom gebündelten OpenClaw-Inventar abhängen, bleiben unter src/plugins/contracts. Legen Sie neue Plugin-Tests auf einem dokumentierten, fokussierten SDK-Unterpfad wie 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 oder plugin-sdk/test-fixtures ab, statt das breite Kompatibilitäts-Barrel plugin-sdk/testing, Repo-src/**-Dateien oder Repo- test/helpers/*-Bridges direkt zu importieren.

Typen

Fokussierte Testunterpfade exportieren außerdem Typen erneut, die in Testdateien nützlich sind:

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

Testen der Zielauflösung

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

  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", () => {    // ...  });});

Testmuster

Testen von Registrierungsverträgen

Unit-Tests, die einen handgeschriebenen api-Mock an register(api) übergeben, üben die Akzeptanz-Gates des OpenClaw-Loaders nicht aus. Fügen Sie für jede Registrierungsoberfläche, von der Ihr Plugin abhängt, mindestens einen loader-gestützten Smoke-Test hinzu, insbesondere für Hooks und exklusive Fähigkeiten wie Memory.

Der echte 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 Eintrag kind: "memory" deklariert.

Testen des Zugriffs auf die Runtime-Konfiguration

Bevorzugen Sie den gemeinsamen Plugin-Runtime-Mock aus openclaw/plugin-sdk/channel-test-helpers, wenn Sie gebündelte Kanal-Plugins testen. Seine veralteten Mocks runtime.config.loadConfig() und runtime.config.writeConfigFile(...) werfen standardmäßig Fehler, damit Tests neue Verwendungen von Kompatibilitäts-APIs erfassen. Überschreiben Sie diese Mocks nur, wenn der Test explizit Legacy-Kompatibilitätsverhalten abdeckt.

Unit-Test eines Kanal-Plugins

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

Unit-Test eines Provider-Plugins

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

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 not set",}); // In test setupconst 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 testsstore.clearRuntime();

Testen mit Stubs pro Instanz

Bevorzugen Sie Stubs pro Instanz gegenüber Prototyp-Mutationen:

// Preferred: per-instance stubconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Avoid: prototype mutation// MyChannelClient.prototype.sendMessage = vi.fn();

Vertragstests (repo-interne Plugins)

Gebündelte Plugins haben Vertragstests, die die Registrierungs-Ownership verifizieren:

pnpm test -- src/plugins/contracts/

Diese Tests prüfen:

• Welche Plugins welche Provider registrieren
• Welche Plugins welche Speech-Provider registrieren
• Korrektheit der Registrierungsform
• 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 (repo-interne Plugins)

Drei Regeln werden von pnpm check für repo-interne Plugins durchgesetzt:

1. Keine monolithischen Root-Importe -- das Root-Barrel openclaw/plugin-sdk wird abgelehnt
2. Keine direkten src/-Importe -- Plugins können ../../src/ nicht direkt importieren
3. Keine Self-Imports -- Plugins können ihren eigenen Unterpfad plugin-sdk/<name> nicht importieren

Externe Plugins unterliegen diesen Lint-Regeln nicht, es wird jedoch empfohlen, denselben Mustern zu folgen.

Testkonfiguration

OpenClaw verwendet Vitest mit V8-Coverage-Schwellenwerten. Für Plugin-Tests:

# Run all testspnpm test # Run specific plugin testspnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts # Run with a specific test name filterpnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account" # Run with coveragepnpm test:coverage

Wenn lokale Läufe Speicherprobleme verursachen:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Verwandt

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