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 económicas 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 ejecución en abanico de comprobación de tipos/lint, las compilaciones, Docker, las vías de paquetes, las pruebas E2E, las pruebas en vivo y la validación multiplataforma se ejecutan de forma remota mediante Crabbox. Para las pruebas pesadas de mantenedores de confianza se usa 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 CI de bifurcación sin secretos o un Crabbox de AWS directo y saneado.

No se debe precalentar para trabajo previsto. Se debe adquirir el backend de forma diferida cuando esté listo el primer comando pesado, reutilizar el id tbx_... devuelto para los comandos pesados posteriores, sincronizar la copia de trabajo actual en cada ejecución y detenerlo antes de la entrega.

Después de la primera reutilización correcta, el contenedor registra la base, las dependencias y la huella digital del flujo de trabajo de Testbox del arrendamiento en .crabbox/testbox-leases/. Las ediciones que solo afectan al código fuente siguen reutilizando la instancia precalentada. 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 continúa sincronizando la copia de trabajo actual. OPENCLAW_TESTBOX_ALLOW_STALE=1 se usa solo para diagnósticos intencionales, no para pruebas de publicación.

Los comandos de prueba locales que aparecen a continuación son para flujos de trabajo humanos y pruebas acotadas del agente. Debe informarse de la falta de disponibilidad del proveedor remoto; no es un permiso para ejecutar silenciosamente una puerta local amplia.

Para pruebas pesadas que no sean de confianza, se debe precalentar de forma diferida con --provider aws. Cada ejecución debe establecer CRABBOX_ENV_ALLOW=CI, pasar --provider aws --no-hydrate y usar un HOME remoto temporal nuevo antes de instalar dependencias o ejecutar pruebas. Se debe usar un arrendamiento recién precalentado dedicado a ese código fuente que no sea de confianza; nunca se debe reutilizar un arrendamiento de confianza o cargado previamente con credenciales. Se debe iniciar un binario de Crabbox de confianza instalado desde una copia de trabajo limpia y de confianza de main y obtener únicamente el PR remoto con --fresh-pr; nunca se debe ejecutar localmente el contenedor ni la configuración de la copia de trabajo que no sea de confianza. Se debe anular CRABBOX_AWS_INSTANCE_PROFILE y provocar 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 confianza con rutas absolutas 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 PR revisado. Se debe vincular el arrendamiento a ese SHA y detenerlo y volverlo a precalentar cuando cambie la cabecera. Se debe cargar el scripts/crabbox-untrusted-bootstrap.sh de confianza 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 intermediario no puede demostrar que no hay ningún rol o que no existe ningún PR remoto, se debe usar CI de bifurcación sin secretos. No se deben usar hydrate-github, --no-sync ni un flujo de trabajo de Testbox cargado con credenciales. Se deben anular todas las sustituciones de CRABBOX_TAILSCALE*, forzar --network public --tailscale=false, borrar los indicadores de nodo de salida/LAN y exigir que crabbox inspect informe de redes públicas sin estado de Tailscale antes de cargar cualquier script.

Orden local habitual

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

En un árbol de trabajo de Codex o una copia de trabajo vinculada/dispersa, los agentes evitan el uso local directo de 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 que solo afectan a la documentación, sin cambios y con pocos metadatos permanecen locales cuando las dependencias están listas, mientras que los planes pesados 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 de actividad; se debe 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 pesadas 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 solo en hosts locales de alta capacidad cuando se ejecutan intencionalmente comprobaciones independientes en varios á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 por fragmento.

Estado de pruebas compartido y auxiliares de procesos

• src/test-utils/openclaw-test-state.ts: se usa desde Vitest cuando una prueba necesita un HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, accesorio de configuración, espacio de trabajo, directorio del agente o almacén de perfiles de autenticación aislado.
• pnpm test:env-mutations:report: informe no bloqueante de pruebas/arneses que modifican directamente HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR o claves de entorno relacionadas. Se usa 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, entorno de CLI, captura de registros y limpieza en un solo lugar.
• Las vías 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 personales 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 se puede cargar (el -- antes de create evita que las versiones más recientes de Node traten --env-file como un indicador de Node). Las vías que inician un Gateway pueden cargar scripts/lib/openclaw-e2e-instance.sh para resolver el punto de entrada, simular el inicio de OpenAI, iniciar en primer plano o en segundo plano, realizar sondeos de disponibilidad, exportar el entorno de estado, volcar registros y limpiar procesos.

Vías 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 dirigida; 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 PTY de la TUI: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts ejecuta la vía PTY rápida con un backend simulado. 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 fragmentos de extensiones/plugins. Los plugins de canales pesados, el plugin del navegador y OpenAI se ejecutan como fragmentos dedicados; los demás grupos de plugins permanecen agrupados. pnpm test extensions/<id> ejecuta la vía de un plugin incluido.
• Los archivos fuente con pruebas hermanas se asignan a esas pruebas antes de recurrir a patrones glob de directorios 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 fragmentos 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 encaminan por vías ligeras dedicadas que conservan solo test/setup.ts, dejando los casos con mayor carga de ejecución 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: conjunto 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 múltiples instancias WS/HTTP/Node). Usa de forma predeterminada threads + isolate: false con ejecutores adaptativos en vitest.e2e.config.ts; ajuste con OPENCLAW_E2E_WORKERS=<n> y active los registros detallados con OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: pruebas en vivo de proveedores (Claude/Minimax/DeepSeek/z.ai/etc., condicionadas por *.live.test.ts). Requiere claves de API y LIVE=1 (o OPENCLAW_LIVE_TEST=1) para dejar de omitirlas; 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 un tarball de npm, compila o reutiliza una imagen de ejecución básica con Node/Git y una imagen funcional que instala ese tarball en /app, y luego ejecuta las vías de pruebas 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 junto con dist/postinstall-inventory.json antes de que Docker lo utilice.

• Imagen básica (OPENCLAW_DOCKER_E2E_BARE_IMAGE): vías de instalación, actualización y dependencias de plugins; monta el tarball precompilado en lugar de copiar el código fuente del repositorio.
• Imagen funcional (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): vías normales de funcionalidad de la aplicación compilada.
• Definiciones de 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 administrado 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 contraídos a _).

Otro comportamiento: el ejecutor realiza de forma predeterminada una comprobación previa de Docker, limpia los contenedores E2E obsoletos de OpenClaw, comparte las cachés de herramientas CLI de los proveedores entre carriles compatibles y deja de programar nuevos carriles agrupados después del primer fallo, a menos que se establezca OPENCLAW_DOCKER_ALL_FAIL_FAST=0. Si un carril supera el límite efectivo de peso o recursos en un host con poco paralelismo, aún 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 imprimir comandos económicos de repetición de ejecución específica.

Carriles de Docker destacados

Puerta de PR local

Para las comprobaciones locales de puerta e 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, mientras sigue usando el enrutamiento de carriles delimitado para destinos explícitos de archivos o 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 en modo de cambios enrutada con la ejecución nativa del proyecto raíz para la misma diferencia de git confirmada; pnpm test:perf:changed:bench -- --worktree compara el conjunto de cambios del árbol de trabajo actual sin realizar primero una confirmación.
• 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 y de memoria dinámica para el ejecutor de pruebas unitarias (.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 del conjunto completo de pruebas y escribe datos agrupados de duración, además de artefactos JSON y registros por configuración. Los informes del conjunto completo de pruebas aíslan los archivos de forma predeterminada para que los gráficos de módulos retenidos y las pausas de GC de archivos anteriores no se imputen a aserciones posteriores; pase -- --no-isolate solo cuando se perfile intencionadamente la acumulación de trabajadores compartidos. El agente de rendimiento de pruebas usa 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 completas, de extensiones y de fragmentos con patrones de inclusión actualizan los datos de tiempos locales 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 tiempo, 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 de tiempos local.

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 rápidas 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 el Gateway y, a continuación, ejecuta openclaw health.

Prueba rápida 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

Relacionado

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