Test

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

Impostazioni predefinite dell'agente

Le sessioni dell'agente eseguono localmente uno o pochi test mirati e controlli statici poco onerosi solo per sorgenti attendibili e quando l'installazione esistente delle dipendenze è pronta. Non eseguire mai localmente gli strumenti di un repository non attendibile. Suite più ampie, gate delle modifiche con esecuzione distribuita di typecheck/lint, build, Docker, corsie dei pacchetti, E2E, prove live e validazione multipiattaforma vengono eseguiti in remoto tramite Crabbox. Per le prove onerose di manutentori attendibili, l'impostazione predefinita è Blacksmith Testbox. Il flusso di lavoro Testbox configurato carica le credenziali, pertanto il codice non attendibile di contributori o fork deve utilizzare la CI del fork senza segreti oppure un Crabbox AWS diretto e sanificato.

Non eseguire il preriscaldamento in previsione del lavoro. Acquisire il backend solo quando il primo comando oneroso è pronto, riutilizzare l'id tbx_... restituito per i comandi onerosi successivi, sincronizzare il checkout corrente a ogni esecuzione e arrestarlo prima del passaggio di consegne.

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 ai sorgenti 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 provoca un arresto preventivo 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 prove di rilascio.

I comandi di test locali riportati di seguito sono destinati ai flussi di lavoro umani e alle prove limitate dell'agente. L'indisponibilità del provider remoto deve essere segnalata; non autorizza l'esecuzione silenziosa di un gate locale ampio.

Per le prove onerose non attendibili, eseguire il riscaldamento solo quando necessario con --provider aws. Ogni esecuzione deve impostare CRABBOX_ENV_ALLOW=CI, passare --provider aws --no-hydrate e utilizzare un nuovo HOME remoto temporaneo prima di installare le dipendenze o eseguire i test. Utilizzare un lease appena riscaldato dedicato a quella sorgente non attendibile; non riutilizzare mai un lease attendibile o precedentemente caricato con credenziali. Avviare un binario Crabbox attendibile installato da un checkout main pulito e attendibile e recuperare solo la PR remota con --fresh-pr; non eseguire mai localmente il wrapper o la configurazione del checkout non attendibile. Rimuovere CRABBOX_AWS_INSTANCE_PROFILE e interrompere preventivamente l'operazione a meno che il valore risolto aws.instanceProfile non sia vuoto. Prima di qualsiasi installazione/test, utilizzare 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 git rev-parse HEAD corrisponda allo SHA completo dell'head della PR esaminata. Associare il lease a tale SHA e arrestarlo/riscaldarlo nuovamente quando l'head cambia. Caricare il file attendibile scripts/crabbox-untrusted-bootstrap.sh dal checkout main pulito insieme a --fresh-pr; installa le versioni fissate di Node/pnpm, verifica lo SHA e il pin del gestore di pacchetti, isola HOME, installa le dipendenze, quindi esegue il test richiesto. Se il broker non può dimostrare l'assenza di un ruolo o non esiste alcuna PR remota, utilizzare la CI del fork senza segreti. Non utilizzare hydrate-github, --no-sync o un flusso di lavoro Testbox caricato con credenziali. Rimuovere tutte le sostituzioni CRABBOX_TAILSCALE*, imporre --network public --tailscale=false, cancellare i flag del nodo di uscita/LAN e richiedere che crabbox inspect segnali una rete pubblica senza stato Tailscale prima di caricare qualsiasi script.

Ordine locale ordinario

1. pnpm test:changed per la prova Vitest nell'ambito delle modifiche.
2. pnpm test <path-or-filter> per un 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:

• Prova mirata e limitata con dipendenze pronte: node scripts/run-vitest.mjs <path-or-filter>.
• Controllo delle modifiche con classificazione preliminare: node scripts/check-changed.mjs; i piani relativi solo alla documentazione, senza modifiche o con pochi metadati restano locali quando le dipendenze sono pronte, mentre i piani onerosi o con dipendenze mancanti vengono delegati a Testbox.
• Prova ampia esplicita con lease mantenuto: 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, in modo che pnpm venga eseguito all'interno di Testbox.
• Il valore finale exitCode del wrapper e il JSON delle tempistiche costituiscono il risultato del comando. Un'esecuzione delegata di Blacksmith GitHub Actions può mostrare cancelled dopo un comando SSH riuscito perché Testbox viene arrestato dall'esterno dell'azione keepalive; controllare 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 nel worktree corrente anziché nella directory Git comune per comandi quali pnpm check:changed e pnpm test ... mirati. Utilizzarlo solo su host locali ad alta capacità quando si eseguono intenzionalmente controlli indipendenti tra worktree collegati.

Comandi principali

Le esecuzioni del wrapper dei test terminano con un breve riepilogo [test] passed|failed|skipped ... in ...; la riga della durata di Vitest resta il dettaglio per singolo shard.

Stato condiviso dei test e helper dei processi

• src/test-utils/openclaw-test-state.ts: utilizzare da Vitest quando un test richiede un HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, una fixture di configurazione, un workspace, una directory dell'agente o un archivio dei profili di autenticazione isolati.
• pnpm test:env-mutations:report: report non bloccante dei test/delle infrastrutture che modificano direttamente HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR o le relative chiavi di ambiente. Utilizzarlo per individuare i candidati alla migrazione verso l'helper dello stato condiviso dei test.
• test/helpers/openclaw-test-instance.ts: test E2E a livello di processo che richiedono in un unico punto un Gateway in esecuzione, l'ambiente CLI, l'acquisizione dei log e la pulizia.
• Le corsie E2E Docker/Bash che caricano 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ù home possono passare docker_e2e_test_state_function_b64 e chiamare openclaw_test_state_create <label> <scenario> in ogni flusso. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json scrive un file di ambiente dell'host caricabile come sorgente (il -- prima di create impedisce ai runtime Node più recenti di trattare --env-file come un flag Node). Le corsie che avviano un Gateway possono caricare scripts/lib/openclaw-e2e-instance.sh per la risoluzione dell'entrypoint, l'avvio simulato di OpenAI, l'avvio in primo piano/in background, le sonde di disponibilità, l'esportazione dell'ambiente di stato, i dump dei log e la pulizia dei processi.

Corsie di Control UI, TUI ed estensioni

• E2E simulato della Control UI: pnpm test:ui:e2e esegue la corsia Vitest + Playwright che avvia la Control UI Vite e pilota una pagina Chromium reale rispetto a un WebSocket del 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 per impostazione predefinita Testbox/Crabbox, 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 rapida con backend simulato. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 o pnpm tui:pty:test:watch --mode local esegue lo smoke test tui --local più lento, 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 tali test 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 in modo generalizzato 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 dei canali 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) affinché l'infrastruttura di test delle risposte non domini i più leggeri test di stato/token/helper di primo livello.
• I file di test plugin-sdk e commands selezionati vengono instradati attraverso corsie leggere dedicate che mantengono solo test/setup.ts, lasciando i casi più onerosi per 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 nelle 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 o pnpm test:gateway.
• pnpm test:e2e: aggregazione 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>, log dettagliati con OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: test in produzione dei provider (Claude/Minimax/DeepSeek/z.ai/ecc., subordinati a *.live.test.ts). Richiede chiavi API e LIVE=1 (o 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 in produzione, impacchetta OpenClaw una sola volta come tarball npm, crea/riutilizza un'immagine runner essenziale Node/Git e un'immagine funzionale che installa tale tarball in /app, quindi esegue le corsie degli smoke test Docker tramite uno scheduler ponderato. scripts/package-openclaw-for-docker.mjs è l'unico strumento locale/CI per la creazione del pacchetto e convalida il tarball più dist/postinstall-inventory.json prima che Docker lo utilizzi.

• Immagine essenziale (OPENCLAW_DOCKER_E2E_BARE_IMAGE): corsie per programma di installazione/aggiornamento/dipendenze dei Plugin; monta il tarball precompilato invece delle sorgenti del repository copiate.
• Immagine funzionale (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): corsie delle normali funzionalità dell'app 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, necessità di pacchetti/immagini per test in produzione, scenari di stato, verifiche delle credenziali) senza creare né 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 accorpati in _).

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

Lane Docker rilevanti

Gate PR locale

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

• 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 sovraccarico, rieseguirlo una volta prima di considerarlo una regressione, quindi isolarlo 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 sulla durata delle importazioni e sulla loro ripartizione in Vitest, continuando a usare l'instradamento per lane 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> esegue il benchmark del percorso instradato in modalità modifiche rispetto all'esecuzione nativa del progetto radice per la stessa differenza git sottoposta a commit; pnpm test:perf:changed:bench -- --worktree esegue il benchmark dell'insieme di modifiche dell'albero di lavoro corrente senza prima creare 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 + heap per il runner 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 Vitest della suite completa e scrive i dati raggruppati sulla durata, oltre agli artefatti JSON/log per configurazione. Per impostazione predefinita, i report della suite completa isolano i file affinché i grafi dei moduli conservati e le pause del GC dovute ai file precedenti non vengano attribuiti alle asserzioni successive; passare -- --no-isolate solo quando si profila intenzionalmente l'accumulo nei worker condivisi. Il Test Performance Agent lo usa come riferimento di base prima di tentare correzioni dei 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 complete, delle estensioni e degli shard basati su pattern di inclusione aggiornano i dati locali sulle tempistiche in .artifacts/vitest-shard-timings.json; le successive esecuzioni dell'intera configurazione usano tali tempistiche per bilanciare gli shard lenti e veloci. Gli shard CI basati su pattern di inclusione aggiungono il nome dello shard alla chiave delle tempistiche, mantenendo visibili le tempistiche degli shard filtrati senza sostituire i dati delle tempistiche dell'intera configurazione. Impostare 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

E2E dell'onboarding (Docker)

Facoltativo; necessario solo per gli smoke test dell'onboarding in container. Flusso completo di avvio a freddo in un container Linux pulito:

scripts/e2e/onboard-docker.sh

Controlla 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.

Smoke test dell'importazione QR (Docker)

Garantisce che l'helper di runtime QR mantenuto venga caricato nei runtime Docker Node supportati (Node 24 predefinito, compatibile con Node 22):

pnpm test:docker:qr

Contenuti correlati

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