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 paketlenmiş Plugin testleri için depoya yerel kaynak giriş noktalarıdır. Üçüncü taraf Plugin'ler için paket dışa aktarımları değildir.

Plugin API mock içe aktarımı: openclaw/plugin-sdk/plugin-test-api

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

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

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

Kanal hedefi test içe aktarımı: openclaw/plugin-sdk/channel-target-testing

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

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

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

Sağlayıcı HTTP mock içe aktarımı: openclaw/plugin-sdk/provider-http-test-mocks

Ortam/ağ test içe aktarımı: openclaw/plugin-sdk/test-env

Genel fixture içe aktarımı: openclaw/plugin-sdk/test-fixtures

Node yerleşik mock içe aktarımı: openclaw/plugin-sdk/test-node-mocks

Yeni Plugin testleri için aşağıdaki odaklı alt yolları tercih edin. Geniş openclaw/plugin-sdk/testing barrel yalnızca eski uyumluluk içindir. Depo güvenlik kuralları, plugin-sdk/testing ve plugin-sdk/test-utils üzerinden yeni gerçek içe aktarımları 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

Paketle gelen plugin sözleşme paketleri de yalnızca test amaçlı kayıt defteri, manifest, herkese açık artefakt ve çalışma zamanı fixture yardımcıları için SDK test alt yollarını kullanır. Yalnızca çekirdeğe ait olan ve paketle gelen OpenClaw envanterine bağımlı paketler src/plugins/contracts altında kalır. Yeni eklenti 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ümlemesi için standart hata durumlarını 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ğımlı 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 metadata eksik olduğunda veya bir plugin sahip olmadığı bir yetenek API'sini çağırdığında plugin kaydını başarısız kılar. Örneğin, api.registerHook(...) bir hook adı gerektirir ve api.registerMemoryCapability(...), plugin manifestinin veya dışa aktarılan girişin kind: "memory" bildirmesini gerektirir.

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

Paketle gelen kanal plugin'lerini test ederken openclaw/plugin-sdk/channel-test-helpers 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ımı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)

Paketle gelen plugin'lerde kayıt sahipliğini doğrulayan sözleşme testleri bulunur:

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 uyum

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/ öğesini doğrudan içe aktaramaz
3. 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 olursa:

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