Pruebas de Plugins

Referencia de utilidades, patrones y aplicación de reglas de lint para las pruebas de 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 integrados de OpenClaw. No son exportaciones publicadas de package.json 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"; 

Para las nuevas pruebas de plugins integrados, use preferentemente estas subrutas específicas. El módulo de reexportación general openclaw/plugin-sdk/testing y el alias openclaw/plugin-sdk/test-utils son únicamente para compatibilidad heredada: pnpm run lint:plugins:no-extension-test-core-imports (scripts/check-no-extension-test-core-imports.ts) rechaza las nuevas importaciones de cualquiera de ellos en los archivos de prueba de extensiones, y ambos se conservan exclusivamente para pruebas que registran la compatibilidad.

Exportaciones disponibles

Los conjuntos 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 tiempo de ejecución exclusivos de las pruebas. En cambio, los conjuntos exclusivos 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 prueba:

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

Resolución de destinos en las pruebas

Usa installCommonResolveTargetErrorCases para añadir casos de error estándar para la resolución de destinos 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

Pruebas de contratos de registro

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

El cargador real hace que falle 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 el nombre de un hook, y api.registerMemoryCapability(...) requiere que el manifiesto del plugin o la entrada exportada declare kind: "memory".

Pruebas del acceso a la configuración en tiempo de ejecución

Prefiere el simulacro compartido del tiempo de ejecución del plugin de openclaw/plugin-sdk/plugin-test-runtime. Sus simulacros runtime.config.loadConfig() y runtime.config.writeConfigFile(...) lanzan errores de forma predeterminada para que las pruebas detecten nuevos usos de API de compatibilidad obsoletas. Sobrescribe esos simulacros únicamente cuando la prueba cubra explícitamente comportamientos de compatibilidad heredados.

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

Simulación del 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();

Pruebas con stubs por instancia

Prefiere los stubs por instancia en lugar de modificar el 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 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
• La corrección de la estructura del registro
• El cumplimiento del contrato de tiempo de ejecución

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 en CI un conjunto de comprobaciones de límites de importación lint:plugins:*; 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 pruebas

OpenClaw usa Vitest 4 con informes informativos de cobertura de V8. Para las 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 provocan 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