Testes de Plugin

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

Utilitários de teste

Esses subcaminhos são pontos de entrada de código-fonte locais do repositório para os testes dos plugins integrados do próprio OpenClaw. Eles não são exportações publicadas no package.json 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"; 

Prefira esses subcaminhos específicos para novos testes de plugins integrados. O barrel amplo openclaw/plugin-sdk/testing e o alias openclaw/plugin-sdk/test-utils existem apenas para compatibilidade legada: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) rejeita novas importações de qualquer um deles em arquivos de teste de extensões, e ambos permanecem exclusivamente para testes de registro de compatibilidade.

Exportações disponíveis

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

Tipos

Os 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 destino

Use installCommonResolveTargetErrorCases para adicionar casos de erro padrão à resolução de destino do 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

Teste de contratos de registro

Testes unitários que passam um mock de 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 falha ao registrar o plugin quando 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. Os mocks de 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. Sobrescreva esses mocks somente quando o teste cobrir explicitamente um comportamento de compatibilidade legado.

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

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

Teste com stubs por instância

Prefira stubs por instância em vez de modificar o 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 do repositório)

Os 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 fala
• Correção do formato do registro
• Conformidade com o contrato do runtime

Execução de testes específicos

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 das regras de lint (plugins do repositório)

scripts/run-additional-boundary-checks.mjs executa um conjunto de verificações de limites de importação lint:plugins:* na CI; cada uma também pode ser executada isoladamente no ambiente local:

Plugins externos não estão sujeitos a essas regras de lint, mas recomenda-se 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:

# 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 as 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
• Criação de plugins -- guia de primeiros passos