Plugin-Tests

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

Testhilfsprogramme

Diese Unterpfade sind Repository-lokale Quellcode-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"; 

Bevorzugen Sie diese gezielten Unterpfade für neue Tests mitgelieferter Plugins. Das umfassende openclaw/plugin-sdk/testing-Barrel und der Alias openclaw/plugin-sdk/test-utils dienen ausschließlich der Legacy-Kompatibilität: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) weist neue Importe beider Pfade aus Erweiterungstestdateien zurück, und beide bleiben ausschließlich für Kompatibilitätsnachweistests bestehen.

Verfügbare Exporte

Gebündelte Plugin-Vertragstests verwenden diese SDK-Testunterpfade ebenfalls für ausschließlich in Tests genutzte Hilfsfunktionen für Registry, Manifest, öffentliche Artefakte und Laufzeit-Fixtures. Reine Core-Testreihen, die vom gebündelten OpenClaw-Bestand abhängen, verbleiben stattdessen unter src/plugins/contracts.

Typen

Spezialisierte Testunterpfade reexportieren 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("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 manuell erstellten api-Mock an register(api) übergeben, durchlaufen die Akzeptanzprüfungen des OpenClaw-Loaders nicht. 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 Speicher.

Der echte Loader lässt die Plugin-Registrierung fehlschlagen, wenn erforderliche Metadaten fehlen oder ein Plugin eine Fähigkeits-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 Einstieg kind: "memory" deklariert.

Testen des Zugriffs auf die Laufzeitkonfiguration

Bevorzugen Sie den gemeinsamen Plugin-Laufzeit-Mock aus openclaw/plugin-sdk/plugin-test-runtime. Seine Mocks runtime.config.loadConfig() und runtime.config.writeConfigFile(...) lösen standardmäßig Fehler aus, damit Tests neue Verwendungen veralteter Kompatibilitäts-APIs erkennen. Überschreiben Sie diese Mocks nur, wenn der Test ausdrücklich älteres 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);  });});

Mocken der Plugin-Laufzeit

Mocken Sie für Code, der createPluginRuntimeStore verwendet, die Laufzeit 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 instanzbezogenen Stubs

Bevorzugen Sie instanzbezogene Stubs gegenüber der Veränderung des Prototyps:

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

Vertragstests (Plugins im Repository)

Gebündelte Plugins verfügen über Vertragstests, die die Zuständigkeit für Registrierungen überprüfen:

pnpm test src/plugins/contracts/

Diese Tests prüfen:

• Welche Plugins welche Provider registrieren
• Welche Plugins welche Sprach-Provider registrieren
• Korrektheit der Registrierungsstruktur
• Einhaltung des Laufzeitvertrags

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 für Importgrenzen aus; jede kann außerdem 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 informativer V8-Coverage-Berichterstattung. 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 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