--- read_when: - Ejecutar o corregir pruebas summary: Cómo ejecutar pruebas localmente (vitest) y cuándo usar los modos de ejecución forzada/cobertura title: Pruebas x-i18n: generated_at: "2026-07-26T05:55:26Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 391185703e853bb523e1396eb22da4693d10d47b1644d3b2a51707d329f67dae source_path: reference/test.md workflow: 16 --- - Kit completo de pruebas (suites, en vivo, Docker): [Pruebas](/es/help/testing) - Validación de actualizaciones y paquetes de plugins: [Pruebas de actualizaciones y plugins](/es/help/testing-updates-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 ` 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 `. - 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 `: 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. | Comando | Qué hace | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | Los objetivos explícitos de archivos o directorios se canalizan mediante flujos Vitest con ámbito definido. Las ejecuciones sin objetivos constituyen pruebas de la suite completa: los grupos fijos de fragmentos se expanden a configuraciones finales para su ejecución local en paralelo y la distribución de fragmentos prevista se muestra antes de comenzar. El grupo de extensiones siempre se expande a configuraciones de fragmentos por extensión en lugar de un único proceso gigante del proyecto raíz. | | `pnpm test:changed` | Ejecución inteligente y económica de pruebas modificadas: objetivos precisos procedentes de ediciones directas de pruebas, archivos `*.test.ts` hermanos, asignaciones explícitas de código fuente y el grafo de importaciones local. Los cambios amplios de configuración o paquetes se omiten salvo que se asignen a pruebas precisas. | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | Ejecución amplia explícita de pruebas modificadas; se utiliza cuando una edición del arnés de pruebas, la configuración o un paquete debe recurrir al comportamiento más amplio de pruebas modificadas de Vitest. | | `pnpm test:force` | Libera el puerto configurado del Gateway de OpenClaw (valor predeterminado: `18789`) y, a continuación, ejecuta la suite completa con un puerto de Gateway aislado para que las pruebas del servidor no colisionen con una instancia en ejecución. | | `pnpm test:coverage` | Emite un informe informativo de cobertura V8 para el flujo unitario predeterminado (`vitest.unit.config.ts`); no se aplican umbrales de cobertura. | | `pnpm test:coverage:changed` | Cobertura unitaria únicamente para los archivos modificados desde `origin/main`. | | `pnpm changed:lanes` | Muestra los flujos arquitectónicos activados por las diferencias con respecto a `origin/main`. | | `pnpm check:changed` | Clasifica los flujos modificados antes de elegir la ejecución. Los planes exclusivos de documentación, sin cambios y de metadatos pequeños permanecen en local cuando las dependencias están listas; los planes con distribución de comprobaciones de tipos/lint, otros flujos intensivos o dependencias locales ausentes se delegan a Crabbox/Testbox fuera de la Pipeline de CI. No ejecuta Vitest; se debe usar `pnpm test:changed` o `pnpm test ` para las pruebas. | ## 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