Testowanie Plugin

Dokumentacja narzędzi testowych, wzorców i wymuszania lintingu dla pluginów OpenClaw.

Narzędzia testowe

Te podścieżki pomocników testowych są lokalnymi dla repozytorium punktami wejścia kodu źródłowego dla własnych testów dołączonych pluginów OpenClaw. Nie są eksportami pakietu dla pluginów firm trzecich.

Import mocka API Pluginu: openclaw/plugin-sdk/plugin-test-api

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

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

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

Import testowy celu kanału: openclaw/plugin-sdk/channel-target-testing

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

Import testowy runtime Pluginu: openclaw/plugin-sdk/plugin-test-runtime

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

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

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

Import ogólnej fikstury: openclaw/plugin-sdk/test-fixtures

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

W nowych testach pluginów preferuj poniższe wyspecjalizowane podścieżki. Szeroki barrel openclaw/plugin-sdk/testing służy wyłącznie do zgodności ze starszym kodem. Zabezpieczenia repozytorium odrzucają nowe rzeczywiste importy z plugin-sdk/testing i plugin-sdk/test-utils; te nazwy pozostają tylko jako przestarzałe powierzchnie zgodności dla testów zapisów zgodności.

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

Dostępne eksporty

Zestawy kontraktowe dla wbudowanych pluginów używają także ścieżek podrzędnych testowania SDK dla pomocników tylko testowych: rejestru, manifestu, artefaktów publicznych i fikstur środowiska uruchomieniowego. Zestawy wyłącznie dla core, które zależą od wbudowanego inwentarza OpenClaw, pozostają w src/plugins/contracts. Nowe testy rozszerzeń umieszczaj w udokumentowanej, zawężonej ścieżce podrzędnej 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 lub plugin-sdk/test-fixtures, zamiast importować szeroki barrel zgodności plugin-sdk/testing, pliki repozytorium src/** albo mostki repozytorium test/helpers/* bezpośrednio.

Typy

Zawężone ścieżki podrzędne testowania ponownie eksportują także typy przydatne w plikach testowych:

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

Rozwiązywanie celu testowania

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 dymny oparty na loaderze dla każdej powierzchni rejestracji, od której zależy Twój plugin, szczególnie hooków i wyłącznych możliwości, takich jak pamięć.

Rzeczywisty loader powoduje niepowodzenie rejestracji pluginu, gdy brakuje wymaganych metadanych albo plugin wywołuje API możliwości, której nie jest właścicielem. 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 środowiska uruchomieniowego

Podczas testowania wbudowanych pluginów kanałów preferuj współdzielony mock środowiska uruchomieniowego pluginu z openclaw/plugin-sdk/channel-test-helpers. Jego przestarzałe mocki runtime.config.loadConfig() i runtime.config.writeConfigFile(...) domyślnie zgłaszają wyjątek, aby testy wykrywały nowe użycie API zgodności. Nadpisuj te mocki tylko wtedy, gdy test jawnie obejmuje zachowanie zgodności ze starszymi wersjami.

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 środowiska uruchomieniowego pluginu

Dla kodu, który używa createPluginRuntimeStore, zamockuj środowisko uruchomieniowe 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 z per-instancyjnymi stubami

Preferuj per-instancyjne stuby zamiast mutowania 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 kontraktowe (pluginy w repozytorium)

Wbudowane pluginy mają testy kontraktowe, 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 środowiska uruchomieniowego

Uruchamianie testów o ograniczonym zakresie

Dla konkretnego pluginu:

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

Tylko dla testów kontraktowych:

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 -- barrel główny openclaw/plugin-sdk jest odrzucany
2. Brak bezpośrednich importów z src/ -- pluginy nie mogą importować bezpośrednio z ../../src/
3. Brak importów samego siebie -- pluginy nie mogą importować własnej ścieżki podrzędnej 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ę pamięci:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Powiązane

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