--- read_when: - Ejecución o corrección de pruebas summary: Cómo ejecutar pruebas localmente (vitest) y cuándo usar los modos forzado/de cobertura title: Pruebas x-i18n: generated_at: "2026-07-14T14:09:07Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 25 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 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 ` 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 `. - 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 `: 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. | Comando | Función | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | Los objetivos explícitos de archivo/directorio se encaminan mediante vías de Vitest con ámbito definido. Las ejecuciones sin objetivo son pruebas de la suite completa: los grupos de fragmentos fijos se expanden a configuraciones hoja para la ejecución local en paralelo y el abanico de fragmentos esperado se imprime antes de comenzar. El grupo de extensiones siempre se expande a configuraciones de fragmentos por extensión en lugar de usar un único proceso gigante del proyecto raíz. | | `pnpm test:changed` | Ejecución inteligente y económica de pruebas modificadas: objetivos precisos a partir 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 o de configuración/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 usa cuando una edición del arnés de pruebas, la configuración o el paquete debe recurrir al comportamiento más amplio de pruebas modificadas de Vitest. | | `pnpm test:force` | Libera el puerto de Gateway de OpenClaw configurado (valor predeterminado: `18789`) y, a continuación, ejecuta la suite completa con un puerto de Gateway aislado para que las pruebas del servidor no entren en conflicto con una instancia en ejecución. | | `pnpm test:coverage` | Emite un informe informativo de cobertura de V8 para la vía de pruebas unitarias predeterminada (`vitest.unit.config.ts`); no se aplican umbrales de cobertura. | | `pnpm test:coverage:changed` | Cobertura de pruebas unitarias únicamente para los archivos modificados desde `origin/main`. | | `pnpm changed:lanes` | Muestra las vías arquitectónicas activadas por las diferencias respecto a `origin/main`. | | `pnpm check:changed` | Clasifica las vías modificadas antes de elegir la ejecución. Los planes que solo afectan a la documentación, sin cambios y con pocos metadatos permanecen locales cuando las dependencias están listas; los planes con ejecución en abanico de comprobación de tipos/lint, otras vías pesadas o dependencias locales ausentes se delegan a Crabbox/Testbox fuera de CI. No ejecuta Vitest; se debe usar `pnpm test:changed` o `pnpm test ` como prueba. | ## 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