Pruebas de Plugin

Referencia de utilidades de prueba, patrones y aplicación de lint para los plugins de OpenClaw.

Utilidades de prueba

Estas subrutas de ayudantes de prueba son puntos de entrada de código fuente locales del repositorio para las pruebas de plugins incluidos propias de OpenClaw. No son exportaciones de paquete para plugins de terceros, y pueden importar Vitest u otras dependencias de prueba exclusivas del repositorio.

Importación de mock de API de Plugin: openclaw/plugin-sdk/plugin-test-api

Importación de contrato del runtime de agente: openclaw/plugin-sdk/agent-runtime-test-contracts

Importación de contrato de canal: openclaw/plugin-sdk/channel-contract-testing

Importación de ayudante de prueba de canal: openclaw/plugin-sdk/channel-test-helpers

Importación de prueba de destino de canal: openclaw/plugin-sdk/channel-target-testing

Importación de contrato de Plugin: openclaw/plugin-sdk/plugin-test-contracts

Importación de prueba de runtime de Plugin: openclaw/plugin-sdk/plugin-test-runtime

Importación de contrato de proveedor: openclaw/plugin-sdk/provider-test-contracts

Importación de mock HTTP de proveedor: openclaw/plugin-sdk/provider-http-test-mocks

Importación de prueba de entorno/red: openclaw/plugin-sdk/test-env

Importación de fixture genérico: openclaw/plugin-sdk/test-fixtures

Importación de mock integrado de Node: openclaw/plugin-sdk/test-node-mocks

Dentro del repositorio de OpenClaw, prefiere las subrutas específicas siguientes para nuevas pruebas de plugins incluidos. El barrel amplio openclaw/plugin-sdk/testing es solo compatibilidad heredada. Las barreras del repositorio rechazan nuevas importaciones reales desde plugin-sdk/testing y plugin-sdk/test-utils; esos nombres permanecen solo como superficies de compatibilidad obsoletas para pruebas de registro de compatibilidad.

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

Exportaciones disponibles

Las suites de contrato de Plugins incluidos también usan subrutas de prueba del SDK para helpers exclusivos de prueba de registro, manifiesto, artefactos públicos y fixtures de runtime. Las suites exclusivas de core que dependen del inventario incluido de OpenClaw permanecen bajo src/plugins/contracts. Mantén las pruebas de extensiones nuevas en una subruta enfocada y documentada del 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 o plugin-sdk/test-fixtures, en lugar de importar directamente el barril amplio de compatibilidad plugin-sdk/testing, archivos src/** del repo o puentes test/helpers/* del repo.

Tipos

Las subrutas enfocadas de pruebas también reexportan tipos útiles en archivos de prueba:

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

Resolución del destino de prueba

Usa installCommonResolveTargetErrorCases para agregar casos de error estándar para la resolución del destino del 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", () => {    // ...  });});

Patrones de prueba

Probar contratos de registro

Las pruebas unitarias que pasan un mock api escrito a mano a register(api) no ejercitan las puertas de aceptación del loader de OpenClaw. Agrega al menos una prueba smoke respaldada por el loader para cada superficie de registro de la que dependa tu Plugin, especialmente hooks y capacidades exclusivas como memoria.

El loader real falla el registro del Plugin cuando faltan metadatos requeridos o un Plugin llama a una API de capacidad que no posee. Por ejemplo, api.registerHook(...) requiere un nombre de hook, y api.registerMemoryCapability(...) requiere que el manifiesto del Plugin o la entrada exportada declare kind: "memory".

Probar el acceso a la configuración del runtime

Prefiere el mock compartido del runtime de Plugin de openclaw/plugin-sdk/plugin-test-runtime. Sus mocks obsoletos runtime.config.loadConfig() y runtime.config.writeConfigFile(...) lanzan errores de forma predeterminada para que las pruebas detecten nuevos usos de APIs de compatibilidad. Sobrescribe esos mocks solo cuando la prueba cubra explícitamente comportamiento de compatibilidad heredada.

Pruebas unitarias de un 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");  });});

Pruebas unitarias de un Plugin de proveedor

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

Mockear el runtime de Plugin

Para código que usa createPluginRuntimeStore, mockea el runtime en las pruebas:

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

Probar con stubs por instancia

Prefiere stubs por instancia en lugar de mutación del prototipo:

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

Pruebas de contrato (Plugins dentro del repo)

Los Plugins incluidos tienen pruebas de contrato que verifican la propiedad del registro:

pnpm test -- src/plugins/contracts/

Estas pruebas verifican:

• Qué Plugins registran qué proveedores
• Qué Plugins registran qué proveedores de voz
• Corrección de la forma del registro
• Cumplimiento del contrato del runtime

Ejecutar pruebas con alcance

Para un Plugin específico:

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

Solo para pruebas 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

Aplicación de lint (Plugins dentro del repo)

pnpm check aplica tres reglas para Plugins dentro del repo:

1. Sin imports raíz monolíticos -- se rechaza el barril raíz openclaw/plugin-sdk
2. Sin imports directos de src/ -- los Plugins no pueden importar directamente ../../src/
3. Sin autoimports -- los Plugins no pueden importar su propia subruta plugin-sdk/<name>

Los Plugins externos no están sujetos a estas reglas de lint, pero se recomienda seguir los mismos patrones.

Configuración de pruebas

OpenClaw usa Vitest con umbrales de cobertura V8. Para pruebas 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

Si las ejecuciones locales causan presión de memoria:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Relacionado

• Descripción general del SDK -- convenciones de importación
• Plugins de canal del SDK -- interfaz de Plugin de canal
• Plugins de proveedor del SDK -- hooks de Plugin de proveedor
• Crear Plugins -- guía de primeros pasos