Testowanie Plugin

Dokumentacja narzędzi testowych, wzorców i wymuszania reguł lint dla pluginów OpenClaw.

Narzędzia testowe

Te ścieżki podrzędne pomocników testowych są lokalnymi dla repozytorium punktami wejścia źródeł dla własnych testów dołączonych pluginów OpenClaw. Nie są eksportami pakietu dla pluginów zewnętrznych i mogą importować Vitest lub inne zależności testowe dostępne tylko w repozytorium.

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

Import kontraktu środowiska uruchomieniowego agenta: openclaw/plugin-sdk/agent-runtime-test-contracts

Import kontraktu kanału: openclaw/plugin-sdk/channel-contract-testing

Import pomocnika testów kanału: openclaw/plugin-sdk/channel-test-helpers

Import testów celu kanału: openclaw/plugin-sdk/channel-target-testing

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

Import testu środowiska uruchomieniowego Plugin: openclaw/plugin-sdk/plugin-test-runtime

Import kontraktu dostawcy: openclaw/plugin-sdk/provider-test-contracts

Import makiety HTTP dostawcy: openclaw/plugin-sdk/provider-http-test-mocks

Import testów środowiska/sieci: openclaw/plugin-sdk/test-env

Import ogólnego fixture: openclaw/plugin-sdk/test-fixtures

Import makiety wbudowanego modułu Node: openclaw/plugin-sdk/test-node-mocks

W repozytorium OpenClaw dla nowych testów dołączonych pluginów preferuj poniższe wyspecjalizowane ścieżki podrzędne. Szeroki barrel openclaw/plugin-sdk/testing służy wyłącznie starszej kompatybilności. Zabezpieczenia repozytorium odrzucają nowe rzeczywiste importy z plugin-sdk/testing i plugin-sdk/test-utils; te nazwy pozostają tylko jako przestarzałe powierzchnie kompatybilności dla testów rejestrów kompatybilności.

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

Dostępne eksporty

Zestawy testów kontraktów dla dołączonych pluginów używają też podścieżek testowych SDK dla pomocników fixture używanych wyłącznie w testach: rejestru, manifestu, artefaktu publicznego i runtime. Zestawy wyłącznie dla rdzenia, które zależą od dołączonego inwentarza OpenClaw, pozostają w src/plugins/contracts. Nowe testy rozszerzeń umieszczaj na udokumentowanej, wyspecjalizowanej podścieżce SDK, takiej jak 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 albo plugin-sdk/test-fixtures, zamiast importować bezpośrednio szeroki kompatybilnościowy barrel plugin-sdk/testing, pliki repozytorium src/** albo mostki repozytorium test/helpers/*.

Typy

Wyspecjalizowane podścieżki testowe ponownie eksportują też typy przydatne w plikach testowych:

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

Rozwiązywanie celu testów

Użyj installCommonResolveTargetErrorCases, aby dodać standardowe przypadki błędów dla rozwiązywania celu kanału:

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

Wzorce testowania

Testowanie kontraktów rejestracji

Testy jednostkowe, które przekazują ręcznie napisany mock api do register(api), nie sprawdzają bramek akceptacji loadera OpenClaw. Dodaj co najmniej jeden test smoke oparty na loaderze dla każdej powierzchni rejestracji, od której zależy Twój plugin, szczególnie hooków i wyłącznych capabilities, takich jak pamięć.

Rzeczywisty loader powoduje niepowodzenie rejestracji pluginu, gdy brakuje wymaganych metadanych albo gdy plugin wywołuje capability API, którego nie posiada. Na przykład api.registerHook(...) wymaga nazwy hooka, a api.registerMemoryCapability(...) wymaga, aby manifest pluginu albo eksportowany punkt wejścia deklarował kind: "memory".

Testowanie dostępu do konfiguracji runtime

Preferuj współdzielony mock runtime pluginu z openclaw/plugin-sdk/plugin-test-runtime. Jego przestarzałe mocki runtime.config.loadConfig() i runtime.config.writeConfigFile(...) domyślnie rzucają wyjątek, aby testy wychwytywały nowe użycia kompatybilnościowych API. Nadpisuj te mocki tylko wtedy, gdy test jawnie obejmuje starsze zachowanie kompatybilnościowe.

Testowanie jednostkowe pluginu kanału

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

Testowanie jednostkowe pluginu dostawcy

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

Mockowanie runtime pluginu

Dla kodu, który używa createPluginRuntimeStore, mockuj runtime w testach:

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

Testowanie ze stubami na instancję

Preferuj stuby na instancję zamiast mutacji prototypu:

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

Testy kontraktów (pluginy w repozytorium)

Dołączone pluginy mają testy kontraktów, które weryfikują własność rejestracji:

pnpm test -- src/plugins/contracts/

Te testy sprawdzają:

• Które pluginy rejestrują których dostawców
• Które pluginy rejestrują których dostawców mowy
• Poprawność kształtu rejestracji
• Zgodność z kontraktem runtime

Uruchamianie testów o ograniczonym zakresie

Dla konkretnego pluginu:

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

Tylko dla testów kontraktów:

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

Egzekwowanie lintowania (pluginy w repozytorium)

Trzy reguły są egzekwowane przez pnpm check dla pluginów w repozytorium:

1. Brak monolitycznych importów z katalogu głównego -- główny barrel openclaw/plugin-sdk jest odrzucany
2. Brak bezpośrednich importów z src/ -- pluginy nie mogą bezpośrednio importować ../../src/
3. Brak samoimportów -- pluginy nie mogą importować własnej podścieżki plugin-sdk/<name>

Pluginy zewnętrzne nie podlegają tym regułom lintowania, ale zaleca się stosowanie tych samych wzorców.

Konfiguracja testów

OpenClaw używa Vitest z progami pokrycia V8. Dla testów pluginów:

# 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

Jeśli lokalne uruchomienia powodują presję na pamięć:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Powiązane

• Przegląd SDK -- konwencje importowania
• Pluginy kanałów SDK -- interfejs pluginu kanału
• Pluginy dostawców SDK -- hooki pluginu dostawcy
• Tworzenie pluginów -- przewodnik wprowadzający