Plugin testi

OpenClaw Plugin'leri için test yardımcıları, kalıplar ve lint uygulaması başvurusu.

Test yardımcıları

Bu test yardımcısı alt yolları, OpenClaw'ın kendi birlikte gelen Plugin testleri için depo yerelindeki kaynak giriş noktalarıdır. Üçüncü taraf Plugin'ler için paket dışa aktarımları değildir ve Vitest veya yalnızca depoya özgü diğer test bağımlılıklarını içe aktarabilirler.

Plugin API sahte içe aktarması: openclaw/plugin-sdk/plugin-test-api

Ajan çalışma zamanı sözleşmesi içe aktarması: openclaw/plugin-sdk/agent-runtime-test-contracts

Kanal sözleşmesi içe aktarması: openclaw/plugin-sdk/channel-contract-testing

Kanal test yardımcısı içe aktarması: openclaw/plugin-sdk/channel-test-helpers

Kanal hedefi testi içe aktarması: openclaw/plugin-sdk/channel-target-testing

Plugin sözleşmesi içe aktarması: openclaw/plugin-sdk/plugin-test-contracts

Plugin çalışma zamanı testi içe aktarması: openclaw/plugin-sdk/plugin-test-runtime

Sağlayıcı sözleşmesi içe aktarması: openclaw/plugin-sdk/provider-test-contracts

Sağlayıcı HTTP sahte içe aktarması: openclaw/plugin-sdk/provider-http-test-mocks

Ortam/ağ testi içe aktarması: openclaw/plugin-sdk/test-env

Genel fikstür içe aktarması: openclaw/plugin-sdk/test-fixtures

Node yerleşik sahte içe aktarması: openclaw/plugin-sdk/test-node-mocks

OpenClaw deposu içinde, yeni birlikte gelen Plugin testleri için aşağıdaki odaklı alt yolları tercih edin. Geniş openclaw/plugin-sdk/testing barrel dışa aktarımı yalnızca eski uyumluluk içindir. Depo koruma kuralları, plugin-sdk/testing ve plugin-sdk/test-utils üzerinden yeni gerçek içe aktarmaları reddeder; bu adlar yalnızca uyumluluk kaydı testleri için kullanımdan kaldırılmış uyumluluk yüzeyleri olarak kalır.

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

Kullanılabilir dışa aktarımlar

Birlikte gelen plugin sözleşme paketleri, yalnızca test amaçlı kayıt defteri, manifest, herkese açık yapıt ve çalışma zamanı fixture yardımcıları için SDK test alt yollarını da kullanır. Birlikte gelen OpenClaw envanterine bağlı yalnızca çekirdek paketler src/plugins/contracts altında kalır. Yeni uzantı testlerini, geniş plugin-sdk/testing uyumluluk barrel'ını, repo src/** dosyalarını veya repo test/helpers/* köprülerini doğrudan içe aktarmak yerine 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 ya da plugin-sdk/test-fixtures gibi belgelenmiş, odaklı bir SDK alt yolunda tutun.

Türler

Odaklı test alt yolları, test dosyalarında yararlı olan türleri de yeniden dışa aktarır:

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

Test hedefi çözümleme

Kanal hedefi çözümleme için standart hata durumları eklemek üzere installCommonResolveTargetErrorCases kullanın:

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

Test kalıpları

Kayıt sözleşmelerini test etme

register(api) işlevine elle yazılmış bir api mock'u geçiren birim testleri, OpenClaw'ın yükleyici kabul kapılarını çalıştırmaz. Plugin'inizin bağlı olduğu her kayıt yüzeyi için, özellikle hook'lar ve bellek gibi özel yetenekler için en az bir yükleyici destekli smoke testi ekleyin.

Gerçek yükleyici, gerekli meta veriler eksik olduğunda veya bir plugin sahip olmadığı bir yetenek API'sini çağırdığında plugin kaydını başarısız yapar. Örneğin, api.registerHook(...) bir hook adı gerektirir ve api.registerMemoryCapability(...), plugin manifestinin veya dışa aktarılan girdinin kind: "memory" bildirmesini gerektirir.

Çalışma zamanı yapılandırma erişimini test etme

openclaw/plugin-sdk/plugin-test-runtime içindeki paylaşılan plugin çalışma zamanı mock'unu tercih edin. Kullanımdan kaldırılmış runtime.config.loadConfig() ve runtime.config.writeConfigFile(...) mock'ları varsayılan olarak hata fırlatır; böylece testler uyumluluk API'lerinin yeni kullanımlarını yakalar. Bu mock'ları yalnızca test açıkça eski uyumluluk davranışını kapsıyorsa geçersiz kılın.

Bir kanal plugin'ini birim test etme

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

Bir sağlayıcı plugin'ini birim test etme

 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 çalışma zamanını mock'lama

createPluginRuntimeStore kullanan kod için, testlerde çalışma zamanını mock'layın:

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

Örnek başına stub'larla test etme

Prototip mutasyonu yerine örnek başına stub'ları tercih edin:

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

Sözleşme testleri (repo içi plugin'ler)

Birlikte gelen plugin'lerin kayıt sahipliğini doğrulayan sözleşme testleri vardır:

pnpm test -- src/plugins/contracts/

Bu testler şunları doğrular:

• Hangi plugin'lerin hangi sağlayıcıları kaydettiği
• Hangi plugin'lerin hangi konuşma sağlayıcılarını kaydettiği
• Kayıt şeklinin doğruluğu
• Çalışma zamanı sözleşmesine uyumluluk

Kapsamlı testleri çalıştırma

Belirli bir plugin için:

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

Yalnızca sözleşme testleri için:

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 zorlaması (repo içi plugin'ler)

Repo içi plugin'ler için pnpm check tarafından üç kural zorlanır:

1. Monolitik kök içe aktarmalar yok -- openclaw/plugin-sdk kök barrel'ı reddedilir
2. Doğrudan src/ içe aktarmaları yok -- plugin'ler ../../src/ yolunu doğrudan içe aktaramaz
3. Kendi kendini içe aktarma yok -- plugin'ler kendi plugin-sdk/<name> alt yolunu içe aktaramaz

Harici plugin'ler bu lint kurallarına tabi değildir, ancak aynı kalıpları izlemek önerilir.

Test yapılandırması

OpenClaw, V8 kapsam eşikleriyle Vitest kullanır. Plugin testleri için:

# 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

Yerel çalıştırmalar bellek baskısına neden oluyorsa:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

İlgili

• SDK Genel Bakış -- içe aktarma kuralları
• SDK Kanal Plugin'leri -- kanal plugin arayüzü
• SDK Sağlayıcı Plugin'leri -- sağlayıcı plugin hook'ları
• Plugin Oluşturma -- başlangıç kılavuzu