Testes de Plugin

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

Utilitários de teste

Estes subcaminhos de auxiliares de teste são entrypoints de código-fonte locais do repositório para os próprios testes de Plugins integrados do OpenClaw. Eles não são exportações de pacote para Plugins de terceiros.

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

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

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

Importação do 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 do 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 do contrato de provedor: openclaw/plugin-sdk/provider-test-contracts

Importação do 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 do mock de builtin do Node: openclaw/plugin-sdk/test-node-mocks

Prefira os subcaminhos focados abaixo para novos testes de Plugin. 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 registros 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 de fixture de registro, manifesto, artefato público e runtime usados apenas em testes. Suítes somente 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 destino em testes

Use installCommonResolveTargetErrorCases para adicionar casos de erro padrão para resolução de destino 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 portas de aceitação do loader do OpenClaw. Adicione pelo menos um teste de fumaça com 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 quando 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/channel-test-helpers ao testar plugins de canal incluídos. Os mocks obsoletos runtime.config.loadConfig() e runtime.config.writeConfigFile(...) lançam erro por padrão para que os testes capturem novos usos de APIs de compatibilidade. Sobrescreva esses mocks apenas quando o teste estiver cobrindo explicitamente comportamento legado de compatibilidade.

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

Fazendo mock do runtime do plugin

Para código que usa createPluginRuntimeStore, faça mock do 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 prototype:

// 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 validam:

• 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 monolíticos da raiz -- 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 testes

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

# 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