Test

• Kit completo per i test (suite, live, Docker): Test
• Validazione degli aggiornamenti e dei pacchetti dei plugin: Test di aggiornamenti e plugin

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:

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 <path-or-filter> 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 <path-or-filter>.
• 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 <local-heavy-check command>: 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.

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 <label> <scenario> al container e decodificarlo con scripts/lib/openclaw-e2e-instance.sh; gli script con più directory home possono passare docker_e2e_test_state_function_b64 e chiamare openclaw_test_state_create <label> <scenario> in ciascun flusso. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json scrive un file di ambiente dell'host importabile (il -- prima di create impedisce ai runtime Node più recenti di interpretare --env-file come un flag di Node). Le corsie che avviano un Gateway possono importare scripts/lib/openclaw-e2e-instance.sh per la risoluzione dell'entrypoint, l'avvio del mock OpenAI, l'esecuzione in primo piano o in background, i controlli di disponibilità, l'esportazione delle variabili di ambiente dello stato, i dump dei log e la pulizia dei processi.

Corsie di Control UI, TUI ed estensioni

• E2E con Control UI simulata: pnpm test:ui:e2e esegue la corsia Vitest + Playwright che avvia la Control UI Vite e pilota una pagina Chromium reale usando un WebSocket Gateway simulato. I test si trovano in ui/src/**/*.e2e.test.ts; le simulazioni e i controlli condivisi si trovano in ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e include questa corsia. Le esecuzioni degli agenti usano Testbox/Crabbox per impostazione predefinita, inclusa la verifica mirata; usare 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 come ripiego locale esplicito.
• Test PTY della TUI: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts esegue la corsia PTY veloce con backend simulato. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 oppure pnpm tui:pty:test:watch --mode local esegue lo smoke test più lento di tui --local, che simula solo l'endpoint esterno del modello. Verificare testo visibile stabile o chiamate alle fixture, non snapshot ANSI grezzi.
• pnpm test:extensions e pnpm test extensions eseguono tutti gli shard delle estensioni/dei plugin. I plugin di canale pesanti, il plugin del browser e OpenAI vengono eseguiti come shard dedicati; gli altri gruppi di plugin restano raggruppati. pnpm test extensions/<id> esegue la corsia di un singolo plugin incluso.
• I file sorgente con test adiacenti vengono associati a questi ultimi prima di ricorrere a glob di directory più ampi. Le modifiche agli helper in src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers e src/plugins/contracts usano un grafo locale delle importazioni per eseguire i test che li importano, anziché eseguire indiscriminatamente ogni shard quando il percorso delle dipendenze è preciso.
• Le destinazioni delle directory dei contratti si distribuiscono sulle rispettive corsie: pnpm test src/channels/plugins/contracts esegue le quattro configurazioni dei contratti di canale e pnpm test src/plugins/contracts esegue la configurazione dei contratti dei plugin, poiché i progetti generici channels/plugins escludono contracts/**.
• auto-reply è suddiviso in tre configurazioni dedicate (core, top-level, reply), così l'infrastruttura di test delle risposte non prevale sui test più leggeri di stato, token e helper di primo livello.
• I file di test selezionati di plugin-sdk e commands vengono instradati attraverso corsie leggere dedicate che mantengono solo test/setup.ts, lasciando i casi che richiedono maggiormente il runtime nelle corsie esistenti.
• La configurazione Vitest di base usa per impostazione predefinita pool: "threads" e isolate: false, con il runner condiviso non isolato abilitato in tutte le configurazioni del repository.
• pnpm test:channels esegue vitest.channels.config.ts.

Gateway ed E2E

• L'integrazione del Gateway è facoltativa: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test oppure pnpm test:gateway.
• pnpm test:e2e: aggregato E2E del repository = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: smoke test end-to-end del Gateway (associazione WS/HTTP/Node con più istanze). Usa per impostazione predefinita threads + isolate: false con worker adattivi in vitest.e2e.config.ts; regolare con OPENCLAW_E2E_WORKERS=<n> e abilitare i log dettagliati con OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: test live dei provider (Claude/Minimax/DeepSeek/z.ai/ecc., controllati da *.live.test.ts). Richiede chiavi API e LIVE=1 (oppure OPENCLAW_LIVE_TEST=1) per non essere ignorato; output dettagliato con OPENCLAW_LIVE_TEST_QUIET=0.

Suite Docker completa (pnpm test:docker:all)

Crea l'immagine condivisa per i test live, impacchetta OpenClaw una sola volta come tarball npm, crea o riutilizza un'immagine runner Node/Git essenziale e un'immagine funzionale che installa il tarball in /app, quindi esegue le corsie di smoke test Docker tramite uno scheduler ponderato. scripts/package-openclaw-for-docker.mjs è l'unico strumento locale/CI per creare il pacchetto e convalida il tarball insieme a dist/postinstall-inventory.json prima che Docker lo utilizzi.

• Immagine essenziale (OPENCLAW_DOCKER_E2E_BARE_IMAGE): corsie per programma di installazione, aggiornamento e dipendenze dei plugin; monta il tarball precompilato invece delle sorgenti del repository copiate.
• Immagine funzionale (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): corsie della normale funzionalità dell'applicazione compilata.
• Definizioni delle corsie: scripts/lib/docker-e2e-scenarios.mjs. Pianificatore: scripts/lib/docker-e2e-plan.mjs. Esecutore: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json genera il piano CI gestito dallo scheduler (corsie, tipi di immagine, requisiti di pacchetto/immagine live, scenari di stato, controlli delle credenziali) senza creare o eseguire Docker.

Parametri di pianificazione (variabili d'ambiente, valori predefiniti tra parentesi):

Il modello delle variabili d'ambiente per i limiti delle risorse è OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (nome della risorsa in maiuscolo, caratteri non alfanumerici convertiti in _).

Altro comportamento: per impostazione predefinita, il runner esegue i controlli preliminari di Docker, rimuove i container E2E obsoleti di OpenClaw, condivide le cache degli strumenti CLI dei provider tra corsie compatibili e interrompe la pianificazione di nuove corsie nel pool dopo il primo errore, a meno che non sia impostato OPENCLAW_DOCKER_ALL_FAIL_FAST=0. Se una corsia supera il limite effettivo di peso/risorse su un host con basso parallelismo, può comunque avviarsi da un pool vuoto ed essere eseguita da sola finché non libera capacità. I log per corsia, summary.json, failures.json e le tempistiche delle fasi vengono scritti in .artifacts/docker-tests/<run-id>/; usa pnpm test:docker:timings <summary.json> per individuare le corsie lente e pnpm test:docker:rerun <run-id|summary.json|failures.json> per stampare comandi economici per riesecuzioni mirate.

Corsie Docker rilevanti

Gate locale per le PR

Per i controlli locali di gate/integrazione delle PR, esegui:

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

Se pnpm test presenta errori intermittenti su un host sotto carico, eseguilo nuovamente una volta prima di considerarli una regressione, quindi isola il problema con pnpm test <path/to/test>. Per gli host con memoria limitata:

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

Strumenti per le prestazioni dei test

• pnpm test:perf:imports: abilita i report di Vitest sulla durata e sulla ripartizione delle importazioni, continuando a usare l’instradamento per corsie con ambito definito per destinazioni esplicite di file/directory. pnpm test:perf:imports:changed limita la stessa profilazione ai file modificati rispetto a origin/main.
• pnpm test:perf:changed:bench -- --ref <git-ref> confronta le prestazioni del percorso instradato in modalità modifiche con l’esecuzione nativa del progetto radice per la stessa differenza Git già sottoposta a commit; pnpm test:perf:changed:bench -- --worktree misura le prestazioni dell’insieme di modifiche attuale dell’albero di lavoro senza richiedere prima un commit.
• pnpm test:perf:profile:main scrive un profilo CPU per il thread principale di Vitest (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner scrive profili CPU e heap per l’esecutore dei test unitari (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: esegue in serie ogni configurazione foglia di Vitest dell’intera suite e scrive i dati raggruppati sulla durata, oltre agli artefatti JSON e di log per ciascuna configurazione. Per impostazione predefinita, i report dell’intera suite isolano i file, affinché i grafi dei moduli conservati e le pause di GC dovute ai file precedenti non siano addebitati alle asserzioni successive; passa -- --no-isolate solo quando intendi profilare deliberatamente l’accumulo nel worker condiviso. L’agente per le prestazioni dei test usa questo risultato come riferimento iniziale prima di tentare correzioni ai test lenti. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json confronta i report raggruppati dopo una modifica incentrata sulle prestazioni.
• Le esecuzioni suddivise in shard complete, delle estensioni e basate su un modello di inclusione aggiornano i dati locali sulle tempistiche in .artifacts/vitest-shard-timings.json; le successive esecuzioni dell’intera configurazione usano queste tempistiche per bilanciare gli shard lenti e veloci. Gli shard CI basati su un modello di inclusione aggiungono il nome dello shard alla chiave delle tempistiche, mantenendo visibili le tempistiche degli shard filtrati senza sostituire i dati sulle tempistiche dell’intera configurazione. Imposta OPENCLAW_TEST_PROJECTS_TIMINGS=0 per ignorare l’artefatto locale delle tempistiche.

Benchmark

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

Onboarding E2E (Docker)

Facoltativo; necessario solo per i test rapidi dell’onboarding in container. Flusso completo di avvio a freddo in un container Linux pulito:

scripts/e2e/onboard-docker.sh

Pilota la procedura guidata interattiva tramite uno pseudo-TTY, verifica i file di configurazione, dell’area di lavoro e della sessione, quindi avvia il Gateway ed esegue openclaw health.

Test rapido dell’importazione QR (Docker)

Verifica che l’helper di runtime QR mantenuto venga caricato con i runtime Docker Node supportati (Node 24 predefinito, compatibile con Node 22):

pnpm test:docker:qr

Correlati

• Test
• Test in ambiente reale
• Test di aggiornamenti e Plugin