Pruebas de Plugin

Referencia de utilidades, patrones y aplicación de lint para las pruebas de 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 los propios plugins incluidos de OpenClaw. No son exportaciones del paquete para plugins de terceros.

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

Importación de contrato de tiempo de ejecución 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 tiempo de ejecución de Plugin: openclaw/plugin-sdk/plugin-test-runtime

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

Importación simulada de 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 simulada de elemento integrado de Node: openclaw/plugin-sdk/test-node-mocks

Prefiere las subrutas enfocadas que aparecen a continuación para las nuevas pruebas de plugins. 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 registros de compatibilidad.

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

Exportaciones disponibles

Las suites de contratos de plugins incluidos también usan subrutas de prueba del SDK para helpers de registro, manifiesto, artefactos públicos y fixtures de tiempo de ejecución solo para pruebas. Las suites exclusivas del núcleo que dependen del inventario incluido de OpenClaw permanecen en src/plugins/contracts. Mantén las nuevas pruebas de extensiones 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 barrel amplio de compatibilidad plugin-sdk/testing, archivos src/** del repositorio o puentes test/helpers/* del repositorio.

Tipos

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

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

Prueba de resolución de destino

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

Patrones de prueba

Probar contratos de registro

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

El cargador 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 declaren kind: "memory".

Probar el acceso a la configuración de tiempo de ejecución

Prefiere el mock compartido de tiempo de ejecución de plugin de openclaw/plugin-sdk/channel-test-helpers al probar plugins de canal incluidos. Sus mocks obsoletos runtime.config.loadConfig() y runtime.config.writeConfigFile(...) lanzan errores por defecto para que las pruebas detecten nuevo uso de API de compatibilidad. Sobrescribe esos mocks solo cuando la prueba cubra explícitamente comportamiento de compatibilidad heredado.

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

Simular el tiempo de ejecución del plugin

Para el código que usa createPluginRuntimeStore, simula el tiempo de ejecución 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 de prototipos:

// 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 repositorio)

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

pnpm test -- src/plugins/contracts/

Estas pruebas afirman:

• Qué plugins registran qué proveedores
• Qué plugins registran qué proveedores de voz
• Corrección de la forma del registro
• Cumplimiento del contrato de tiempo de ejecución

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 repositorio)

Tres reglas son aplicadas por pnpm check para plugins dentro del repositorio:

1. Sin importaciones monolíticas desde la raíz -- se rechaza el barrel raíz openclaw/plugin-sdk
2. Sin importaciones directas de src/ -- los plugins no pueden importar directamente ../../src/
3. Sin autoimportaciones -- 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 de 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