Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Referencia de utilidades, patrones y aplicación de lint para las pruebas de plugins de OpenClaw.
¿Buscas ejemplos de pruebas? Las guías prácticas incluyen ejemplos de pruebas resueltos: Pruebas de plugins de canal y Pruebas de plugins de proveedor.

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.
import {
  shouldAckReaction,
  removeAckReactionAfterReply,
} from "openclaw/plugin-sdk/channel-feedback";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";
import { AUTH_PROFILE_RUNTIME_CONTRACT } from "openclaw/plugin-sdk/agent-runtime-test-contracts";
import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing";
import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers";
import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts";
import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime";
import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts";
import { getProviderHttpMocks } from "openclaw/plugin-sdk/provider-http-test-mocks";
import { withEnv, withFetchPreconnect, withServer } from "openclaw/plugin-sdk/test-env";
import {
  bundledPluginRoot,
  createCliRuntimeCapture,
  typedCases,
} from "openclaw/plugin-sdk/test-fixtures";
import { mockNodeBuiltinModule } from "openclaw/plugin-sdk/test-node-mocks";

Exportaciones disponibles

ExportaciónPropósito
createTestPluginApiConstruye un mock mínimo de API de plugin para pruebas unitarias de registro directo. Importar desde plugin-sdk/plugin-test-api
AUTH_PROFILE_RUNTIME_CONTRACTFixture compartido de contrato de perfil de autenticación para adaptadores runtime de agentes nativos. Importar desde plugin-sdk/agent-runtime-test-contracts
DELIVERY_NO_REPLY_RUNTIME_CONTRACTFixture compartido de contrato de supresión de entrega para adaptadores runtime de agentes nativos. Importar desde plugin-sdk/agent-runtime-test-contracts
OUTCOME_FALLBACK_RUNTIME_CONTRACTFixture compartido de contrato de clasificación de fallback para adaptadores runtime de agentes nativos. Importar desde plugin-sdk/agent-runtime-test-contracts
createParameterFreeToolConstruye fixtures de esquemas de herramientas dinámicas para pruebas de contrato de runtime nativo. Importar desde plugin-sdk/agent-runtime-test-contracts
expectChannelInboundContextContractVerifica la forma del contexto entrante del canal. Importar desde plugin-sdk/channel-contract-testing
installChannelOutboundPayloadContractSuiteInstala casos de contrato de payload saliente de canal. Importar desde plugin-sdk/channel-contract-testing
createStartAccountContextConstruye contextos de ciclo de vida de cuentas de canal. Importar desde plugin-sdk/channel-test-helpers
installChannelActionsContractSuiteInstala casos genéricos de contrato de acciones de mensaje de canal. Importar desde plugin-sdk/channel-test-helpers
installChannelSetupContractSuiteInstala casos genéricos de contrato de configuración de canal. Importar desde plugin-sdk/channel-test-helpers
installChannelStatusContractSuiteInstala casos genéricos de contrato de estado de canal. Importar desde plugin-sdk/channel-test-helpers
expectDirectoryIdsVerifica los ids del directorio de canal desde una función de listado de directorio. Importar desde plugin-sdk/channel-test-helpers
assertBundledChannelEntriesVerifica que los puntos de entrada de canales incluidos expongan el contrato público esperado. Importar desde plugin-sdk/channel-test-helpers
formatEnvelopeTimestampFormatea marcas de tiempo deterministas de sobres. Importar desde plugin-sdk/channel-test-helpers
expectPairingReplyTextVerifica el texto de respuesta de emparejamiento del canal y extrae su código. Importar desde plugin-sdk/channel-test-helpers
describePluginRegistrationContractInstala comprobaciones del contrato de registro de plugins. Importar desde plugin-sdk/plugin-test-contracts
registerSingleProviderPluginRegistra un plugin de proveedor en pruebas de humo del cargador. Importar desde plugin-sdk/plugin-test-runtime
registerProviderPluginCaptura todos los tipos de proveedor de un plugin. Importar desde plugin-sdk/plugin-test-runtime
registerProviderPluginsCaptura registros de proveedores entre varios plugins. Importar desde plugin-sdk/plugin-test-runtime
requireRegisteredProviderVerifica que una colección de proveedores contenga un id. Importar desde plugin-sdk/plugin-test-runtime
createRuntimeEnvConstruye un entorno runtime simulado de CLI/plugin. Importar desde plugin-sdk/plugin-test-runtime
createPluginSetupWizardStatusConstruye helpers de estado de configuración para plugins de canal. Importar desde plugin-sdk/plugin-test-runtime
describeOpenAIProviderRuntimeContractInstala comprobaciones de contrato de runtime de familia de proveedores. Importar desde plugin-sdk/provider-test-contracts
expectPassthroughReplayPolicyVerifica que las políticas de repetición del proveedor pasen herramientas y metadatos propiedad del proveedor. Importar desde plugin-sdk/provider-test-contracts
runRealtimeSttLiveTestEjecuta una prueba en vivo de proveedor STT en tiempo real con fixtures de audio compartidos. Importar desde plugin-sdk/provider-test-contracts
normalizeTranscriptForMatchNormaliza la salida de transcripción en vivo antes de aserciones aproximadas. Importar desde plugin-sdk/provider-test-contracts
expectExplicitVideoGenerationCapabilitiesVerifica que los proveedores de video declaren capacidades explícitas de modo de generación. Importar desde plugin-sdk/provider-test-contracts
expectExplicitMusicGenerationCapabilitiesVerifica que los proveedores de música declaren capacidades explícitas de generación/edición. Importar desde plugin-sdk/provider-test-contracts
mockSuccessfulDashscopeVideoTaskInstala una respuesta exitosa de tarea de video compatible con DashScope. Importar desde plugin-sdk/provider-test-contracts
getProviderHttpMocksAccede a mocks Vitest opcionales de HTTP/autenticación de proveedor. Importar desde plugin-sdk/provider-http-test-mocks
installProviderHttpMockCleanupRestablece mocks de HTTP/autenticación de proveedor después de cada prueba. Importar desde plugin-sdk/provider-http-test-mocks
installCommonResolveTargetErrorCasesCasos de prueba compartidos para el manejo de errores de resolución de destino. Importar desde plugin-sdk/channel-target-testing
shouldAckReactionComprueba si un canal debe agregar una reacción de confirmación. Importar desde plugin-sdk/channel-feedback
removeAckReactionAfterReplyElimina la reacción de confirmación después de entregar la respuesta. Importar desde plugin-sdk/channel-feedback
createTestRegistryConstruye un fixture de registro de plugins de canal. Importar desde plugin-sdk/plugin-test-runtime o plugin-sdk/channel-test-helpers
createEmptyPluginRegistryConstruye un fixture de registro de plugins vacío. Importar desde plugin-sdk/plugin-test-runtime o plugin-sdk/channel-test-helpers
setActivePluginRegistryInstala un fixture de registro para pruebas de runtime de plugins. Importar desde plugin-sdk/plugin-test-runtime o plugin-sdk/channel-test-helpers
createRequestCaptureJsonFetchCaptura solicitudes fetch JSON en pruebas de helpers de medios. Importar desde plugin-sdk/test-env
withServerEjecuta pruebas contra un servidor HTTP local desechable. Importar desde plugin-sdk/test-env
createMockIncomingRequestConstruye un objeto mínimo de solicitud HTTP entrante. Importar desde plugin-sdk/test-env
withFetchPreconnectEjecuta pruebas de fetch con hooks de preconexión instalados. Importar desde plugin-sdk/test-env
withEnv / withEnvAsyncParchea temporalmente variables de entorno. Importar desde plugin-sdk/test-env
createTempHomeEnv / withTempHome / withTempDirCrea fixtures de prueba de sistema de archivos aislados. Importar desde plugin-sdk/test-env
createMockServerResponseCrea un mock mínimo de respuesta de servidor HTTP. Importar desde plugin-sdk/test-env
createCliRuntimeCaptureCaptura la salida del runtime de CLI en pruebas. Importar desde plugin-sdk/test-fixtures
importFreshModuleImporta un módulo ESM con un token de consulta nuevo para omitir la caché de módulos. Importar desde plugin-sdk/test-fixtures
bundledPluginRoot / bundledPluginFileResuelve rutas de fixtures de código fuente o dist de plugins incluidos. Importar desde plugin-sdk/test-fixtures
mockNodeBuiltinModuleInstala mocks Vitest acotados de módulos integrados de Node. Importar desde plugin-sdk/test-node-mocks
createSandboxTestContextConstruye contextos de prueba de sandbox. Importar desde plugin-sdk/test-fixtures
writeSkillEscribe fixtures de skill. Importar desde plugin-sdk/test-fixtures
makeAgentAssistantMessageConstruye fixtures de mensajes de transcripción de agente. Importar desde plugin-sdk/test-fixtures
peekSystemEvents / resetSystemEventsForTestInspecciona y restablece fixtures de eventos del sistema. Importar desde plugin-sdk/test-fixtures
sanitizeTerminalTextSanitiza la salida de terminal para aserciones. Importar desde plugin-sdk/test-fixtures
countLines / hasBalancedFencesVerifica la forma de la salida de fragmentación. Importar desde plugin-sdk/test-fixtures
runProviderCatalogEjecuta un hook de catálogo de proveedor con dependencias de prueba
resolveProviderWizardOptionsResuelve opciones del asistente de configuración de proveedor en pruebas de contrato
resolveProviderModelPickerEntriesResuelve entradas del selector de modelos de proveedor en pruebas de contrato
buildProviderPluginMethodChoiceConstruye ids de opciones del asistente de proveedor para aserciones
setProviderWizardProvidersResolverForTestInyecta proveedores del asistente de proveedor para pruebas aisladas
createProviderUsageFetchCrear fixtures para obtener el uso del proveedor
useFrozenTime / useRealTimeCongelar y restaurar temporizadores para pruebas sensibles al tiempo. Importar desde plugin-sdk/test-env
createTestWizardPrompterCrear un prompter simulado del asistente de configuración
createRuntimeTaskFlowCrear un estado aislado del flujo de tareas en tiempo de ejecución
typedCasesPreservar tipos literales para pruebas basadas en tablas. Importar desde plugin-sdk/test-fixtures
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:
import type {
  ChannelAccountSnapshot,
  ChannelGatewayContext,
} from "openclaw/plugin-sdk/channel-contract";
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
import type { MockFn, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk/plugin-test-runtime";

Prueba de resolución de destino

Usa installCommonResolveTargetErrorCases para agregar casos de error estándar para la resolución de destinos de canal:
import { describe } from "vitest";
import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/channel-target-testing";

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

import { describe, it, expect, vi } from "vitest";

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

import { describe, it, expect } from "vitest";

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:
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "test-plugin",
  errorMessage: "test runtime not set",
});

// In test setup
const 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 tests
store.clearRuntime();

Probar con stubs por instancia

Prefiere stubs por instancia en lugar de mutación de prototipos:
// Preferred: per-instance stub
const 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.ts
pnpm test -- src/plugins/contracts/auth-choice.contract.test.ts
pnpm 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 tests
pnpm test

# Run specific plugin tests
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts

# Run with a specific test name filter
pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"

# Run with coverage
pnpm test:coverage
Si las ejecuciones locales causan presión de memoria:
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test

Relacionado