Plugin-Tests

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

Test-Hilfsprogramme

Diese test-helper-Unterpfade sind repo-lokale Quellcode-Einstiegspunkte für die eigenen gebündelten Plugin-Tests von OpenClaw. Sie sind keine Package-Exporte für Drittanbieter-Plugins und können Vitest oder andere nur im Repo verwendete Testabhängigkeiten importieren.

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

Import für Agent-Runtime-Vertrag: openclaw/plugin-sdk/agent-runtime-test-contracts

Import für Channel-Vertrag: openclaw/plugin-sdk/channel-contract-testing

Import für Channel-Test-Helper: openclaw/plugin-sdk/channel-test-helpers

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

Import für Plugin-Vertrag: openclaw/plugin-sdk/plugin-test-contracts

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

Import für Provider-Vertrag: openclaw/plugin-sdk/provider-test-contracts

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

Import für Umgebungs-/Netzwerktest: openclaw/plugin-sdk/test-env

Import für generische Fixture: openclaw/plugin-sdk/test-fixtures

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

Bevorzugen Sie innerhalb des OpenClaw-Repos die folgenden fokussierten Unterpfade für neue gebündelte Plugin-Tests. 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ätsdatensatz-Tests bestehen.

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

Verfügbare Exporte

Gebündelte Plugin-Vertragssuiten verwenden außerdem SDK-Test-Unterpfade für reine Test-Helfer für Registry, Manifest, öffentliche Artefakte und Runtime-Fixtures. Core-only-Suiten, die vom gebündelten OpenClaw-Inventar abhängen, bleiben unter src/plugins/contracts. Legen Sie neue Extension-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 direkt den breiten Kompatibilitäts-Barrel plugin-sdk/testing, Repo-Dateien unter src/** oder Bridges unter test/helpers/* zu importieren.

Typen

Fokussierte Test-Unterpfade 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 Channel-Zielen 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

Registrierungskontrakte testen

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 loadergestützten Smoke-Test hinzu, insbesondere für Hooks und exklusive Fähigkeiten wie Speicher.

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

Runtime-Konfigurationszugriff testen

Bevorzugen Sie den gemeinsamen Plugin-Runtime-Mock aus openclaw/plugin-sdk/plugin-test-runtime. Seine veralteten Mocks runtime.config.loadConfig() und runtime.config.writeConfigFile(...) werfen standardmäßig Fehler, damit Tests neue Nutzung von Kompatibilitäts-APIs erkennen. Überschreiben Sie diese Mocks nur, wenn der Test ausdrücklich Legacy-Kompatibilitätsverhalten abdeckt.

Unit-Tests für ein Channel-Plugin

 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-Tests für ein Provider-Plugin

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

Plugin-Runtime mocken

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 instanzspezifischen Stubs

Bevorzugen Sie instanzspezifische Stubs statt Prototyp-Mutation:

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

Vertragstests (In-Repo-Plugins)

Gebündelte Plugins haben Vertragstests, die Registrierungsbesitz verifizieren:

pnpm test -- src/plugins/contracts/

Diese Tests stellen sicher:

• Welche Plugins welche Provider registrieren
• Welche Plugins welche Sprach-Provider registrieren
• Korrektheit der Registrierungsform
• Einhaltung des Runtime-Vertrags

Bereichsbezogene Tests ausführen

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 (In-Repo-Plugins)

Drei Regeln werden von pnpm check für In-Repo-Plugins durchgesetzt:

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

Externe Plugins unterliegen diesen Lint-Regeln nicht, aber es wird 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 Speicherdruck verursachen:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Verwandte Themen

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