Testes de Plugin

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

Utilitários de teste

Estes subcaminhos são pontos de entrada de código-fonte locais do repositório para os testes dos plugins incluídos no próprio OpenClaw. Eles não são exports package.json publicados para plugins de terceiros e podem importar o Vitest ou outras dependências de teste exclusivas do repositório.

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

Use estes subcaminhos específicos para testes de plugins incluídos. O barrel openclaw/plugin-sdk/testing anterior era local do repositório, foi excluído dos pacotes distribuídos e foi removido. O alias legado openclaw/plugin-sdk/test-utils permanece local do repositório; pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) rejeita novas importações desse alias em testes de extensões.

Exports disponíveis

Os conjuntos de contratos de plugins integrados também usam esses subcaminhos de teste do SDK para auxiliares de fixtures de registro, manifesto, artefatos públicos e runtime exclusivos de teste. Os conjuntos exclusivos do núcleo que dependem do inventário integrado do OpenClaw permanecem em src/plugins/contracts.

Tipos

Subcaminhos de teste específicos também reexportam tipos úteis em arquivos de teste:

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

Teste da resolução de destinos

Use installCommonResolveTargetErrorCases para adicionar casos de erro padrão para a resolução de destinos do canal:

  describe("resolução de destinos do my-channel", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Lógica de resolução de destinos do seu canal      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Adicione casos de teste específicos do canal  it("deve resolver destinos @username", () => {    // ...  });});

Padrões de teste

Teste de contratos de registro

Testes de unidade que passam um mock api escrito manualmente para register(api) não exercitam as verificações de aceitação do carregador do OpenClaw. Adicione pelo menos um teste de fumaça apoiado pelo carregador para cada superfície de registro da qual seu plugin depende, especialmente hooks e recursos exclusivos, como memória.

O carregador real causa falha no registro do plugin quando os metadados obrigatórios estão ausentes ou um plugin chama uma API de recurso que 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".

Teste do acesso à configuração do runtime

Prefira o mock compartilhado do runtime do plugin de openclaw/plugin-sdk/plugin-test-runtime. Seus mocks runtime.config.loadConfig() e runtime.config.writeConfigFile(...) lançam erros por padrão para que os testes detectem novos usos de APIs de compatibilidade obsoletas. Substitua esses mocks somente quando o teste estiver cobrindo explicitamente o comportamento de compatibilidade legada.

Teste de unidade de um plugin de canal

 describe("plugin my-channel", () => {  it("deve resolver a conta a partir da configuração", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("deve inspecionar a conta sem materializar segredos", () => {    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");    // Nenhum valor de token exposto    expect(inspection).not.toHaveProperty("token");  });});

Teste de unidade de um plugin de provedor

 describe("plugin my-provider", () => {  it("deve resolver modelos dinâmicos", () => {    const model = myProvider.resolveDynamicModel({      modelId: "custom-model-v2",      // ... contexto    });     expect(model.id).toBe("custom-model-v2");    expect(model.provider).toBe("my-provider");    expect(model.api).toBe("openai-completions");  });   it("deve retornar o catálogo quando a chave de API estiver disponível", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... contexto    });     expect(result?.provider?.models).toHaveLength(2);  });});

Simulação do runtime do plugin

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

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "runtime de teste não definido",}); // Na configuração do testeconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... outros mocks  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... outros namespaces} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Após os testesstore.clearRuntime();

Teste com stubs por instância

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

// Preferencial: stub por instânciaconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Evite: mutação do protótipo// MyChannelClient.prototype.sendMessage = vi.fn();

Testes de contrato (plugins no repositório)

Plugins integrados 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 voz
• Correção da estrutura de registro
• Conformidade com o contrato do runtime

Execução de 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)

scripts/run-additional-boundary-checks.mjs executa um conjunto de verificações de limite de importação lint:plugins:* na CI; cada uma também pode ser executada localmente de forma independente:

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

Configuração de testes

O OpenClaw usa o Vitest 4 com relatórios informativos de cobertura V8. Para testes de plugins:

# Executar todos os testespnpm test # Executar testes de um plugin específicopnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Executar com um filtro de nome de teste específicopnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Executar com coberturapnpm test:coverage

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

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Relacionados

• 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
• Criação de plugins -- guia de introdução