--- read_when: - Esecuzione o correzione dei test summary: Come eseguire i test localmente (vitest) e quando usare le modalità force/coverage title: Test x-i18n: generated_at: "2026-07-12T07:30:12Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 63806ea72da1579f4aa0b92c14a6d2d3e67990d6c10cb6d9b1b2bb4a63c8e140 source_path: reference/test.md workflow: 16 --- - Kit completo per i test (suite, live, Docker): [Test](/it/help/testing) - Validazione degli aggiornamenti e dei pacchetti dei plugin: [Test di aggiornamenti e plugin](/it/help/testing-updates-plugins) ## Impostazione predefinita dell'agente Le sessioni dell'agente eseguono da remoto, tramite Crabbox, i test e le convalide ad alta intensità di calcolo. Per il codice attendibile dei manutentori viene usato per impostazione predefinita Blacksmith Testbox. Il flusso di lavoro Testbox configurato carica le credenziali, pertanto il codice non attendibile di collaboratori o fork deve invece usare la CI del fork senza segreti oppure un'istanza AWS Crabbox diretta e sanificata. Quando è probabile che un'attività su codice attendibile richieda test o verifiche onerose, esegui immediatamente il preriscaldamento in una sessione di comandi in background, continua a lavorare durante il caricamento, riutilizza l'ID `tbx_...` restituito, sincronizza il checkout corrente a ogni esecuzione e arrestalo prima del passaggio di consegne: ```bash node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json ``` Dopo il primo riutilizzo riuscito, il wrapper registra la base del lease, le dipendenze e l'impronta digitale del flusso di lavoro Testbox in `.crabbox/testbox-leases/`. Le modifiche limitate al codice sorgente continuano a riutilizzare l'ambiente preriscaldato. Una modifica alla base di merge, al lockfile, all'input del gestore di pacchetti, al wrapper o al flusso di lavoro Testbox causa un arresto sicuro e richiede un nuovo lease. Ogni esecuzione continua comunque a sincronizzare il checkout corrente. `OPENCLAW_TESTBOX_ALLOW_STALE=1` è destinato esclusivamente alla diagnostica intenzionale, non alle verifiche di rilascio. I comandi di test locali riportati di seguito sono destinati ai flussi di lavoro umani o a un fallback esplicito dell'agente richiesto dall'utente. L'indisponibilità del provider remoto deve essere segnalata; non autorizza l'esecuzione silenziosa di un controllo locale esteso. Per il codice non attendibile, esegui il preriscaldamento con `--provider aws`. Ogni esecuzione deve impostare `CRABBOX_ENV_ALLOW=CI`, passare `--provider aws --no-hydrate` e usare una nuova directory `HOME` remota temporanea prima di installare le dipendenze o eseguire i test. Usa un lease appena preriscaldato e dedicato a quella sorgente non attendibile; non riutilizzare mai un lease attendibile o caricato in precedenza. Avvia un binario Crabbox attendibile già installato da un checkout pulito e attendibile di `main` e recupera solo la PR remota con `--fresh-pr`; non eseguire mai localmente il wrapper o la configurazione del checkout non attendibile. Rimuovi l'impostazione di `CRABBOX_AWS_INSTANCE_PROFILE` e applica un arresto sicuro a meno che il valore risolto di `aws.instanceProfile` non sia vuoto. Prima di qualsiasi installazione o test, usa strumenti attendibili con percorso assoluto per richiedere un token IMDSv2, dimostrare che l'endpoint delle credenziali IAM restituisce 404 e verificare che il valore remoto di `git rev-parse HEAD` corrisponda allo SHA completo dell'HEAD della PR revisionata. Associa il lease a tale SHA e arrestalo oppure preriscaldalo nuovamente quando l'HEAD cambia. Carica lo script attendibile `scripts/crabbox-untrusted-bootstrap.sh` da un `main` pulito insieme a `--fresh-pr`; installa le versioni bloccate di Node/pnpm, verifica lo SHA e il blocco del gestore di pacchetti, isola `HOME`, installa le dipendenze e quindi esegue il test richiesto. Se il broker non può dimostrare l'assenza di un ruolo o non esiste una PR remota, usa la CI del fork senza segreti. Non usare `hydrate-github`, `--no-sync` o un flusso di lavoro Testbox con credenziali caricate. Rimuovi tutte le impostazioni sostitutive `CRABBOX_TAILSCALE*`, forza `--network public --tailscale=false`, azzera i flag del nodo di uscita/LAN e richiedi che `crabbox inspect` segnali una rete pubblica senza stato Tailscale prima di caricare qualsiasi script. ## Ordine locale di routine 1. `pnpm test:changed` per la verifica Vitest limitata alle modifiche. 2. `pnpm test ` per un singolo file, una directory o una destinazione esplicita. 3. `pnpm test` solo quando è intenzionalmente necessaria l'intera suite Vitest locale. In un worktree Codex o in un checkout collegato/sparso, gli agenti evitano l'esecuzione locale diretta di `pnpm test*` / `pnpm check*` / `pnpm crabbox:run`: - Fallback locale richiesto esplicitamente dall'utente per un file di piccole dimensioni: `node scripts/run-vitest.mjs `. - Controlli sulle modifiche o verifiche estese: `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`, affinché pnpm venga eseguito all'interno di Testbox. - L'`exitCode` finale del wrapper e il JSON delle tempistiche costituiscono il risultato del comando. Un'esecuzione delegata di Blacksmith GitHub Actions può risultare `cancelled` dopo un comando SSH riuscito, perché Testbox viene arrestata dall'esterno dell'azione di mantenimento attivo; controlla il riepilogo del wrapper e l'output del comando prima di considerarlo un errore. - `OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree `: mantiene la serializzazione dei controlli onerosi all'interno del worktree corrente anziché nella directory Git comune per comandi quali `pnpm check:changed` e `pnpm test ...` mirati. Usalo solo su host locali ad alta capacità quando esegui intenzionalmente controlli indipendenti tra worktree collegati. ## Comandi principali Le esecuzioni del wrapper di test terminano con un breve riepilogo `[test] passed|failed|skipped ... in ...`; la riga della durata di Vitest rimane il dettaglio relativo al singolo shard. | Comando | Funzione | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | Le destinazioni esplicite di file/directory vengono instradate attraverso corsie Vitest con ambito specifico. Le esecuzioni senza destinazione verificano l'intera suite: i gruppi fissi di shard vengono espansi in configurazioni foglia per l'esecuzione parallela locale e il fan-out previsto degli shard viene stampato prima dell'avvio. Il gruppo delle estensioni viene sempre espanso in configurazioni di shard per singola estensione anziché in un unico enorme processo del progetto radice. | | `pnpm test:changed` | Esecuzione intelligente ed economica dei test relativi alle modifiche: destinazioni precise ricavate dalle modifiche dirette ai test, dai file `*.test.ts` adiacenti, dalle mappature esplicite del codice sorgente e dal grafo locale delle importazioni. Le modifiche estese, di configurazione o dei pacchetti vengono ignorate, salvo che possano essere associate a test precisi. | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | Esecuzione esplicita ed estesa dei test relativi alle modifiche; usala quando una modifica a un'infrastruttura di test, una configurazione o un pacchetto deve ricorrere al comportamento più ampio di Vitest per i test delle modifiche. | | `pnpm test:force` | Libera la porta configurata del Gateway OpenClaw (valore predefinito `18789`), quindi esegue l'intera suite con una porta Gateway isolata, affinché i test del server non entrino in conflitto con un'istanza in esecuzione. | | `pnpm test:coverage` | Genera un rapporto informativo sulla copertura V8 per la corsia di unit test predefinita (`vitest.unit.config.ts`); non vengono applicate soglie di copertura. | | `pnpm test:coverage:changed` | Copertura degli unit test limitata ai file modificati rispetto a `origin/main`. | | `pnpm changed:lanes` | Mostra le corsie architetturali attivate dalle differenze rispetto a `origin/main`. | | `pnpm check:changed` | Delega per impostazione predefinita a Crabbox/Testbox al di fuori della CI, quindi esegue nel processo figlio remoto il controllo intelligente delle modifiche: formattazione, controllo dei tipi, lint e comandi di protezione per le corsie interessate. Non esegue Vitest; usa `pnpm test:changed` o `pnpm test ` per la verifica tramite test. | ## Stato di test condiviso e helper dei processi - `src/test-utils/openclaw-test-state.ts`: usalo da Vitest quando un test necessita di una directory `HOME` isolata, di `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, di una fixture di configurazione, di uno spazio di lavoro, di una directory dell'agente o di un archivio dei profili di autenticazione. - `pnpm test:env-mutations:report`: rapporto non bloccante sui test e sulle infrastrutture di test che modificano direttamente `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_WORKSPACE_DIR` o chiavi di ambiente correlate. Usalo per individuare i candidati alla migrazione verso l'helper condiviso dello stato di test. - `test/helpers/openclaw-test-instance.ts`: per i test E2E a livello di processo che richiedono un Gateway in esecuzione, l'ambiente della CLI, l'acquisizione dei log e la pulizia in un'unica posizione. - Le corsie E2E Docker/Bash che importano `scripts/lib/docker-e2e-image.sh` possono passare `docker_e2e_test_state_shell_b64