Pruebas

• Kit completo de pruebas (suites, en vivo, Docker): Pruebas
• Validación de actualizaciones y paquetes de plugins: Pruebas de actualizaciones y plugins

Configuración predeterminada del agente

Las sesiones de agente ejecutan localmente una o unas pocas pruebas específicas y comprobaciones estáticas de bajo coste solo para código fuente de confianza y cuando la instalación de dependencias existente está lista. Nunca se deben ejecutar localmente herramientas de repositorios que no sean de confianza. Las suites más grandes, las puertas de cambios con distribución de comprobaciones de tipos/lint, las compilaciones, Docker, los flujos de paquetes, E2E, las pruebas en vivo y la validación multiplataforma se ejecutan de forma remota mediante Crabbox. Las pruebas intensivas de mantenedores de confianza utilizan Blacksmith Testbox de forma predeterminada. El flujo de trabajo de Testbox configurado carga credenciales, por lo que el código de colaboradores o bifurcaciones que no sea de confianza debe usar la Pipeline de CI sin secretos de la bifurcación o una instancia directa y saneada de AWS Crabbox.

No se debe realizar un calentamiento previo para trabajos previstos. Se debe adquirir el backend de forma diferida cuando el primer comando intensivo esté listo, reutilizar el id tbx_... devuelto para los comandos intensivos posteriores, sincronizar el checkout actual en cada ejecución y detenerlo antes de la entrega.

Después de la primera reutilización correcta, el contenedor registra la base del arrendamiento, las dependencias y la huella digital del flujo de trabajo de Testbox en .crabbox/testbox-leases/. Las ediciones exclusivas del código fuente siguen reutilizando la máquina preparada. Un cambio en la base de fusión, el archivo de bloqueo, la entrada del gestor de paquetes, el contenedor o el flujo de trabajo de Testbox provoca un cierre seguro y requiere un arrendamiento nuevo. Cada ejecución sigue sincronizando el checkout actual. OPENCLAW_TESTBOX_ALLOW_STALE=1 se utiliza únicamente para diagnósticos intencionados, no para pruebas de versiones.

Los comandos de pruebas locales que aparecen a continuación están destinados a flujos de trabajo humanos y pruebas acotadas del agente. La falta de disponibilidad del proveedor remoto debe notificarse; no autoriza a ejecutar silenciosamente una puerta local amplia.

Para pruebas intensivas que no sean de confianza, se debe preparar de forma diferida con --provider aws. Cada ejecución debe establecer CRABBOX_ENV_ALLOW=CI, pasar --provider aws --no-hydrate y utilizar un HOME remoto temporal nuevo antes de instalar dependencias o ejecutar pruebas. Se debe usar un arrendamiento recién preparado y dedicado a ese código fuente que no sea de confianza; nunca se debe reutilizar un arrendamiento de confianza o previamente cargado con credenciales. Se debe iniciar un binario Crabbox de confianza instalado desde un checkout main limpio y de confianza, y obtener únicamente el pull request remoto con --fresh-pr; nunca se debe ejecutar localmente el contenedor ni la configuración del checkout que no sea de confianza. Se debe desactivar CRABBOX_AWS_INSTANCE_PROFILE y aplicar un cierre seguro salvo que el valor resuelto de aws.instanceProfile esté vacío. Antes de cualquier instalación o prueba, se deben usar herramientas de ruta absoluta de confianza para exigir un token IMDSv2, demostrar que el endpoint de credenciales de IAM devuelve 404 y verificar que el git rev-parse HEAD remoto sea igual al SHA completo de la cabecera del pull request revisado. Se debe vincular el arrendamiento a ese SHA y detenerlo y volverlo a preparar cuando cambie la cabecera. Se debe cargar el archivo de confianza scripts/crabbox-untrusted-bootstrap.sh desde un main limpio junto con --fresh-pr; este instala versiones fijadas de Node/pnpm, verifica el SHA y la versión fijada del gestor de paquetes, aísla HOME, instala las dependencias y, a continuación, ejecuta la prueba solicitada. Si el bróker no puede demostrar que no existe ningún rol o ningún pull request remoto, se debe usar la Pipeline de CI sin secretos de la bifurcación. No se deben usar hydrate-github, --no-sync ni un flujo de trabajo de Testbox cargado con credenciales. Se deben desactivar todas las anulaciones CRABBOX_TAILSCALE*, forzar --network public --tailscale=false, borrar las marcas de nodo de salida/LAN y exigir que crabbox inspect informe de una red pública sin estado de Tailscale antes de cargar cualquier script.

Orden local habitual

1. pnpm test:changed para pruebas Vitest del ámbito modificado.
2. pnpm test <path-or-filter> para un archivo, directorio u objetivo explícito.
3. pnpm test únicamente cuando se necesite intencionadamente la suite Vitest local completa.

En un árbol de trabajo de Codex o un checkout vinculado o disperso, los agentes evitan ejecutar directamente de forma local pnpm test* / pnpm check* / pnpm crabbox:run:

• Prueba específica acotada con las dependencias listas: node scripts/run-vitest.mjs <path-or-filter>.
• Comprobación de cambios con clasificación previa: node scripts/check-changed.mjs; los planes exclusivos de documentación, sin cambios y de metadatos pequeños permanecen en local cuando las dependencias están listas, mientras que los planes intensivos o con dependencias ausentes se delegan a Testbox.
• Prueba amplia explícita con arrendamiento conservado: node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed, para que pnpm se ejecute dentro de Testbox.
• El exitCode final del contenedor y el JSON de tiempos constituyen el resultado del comando. Una ejecución delegada de GitHub Actions de Blacksmith puede mostrar cancelled después de un comando SSH correcto porque Testbox se detiene desde fuera de la acción de mantenimiento activo; se deben comprobar el resumen del contenedor y la salida del comando antes de considerarlo un fallo.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: mantiene la serialización de comprobaciones intensivas dentro del árbol de trabajo actual en lugar del directorio común de Git para comandos como pnpm check:changed y pnpm test ... dirigidos. Se debe usar únicamente en hosts locales de alta capacidad cuando se ejecuten intencionadamente comprobaciones independientes en distintos árboles de trabajo vinculados.

Comandos principales

Las ejecuciones del contenedor de pruebas terminan con un breve resumen [test] passed|failed|skipped ... in ...; la línea de duración propia de Vitest sigue siendo el detalle de cada fragmento.

Estado de pruebas compartido y auxiliares de procesos

• src/test-utils/openclaw-test-state.ts: se utiliza desde Vitest cuando una prueba necesita un HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, fixture de configuración, espacio de trabajo, directorio de agente o almacén de perfiles de autenticación aislados.
• pnpm test:env-mutations:report: informe no bloqueante de pruebas y arneses que modifican directamente HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR o claves de entorno relacionadas. Se utiliza para encontrar candidatos de migración al auxiliar de estado de pruebas compartido.
• test/helpers/openclaw-test-instance.ts: pruebas E2E a nivel de proceso que necesitan un Gateway en ejecución, el entorno de la CLI, captura de registros y limpieza en un único lugar.
• Los flujos E2E de Docker/Bash que cargan scripts/lib/docker-e2e-image.sh pueden pasar docker_e2e_test_state_shell_b64 <label> <scenario> al contenedor y decodificarlo con scripts/lib/openclaw-e2e-instance.sh; los scripts con varios directorios de inicio pueden pasar docker_e2e_test_state_function_b64 y llamar a openclaw_test_state_create <label> <scenario> en cada flujo. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json escribe un archivo de entorno del host que puede cargarse (el -- antes de create evita que las versiones más recientes de Node traten --env-file como una marca de Node). Los flujos que inician un Gateway pueden cargar scripts/lib/openclaw-e2e-instance.sh para la resolución del punto de entrada, el inicio simulado de OpenAI, la ejecución en primer o segundo plano, las sondas de disponibilidad, la exportación del entorno de estado, los volcados de registros y la limpieza de procesos.

Flujos de la interfaz de control, la TUI y las extensiones

• E2E simulado de la interfaz de control: pnpm test:ui:e2e ejecuta la vía de Vitest + Playwright que inicia la interfaz de control de Vite y controla una página real de Chromium contra un WebSocket simulado del Gateway. Las pruebas se encuentran en ui/src/**/*.e2e.test.ts; las simulaciones y los controles compartidos se encuentran en ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e incluye esta vía. Las ejecuciones de agentes usan Testbox/Crabbox de forma predeterminada, incluida la verificación específica; use node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts solo como alternativa local explícita.
• Pruebas de PTY de la TUI: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts ejecuta la vía rápida de PTY con un backend falso. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 o pnpm tui:pty:test:watch --mode local ejecuta la prueba de humo más lenta de tui --local, que solo simula el endpoint externo del modelo. Compruebe texto visible estable o llamadas a fixtures, no instantáneas ANSI sin procesar.
• pnpm test:extensions y pnpm test extensions ejecutan todos los shards de extensiones/plugins. Los plugins de canales pesados, el plugin del navegador y OpenAI se ejecutan como shards dedicados; los demás grupos de plugins permanecen agrupados. pnpm test extensions/<id> ejecuta una vía de un plugin incluido.
• Los archivos fuente con pruebas hermanas se asignan a esas pruebas antes de recurrir a globs de directorio más amplios. Las modificaciones de auxiliares en src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers y src/plugins/contracts usan un grafo de importaciones local para ejecutar las pruebas que los importan, en lugar de ejecutar ampliamente todos los shards cuando la ruta de dependencia es precisa.
• Los destinos de directorios de contratos se distribuyen entre sus vías de contratos: pnpm test src/channels/plugins/contracts ejecuta las cuatro configuraciones de contratos de canales y pnpm test src/plugins/contracts ejecuta la configuración de contratos de plugins, ya que los proyectos genéricos channels/plugins excluyen contracts/**.
• auto-reply se divide en tres configuraciones dedicadas (core, top-level, reply) para que el arnés de respuestas no domine las pruebas más ligeras de estado, tokens y auxiliares de nivel superior.
• Los archivos de prueba seleccionados de plugin-sdk y commands se dirigen a través de vías ligeras dedicadas que conservan solo test/setup.ts, mientras los casos con mayor carga de ejecución permanecen en sus vías existentes.
• La configuración base de Vitest usa de forma predeterminada pool: "threads" y isolate: false, con el ejecutor compartido no aislado habilitado en todas las configuraciones del repositorio.
• pnpm test:channels ejecuta vitest.channels.config.ts.

Gateway y E2E

• La integración del Gateway es opcional: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test o pnpm test:gateway.
• pnpm test:e2e: agregado E2E del repositorio = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: pruebas de humo de extremo a extremo del Gateway (emparejamiento de WS/HTTP/Node con varias instancias). Usa de forma predeterminada threads + isolate: false con workers adaptativos en vitest.e2e.config.ts; ajústelos con OPENCLAW_E2E_WORKERS=<n> y habilite registros detallados con OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: pruebas en vivo de proveedores (Claude/Minimax/DeepSeek/z.ai/etc., controladas por *.live.test.ts). Requieren claves de API y LIVE=1 (o OPENCLAW_LIVE_TEST=1) para dejar de omitirse; habilite la salida detallada con OPENCLAW_LIVE_TEST_QUIET=0.

Suite completa de Docker (pnpm test:docker:all)

Compila la imagen compartida de pruebas en vivo, empaqueta OpenClaw una vez como tarball de npm, compila o reutiliza una imagen básica de ejecución con Node/Git y una imagen funcional que instala ese tarball en /app, y después ejecuta las vías de humo de Docker mediante un planificador ponderado. scripts/package-openclaw-for-docker.mjs es el único empaquetador local/de CI y valida el tarball y dist/postinstall-inventory.json antes de que Docker lo utilice.

• Imagen básica (OPENCLAW_DOCKER_E2E_BARE_IMAGE): vías del instalador, las actualizaciones y las dependencias de plugins; monta el tarball precompilado en lugar de fuentes copiadas del repositorio.
• Imagen funcional (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): vías normales de funcionalidad de la aplicación compilada.
• Definiciones de las vías: scripts/lib/docker-e2e-scenarios.mjs. Planificador: scripts/lib/docker-e2e-plan.mjs. Ejecutor: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json emite el plan de CI gestionado por el planificador (vías, tipos de imagen, necesidades de paquetes/imágenes en vivo, escenarios de estado y comprobaciones de credenciales) sin compilar ni ejecutar Docker.

Parámetros de planificación (variables de entorno, valores predeterminados entre paréntesis):

El patrón de variables de entorno para los límites de recursos es OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (nombre del recurso en mayúsculas, con los caracteres no alfanuméricos sustituidos por _).

Otro comportamiento: el ejecutor realiza una comprobación previa de Docker de forma predeterminada, limpia los contenedores E2E obsoletos de OpenClaw, comparte las cachés de herramientas de la CLI del proveedor entre carriles compatibles y deja de programar nuevos carriles agrupados después del primer fallo, salvo que se establezca OPENCLAW_DOCKER_ALL_FAIL_FAST=0. Si un carril supera el límite efectivo de peso/recursos en un host con poco paralelismo, aun así puede iniciarse desde un grupo vacío y ejecutarse en solitario hasta que libere capacidad. Los registros por carril, summary.json, failures.json y los tiempos de las fases se escriben en .artifacts/docker-tests/<run-id>/; use pnpm test:docker:timings <summary.json> para inspeccionar los carriles lentos y pnpm test:docker:rerun <run-id|summary.json|failures.json> para mostrar comandos económicos de repetición dirigida.

Carriles de Docker destacados

Puerta local para PR

Para las comprobaciones locales de puerta/integración de PR, ejecute:

• pnpm check:changed
• pnpm check
• pnpm check:test-types
• pnpm build
• pnpm test
• pnpm check:docs

Si pnpm test presenta fallos intermitentes en un host con carga, vuelva a ejecutarlo una vez antes de considerarlo una regresión y, después, aíslelo con pnpm test <path/to/test>. Para hosts con memoria limitada:

• OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
• OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

Herramientas de rendimiento de pruebas

• pnpm test:perf:imports: habilita los informes de duración y desglose de importaciones de Vitest, pero sigue usando el enrutamiento de carriles delimitado para objetivos explícitos de archivos/directorios. pnpm test:perf:imports:changed limita el mismo perfilado a los archivos modificados desde origin/main.
• pnpm test:perf:changed:bench -- --ref <git-ref> compara el rendimiento de la ruta enrutada del modo de cambios con la ejecución nativa del proyecto raíz para la misma diferencia de git confirmada; pnpm test:perf:changed:bench -- --worktree evalúa el rendimiento del conjunto de cambios actual del árbol de trabajo sin confirmarlo primero.
• pnpm test:perf:profile:main escribe un perfil de CPU para el hilo principal de Vitest (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner escribe perfiles de CPU + heap para el ejecutor unitario (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: ejecuta en serie cada configuración hoja de Vitest de la suite completa y escribe datos de duración agrupados, además de artefactos JSON/registros por configuración. Los informes de la suite completa aíslan los archivos de forma predeterminada para que los grafos de módulos retenidos y las pausas de GC de archivos anteriores no se atribuyan a aserciones posteriores; pase -- --no-isolate solo cuando se perfile intencionadamente la acumulación de trabajadores compartidos. El agente de rendimiento de pruebas utiliza esto como referencia antes de intentar corregir pruebas lentas. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json compara informes agrupados después de un cambio centrado en el rendimiento.
• Las ejecuciones fragmentadas de la suite completa, extensiones y patrones de inclusión actualizan los datos locales de tiempos en .artifacts/vitest-shard-timings.json; las ejecuciones posteriores de configuraciones completas usan esos tiempos para equilibrar los fragmentos lentos y rápidos. Los fragmentos de CI con patrones de inclusión añaden el nombre del fragmento a la clave de tiempos, lo que mantiene visibles los tiempos de los fragmentos filtrados sin sustituir los datos de tiempos de la configuración completa. Establezca OPENCLAW_TEST_PROJECTS_TIMINGS=0 para ignorar el artefacto local de tiempos.

Pruebas de rendimiento

pnpm tsx scripts/bench-model.ts --runs 10

pnpm test:startup:benchpnpm test:startup:bench:smokepnpm test:startup:bench:savepnpm test:startup:bench:updatepnpm test:startup:bench:checkpnpm tsx scripts/bench-cli-startup.ts --runs 12pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all

pnpm test:startup:gateway -- --runs 5 --warmup 1pnpm test:startup:gateway -- --case skipChannels --case fiftyPlugins --runs 5node --import tsx scripts/bench-gateway-startup.ts --case default --runs 5 --output .artifacts/gateway-startup.json

pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1

E2E de incorporación (Docker)

Opcional; solo es necesario para las pruebas de humo de incorporación en contenedores. Flujo completo de arranque en frío en un contenedor Linux limpio:

scripts/e2e/onboard-docker.sh

Controla el asistente interactivo mediante una pseudoterminal, verifica los archivos de configuración, espacio de trabajo y sesión, inicia después el Gateway y ejecuta openclaw health.

Prueba de humo de importación de QR (Docker)

Garantiza que el helper mantenido del entorno de ejecución de QR se cargue en los entornos de ejecución de Node compatibles con Docker (Node 24 de forma predeterminada, compatible con Node 22):

pnpm test:docker:qr

Contenido relacionado

• Pruebas
• Pruebas en vivo
• Pruebas de actualizaciones y plugins