Pruebas de plugins

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

Utilidades de prueba

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

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

Utilice estas subrutas específicas para las pruebas de plugins incluidos. El antiguo barrel openclaw/plugin-sdk/testing era local del repositorio, estaba excluido de los paquetes distribuidos y se ha eliminado. El antiguo alias openclaw/plugin-sdk/test-utils se eliminó junto con él. pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) mantiene las pruebas de extensiones en las subrutas de prueba específicas anteriores.

Exportaciones disponibles

Las suites de contratos de plugins incluidos también usan estas subrutas de pruebas del SDK para los auxiliares de registro, manifiesto, artefactos públicos y fixtures de runtime exclusivos de pruebas. Las suites exclusivas del núcleo que dependen del inventario incluido de OpenClaw permanecen en src/plugins/contracts.

Tipos

Las subrutas de pruebas específicas también reexportan tipos útiles en los archivos de pruebas:

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

Pruebas de resolución de destinos

Use installCommonResolveTargetErrorCases para añadir casos de error estándar para la resolución de destinos de canales:

  describe("resolución de destinos de my-channel", () => {  installCommonResolveTargetErrorCases({    resolveTarget: ({ to, mode, allowFrom }) => {      // Lógica de resolución de destinos de su canal      return myChannelResolveTarget({ to, mode, allowFrom });    },    implicitAllowFrom: ["user1", "user2"],  });   // Añada casos de prueba específicos del canal  it("debería resolver destinos @username", () => {    // ...  });});

Patrones de pruebas

Pruebas de contratos de registro

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

El cargador real rechaza el registro del plugin cuando faltan metadatos obligatorios o un plugin llama a una API de capacidad que no le pertenece. 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".

Pruebas de acceso a la configuración del runtime

Es preferible usar el mock compartido del runtime del plugin de openclaw/plugin-sdk/plugin-test-runtime. Sus auxiliares de configuración del runtime modelan las API actuales de instantáneas y mutación.

Pruebas unitarias de un plugin de canal

 describe("plugin my-channel", () => {  it("debería resolver la cuenta desde la configuración", () => {    const cfg = {      channels: {        "my-channel": {          token: "test-token",          allowFrom: ["user1"],        },      },    };     const account = myPlugin.setup.resolveAccount(cfg, undefined);    expect(account.token).toBe("test-token");  });   it("debería inspeccionar la cuenta sin materializar secretos", () => {    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 se expone el valor del token    expect(inspection).not.toHaveProperty("token");  });});

Pruebas unitarias de un plugin de proveedor

 describe("plugin my-provider", () => {  it("debería 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("debería devolver el catálogo cuando la clave de API esté disponible", async () => {    const result = await myProvider.catalog.run({      resolveProviderApiKey: () => ({ apiKey: "test-key" }),      // ... contexto    });     expect(result?.provider?.models).toHaveLength(2);  });});

Simulación del runtime del plugin

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

  const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "test-plugin",  errorMessage: "runtime de prueba no establecido",}); // En la configuración de las pruebasconst mockRuntime = {  agent: {    resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),    // ... otros mocks  },  config: {    current: vi.fn(() => ({}) as const),    mutateConfigFile: vi.fn(),    replaceConfigFile: vi.fn(),  },  // ... otros espacios de nombres} as unknown as PluginRuntime; store.setRuntime(mockRuntime); // Después de las pruebasstore.clearRuntime();

Pruebas con stubs por instancia

Es preferible usar stubs por instancia en lugar de modificar el prototipo:

// Preferido: stub por instanciaconst client = new MyChannelClient();client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // Evitar: modificación del prototipo// MyChannelClient.prototype.sendMessage = vi.fn();

Pruebas de contratos (plugins del repositorio)

Los plugins incluidos tienen pruebas de contratos 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 estructura de registro
• Cumplimiento del contrato del runtime

Ejecución de pruebas específicas

Para un plugin específico:

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

Solo para las pruebas de contratos:

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 del lint (plugins del repositorio)

scripts/run-additional-boundary-checks.mjs ejecuta un conjunto de comprobaciones de límites de importación de lint:plugins:* en la CI; cada una también puede ejecutarse localmente de forma independiente:

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

Configuración de las pruebas

OpenClaw usa Vitest 4 con informes informativos de cobertura V8. Para las pruebas de plugins:

# Ejecutar todas las pruebaspnpm test # Ejecutar pruebas de un plugin específicopnpm test <bundled-plugin-root>/my-channel/src/channel.test.ts # Ejecutar con un filtro de nombre de prueba específicopnpm test <bundled-plugin-root>/my-channel/ -t "resolves account" # Ejecutar con coberturapnpm test:coverage

Si las ejecuciones locales causan presión de memoria:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Contenido relacionado

• Descripción general del SDK -- convenciones de importación
• Plugins de canal del SDK -- interfaz de plugins de canal
• Plugins de proveedor del SDK -- hooks de plugins de proveedor
• Creación de plugins -- guía de introducción