Plugin testi

OpenClaw Pluginleri için test yardımcı araçları, kalıpları ve lint uygulamasına ilişkin başvuru.

Test yardımcı araçları

Bu alt yollar, OpenClaw'ın kendi paketle birlikte sunulan Plugin testleri için depo içi kaynak giriş noktalarıdır. Üçüncü taraf Pluginler için yayımlanmış package.json dışa aktarımları değildir ve Vitest veya yalnızca depoda bulunan diğer test bağımlılıklarını içe aktarabilirler.

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

Paketle birlikte sunulan yeni Plugin testlerinde bu odaklanmış alt yolları tercih edin. Geniş kapsamlı openclaw/plugin-sdk/testing barrel'i ve openclaw/plugin-sdk/test-utils takma adı yalnızca eski uyumluluk içindir: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts), eklenti test dosyalarında ikisinden de yapılan yeni içe aktarımları reddeder ve her ikisi de yalnızca uyumluluk kaydı testleri için korunur.

Kullanılabilir dışa aktarımlar

Paketle gelen Plugin sözleşme paketleri, yalnızca test amaçlı kayıt defteri, manifest, herkese açık yapıt ve çalışma zamanı fikstürü yardımcıları için bu SDK test alt yollarını da kullanır. Paketle gelen OpenClaw envanterine bağlı yalnızca çekirdeğe özel paketler ise bunun yerine src/plugins/contracts altında kalır.

Türler

Odaklanmış 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ümlemeye yönelik standart hata durumlarını eklemek için installCommonResolveTargetErrorCases kullanın:

  describe("my-channel target resolution", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Kanalınızın hedef çözümleme mantığı      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Kanala özgü test durumları ekleyin  it("should resolve @username targets", () => {    // ...  });});

Test kalıpları

Kayıt sözleşmelerini test etme

register(api) işlevine elle yazılmış bir api sahtesi aktaran 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 kancalar ve bellek gibi münhasır yetenekler için, en az bir yükleyici destekli duman testi ekleyin.

Gerekli meta veriler eksik olduğunda veya bir Plugin sahibi olmadığı bir yetenek API'sini çağırdığında gerçek yükleyici Plugin kaydını başarısız kılar. Örneğin, api.registerHook(...) bir kanca 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

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

Bir kanal Plugin'ini birim testiyle sınama

 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");    // Belirteç değeri açığa çıkarılmaz    expect(inspection).not.toHaveProperty("token");  });});

Bir sağlayıcı Plugin'ini birim testiyle sınama

 describe("my-provider plugin", () => {  it("should resolve dynamic models", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... bağlam    });     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" }),      // ... bağlam    });     expect(result?.provider?.models).toHaveLength(2);  });});

Plugin çalışma zamanını sahteleme

createPluginRuntimeStore kullanan kodlarda çalışma zamanını testlerde sahteleyin:

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "test runtime not set",}); // Test kurulumundaconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... diğer sahte işlevler  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... diğer ad alanları} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Testlerden sonrastore.clearRuntime();

Örnek başına saplamalarla test etme

Prototip değiştirme yerine örnek başına saplamaları tercih edin:

// Tercih edilen: örnek başına saplamaconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Kaçının: prototip değiştirme// MyChannelClient.prototype.sendMessage = vi.fn();

Sözleşme testleri (depo içi Plugin'ler)

Paketle gelen Plugin'ler, kayıt sahipliğini doğrulayan sözleşme testlerine sahiptir:

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 uygulaması (depo içi Plugin'ler)

scripts/run-additional-boundary-checks.mjs, CI'da bir dizi lint:plugins:* içe aktarma sınırı denetimi çalıştırır; her biri yerel olarak bağımsız biçimde de çalıştırılabilir:

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

Test yapılandırması

OpenClaw, bilgilendirme amaçlı V8 kapsam raporlamasıyla Vitest 4 kullanır. Plugin testleri için:

# Tüm testleri çalıştırpnpm test # Belirli Plugin testlerini çalıştırpnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Belirli bir test adı filtresiyle çalıştırpnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Kapsam raporuyla çalıştırpnpm test:coverage

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

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

İlgili konular

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