Teste de Plugin

Referência para utilitários de teste, padrões e aplicação de lint para plugins do OpenClaw.

Utilitários de teste

Esses subcaminhos de auxiliares de teste são pontos de entrada de código-fonte locais do repositório para os próprios testes de plugins empacotados do OpenClaw. Eles não são exportações de pacote para plugins de terceiros e podem importar Vitest ou outras dependências de teste exclusivas do repositório.

Importação de mock da API de Plugin: openclaw/plugin-sdk/plugin-test-api

Importação de contrato do runtime do agente: openclaw/plugin-sdk/agent-runtime-test-contracts

Importação de contrato de canal: openclaw/plugin-sdk/channel-contract-testing

Importação de auxiliar de teste de canal: openclaw/plugin-sdk/channel-test-helpers

Importação de teste de destino de canal: openclaw/plugin-sdk/channel-target-testing

Importação de contrato de Plugin: openclaw/plugin-sdk/plugin-test-contracts

Importação de teste de runtime de Plugin: openclaw/plugin-sdk/plugin-test-runtime

Importação de contrato de provedor: openclaw/plugin-sdk/provider-test-contracts

Importação de mock HTTP de provedor: openclaw/plugin-sdk/provider-http-test-mocks

Importação de teste de ambiente/rede: openclaw/plugin-sdk/test-env

Importação de fixture genérica: openclaw/plugin-sdk/test-fixtures

Importação de mock embutido do Node: openclaw/plugin-sdk/test-node-mocks

Dentro do repositório OpenClaw, prefira os subcaminhos focados abaixo para novos testes de plugins empacotados. O barrel amplo openclaw/plugin-sdk/testing existe apenas para compatibilidade legada. As proteções do repositório rejeitam novas importações reais de plugin-sdk/testing e plugin-sdk/test-utils; esses nomes permanecem apenas como superfícies de compatibilidade obsoletas para testes de registro de compatibilidade.

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

Exportações disponíveis

As suítes de contrato de plugins incluídos também usam subcaminhos de teste do SDK para helpers somente de teste de registro, manifesto, artefatos públicos e fixtures de runtime. Suítes exclusivas do core que dependem do inventário incluído do OpenClaw permanecem em src/plugins/contracts. Mantenha novos testes de extensões em um subcaminho focado e documentado do SDK, como 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 ou plugin-sdk/test-fixtures, em vez de importar diretamente o barrel amplo de compatibilidade plugin-sdk/testing, arquivos src/** do repositório ou pontes test/helpers/* do repositório.

Tipos

Subcaminhos focados de teste também reexportam tipos úteis em arquivos de teste:

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

Resolução de alvo em testes

Use installCommonResolveTargetErrorCases para adicionar casos de erro padrão para resolução de alvo de canal:

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

Padrões de teste

Testando contratos de registro

Testes unitários que passam um mock api escrito manualmente para register(api) não exercitam as barreiras de aceitação do loader do OpenClaw. Adicione pelo menos um teste smoke apoiado pelo loader para cada superfície de registro da qual seu plugin depende, especialmente hooks e capacidades exclusivas, como memória.

O loader real falha o registro do plugin quando metadados obrigatórios estão ausentes ou um plugin chama uma API de capacidade que ele não possui. Por exemplo, api.registerHook(...) exige um nome de hook, e api.registerMemoryCapability(...) exige que o manifesto do plugin ou a entrada exportada declare kind: "memory".

Testando acesso à configuração de runtime

Prefira o mock compartilhado de runtime de plugin de openclaw/plugin-sdk/plugin-test-runtime. Seus mocks obsoletos runtime.config.loadConfig() e runtime.config.writeConfigFile(...) lançam erro por padrão, para que os testes detectem novo uso de APIs de compatibilidade. Sobrescreva esses mocks somente quando o teste estiver cobrindo explicitamente comportamento de compatibilidade legada.

Teste unitário de um plugin de canal

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

Teste unitário de um plugin de provedor

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

Simulando o runtime do plugin

Para código que usa createPluginRuntimeStore, simule o runtime nos testes:

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

Testando com stubs por instância

Prefira stubs por instância em vez de mutação de protótipo:

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

Testes de contrato (plugins no repositório)

Plugins incluídos têm testes de contrato que verificam a propriedade do registro:

pnpm test -- src/plugins/contracts/

Esses testes verificam:

• Quais plugins registram quais provedores
• Quais plugins registram quais provedores de fala
• Correção do formato de registro
• Conformidade com o contrato de runtime

Executando testes com escopo

Para um plugin específico:

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

Somente para testes de contrato:

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

Aplicação de lint (plugins no repositório)

Três regras são aplicadas por pnpm check para plugins no repositório:

1. Sem imports raiz monolíticos -- o barrel raiz openclaw/plugin-sdk é rejeitado
2. Sem imports diretos de src/ -- plugins não podem importar ../../src/ diretamente
3. Sem autoimports -- plugins não podem importar seu próprio subcaminho plugin-sdk/<name>

Plugins externos não estão sujeitos a essas regras de lint, mas seguir os mesmos padrões é recomendado.

Configuração de teste

OpenClaw usa Vitest com limites de cobertura do V8. Para testes de plugin:

# 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

Se execuções locais causarem pressão de memória:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Relacionado

• Visão geral do SDK -- convenções de importação
• Plugins de canal do SDK -- interface de plugin de canal
• Plugins de provedor do SDK -- hooks de plugin de provedor
• Criando plugins -- guia de primeiros passos