Tests

• Volledige testkit (suites, live, Docker): Testen
• Validatie van updates en pluginpakketten: Updates en plugins testen

Standaardinstelling voor agents

Agentsessies voeren alleen lokaal één/enkele gerichte tests en goedkope statische controles uit voor vertrouwde broncode en wanneer de bestaande installatie van afhankelijkheden gereed is. Voer nooit lokaal tooling uit een niet-vertrouwde repository uit. Grotere suites, gewijzigde gates met uitwaaierende typecheck-/linttaken, builds, Docker, pakketlanes, E2E, live-bewijs en platformoverschrijdende validatie worden extern uitgevoerd via Crabbox. Voor zwaar bewijs van vertrouwde maintainers wordt standaard Blacksmith Testbox gebruikt. De geconfigureerde Testbox-workflow laadt inloggegevens, dus code van niet-vertrouwde bijdragers of forks moet in plaats daarvan fork-CI zonder secrets of een opgeschoonde directe AWS Crabbox gebruiken.

Warm niet vooraf op voor verwacht werk. Verkrijg de backend pas wanneer de eerste zware opdracht gereed is, hergebruik de geretourneerde tbx_...-id voor latere zware opdrachten, synchroniseer bij elke uitvoering de huidige checkout en stop deze vóór de overdracht.

Na het eerste geslaagde hergebruik registreert de wrapper de basis-, afhankelijkheids- en Testbox-workflowvingerafdruk van de lease onder .crabbox/testbox-leases/. Wijzigingen die alleen de broncode betreffen, blijven de opgewarmde box hergebruiken. Een gewijzigde merge-base, lockfile, pakketmanagerinvoer, wrapper of Testbox-workflow faalt gesloten en vereist een nieuwe lease. Bij elke uitvoering wordt de huidige checkout nog steeds gesynchroniseerd. OPENCLAW_TESTBOX_ALLOW_STALE=1 is alleen bedoeld voor doelbewuste diagnostiek, niet voor releasebewijs.

De onderstaande lokale testopdrachten zijn bedoeld voor menselijke workflows en begrensd agentbewijs. Onbeschikbaarheid van de externe provider moet worden gemeld; dit geeft geen toestemming om stilzwijgend een brede lokale gate uit te voeren.

Warm voor zwaar niet-vertrouwd bewijs pas op met --provider aws. Elke uitvoering moet CRABBOX_ENV_ALLOW=CI instellen, --provider aws --no-hydrate doorgeven en een nieuwe tijdelijke externe HOME gebruiken voordat afhankelijkheden worden geïnstalleerd of tests worden uitgevoerd. Gebruik een nieuw opgewarmde lease die uitsluitend voor die niet-vertrouwde bron is bestemd; hergebruik nooit een vertrouwde of eerder met inloggegevens geladen lease. Start een geïnstalleerde vertrouwde Crabbox- binary vanuit een schone vertrouwde main-checkout en haal alleen de externe PR op met --fresh-pr; voer de wrapper of configuratie van de niet-vertrouwde checkout nooit lokaal uit. Verwijder CRABBOX_AWS_INSTANCE_PROFILE uit de omgeving en faal gesloten tenzij de opgeloste aws.instanceProfile leeg is. Gebruik vóór elke installatie/test vertrouwde tools met absolute paden om een IMDSv2-token te vereisen, aan te tonen dat het eindpunt voor IAM-inloggegevens 404 retourneert en te verifiëren dat de externe git rev-parse HEAD gelijk is aan de volledige beoordeelde SHA van de PR-head. Koppel de lease aan die SHA en stop/warm opnieuw op wanneer de head wijzigt. Upload de vertrouwde scripts/crabbox-untrusted-bootstrap.sh vanuit een schone main naast --fresh-pr; deze installeert vastgezette Node/pnpm-versies, verifieert de SHA en de pakketmanagerpin, isoleert HOME, installeert afhankelijkheden en voert vervolgens de gevraagde test uit. Als de broker niet kan aantonen dat er geen rol is of dat er geen externe PR bestaat, gebruik dan fork-CI zonder secrets. Gebruik geen hydrate-github, --no-sync of een Testbox-workflow die met inloggegevens is geladen. Verwijder alle CRABBOX_TAILSCALE*-overrides uit de omgeving, dwing --network public --tailscale=false af, wis exit-node-/LAN-vlaggen en vereis dat crabbox inspect openbare netwerktoegang zonder Tailscale-status rapporteert voordat een script wordt geüpload.

Gebruikelijke lokale volgorde

1. pnpm test:changed voor Vitest-bewijs binnen de gewijzigde scope.
2. pnpm test <path-or-filter> voor één bestand, map of expliciet doel.
3. pnpm test alleen wanneer je doelbewust de volledige lokale Vitest-suite nodig hebt.

In een Codex-worktree of gekoppelde/sparse checkout vermijden agents directe lokale pnpm test* / pnpm check* / pnpm crabbox:run:

• Begrensd gericht bewijs met gereedstaande afhankelijkheden: node scripts/run-vitest.mjs <path-or-filter>.
• Gewijzigde controle met classificatie als eerste stap: node scripts/check-changed.mjs; plannen die alleen documentatie betreffen, geen wijzigingen bevatten of weinig metadata omvatten, blijven lokaal wanneer afhankelijkheden gereed zijn, terwijl zware plannen of plannen met ontbrekende afhankelijkheden aan Testbox worden gedelegeerd.
• Expliciet breed bewijs met behouden lease: 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, zodat pnpm binnen Testbox wordt uitgevoerd.
• De laatste exitCode en timing-JSON van de wrapper vormen het opdrachtresultaat. Een gedelegeerde Blacksmith GitHub Actions-uitvoering kan na een geslaagde SSH-opdracht cancelled tonen omdat de Testbox buiten de keepalive-action wordt gestopt; controleer de wrappersamenvatting en opdrachtuitvoer voordat je dit als een fout beschouwt.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: houdt de serialisatie van zware controles binnen de huidige worktree in plaats van de gemeenschappelijke Git-map voor opdrachten zoals pnpm check:changed en gerichte pnpm test .... Gebruik dit alleen op lokale hosts met hoge capaciteit wanneer je doelbewust onafhankelijke controles uitvoert in gekoppelde worktrees.

Kernopdrachten

Uitvoeringen van de testwrapper eindigen met een korte [test] passed|failed|skipped ... in ...-samenvatting; de eigen duurregel van Vitest blijft het detail per shard.

Gedeelde teststatus en proceshelpers

• src/test-utils/openclaw-test-state.ts: gebruik vanuit Vitest wanneer een test een geïsoleerde HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, configuratiefixture, werkruimte, agentmap of opslag voor authenticatieprofielen nodig heeft.
• pnpm test:env-mutations:report: niet-blokkerend rapport van tests/harnassen die HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR of gerelateerde omgevingssleutels rechtstreeks wijzigen. Gebruik dit om migratiekandidaten voor de gedeelde teststatushelper te vinden.
• test/helpers/openclaw-test-instance.ts: E2E-tests op procesniveau die op één plek een actieve Gateway, CLI-omgeving, logregistratie en opschoning nodig hebben.
• Docker-/Bash-E2E-lanes die scripts/lib/docker-e2e-image.sh sourcen, kunnen docker_e2e_test_state_shell_b64 <label> <scenario> aan de container doorgeven en dit decoderen met scripts/lib/openclaw-e2e-instance.sh; scripts met meerdere home-mappen kunnen docker_e2e_test_state_function_b64 doorgeven en in elke flow openclaw_test_state_create <label> <scenario> aanroepen. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json schrijft een sourcebaar hostomgevingsbestand (de -- vóór create voorkomt dat nieuwere Node-runtimes --env-file als een Node-vlag behandelen). Lanes die een Gateway starten, kunnen scripts/lib/openclaw-e2e-instance.sh sourcen voor het oplossen van het entrypoint, een nagebootste OpenAI-start, starten op de voorgrond/achtergrond, gereedheidscontroles, export van statusomgevingsvariabelen, logdumps en procesopschoning.

Control UI-, TUI- en extensielanes

• E2E met gesimuleerde Control UI: pnpm test:ui:e2e voert de Vitest- en Playwright-lane uit die de Vite Control UI start en een echte Chromium-pagina aanstuurt via een gesimuleerde Gateway-WebSocket. Tests staan in ui/src/**/*.e2e.test.ts; gedeelde simulaties en besturingselementen staan in ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e omvat deze lane. Agent-uitvoeringen gebruiken standaard Testbox/Crabbox, inclusief gerichte verificatie; gebruik 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 alleen als expliciete lokale terugvaloptie.
• TUI-PTY-tests: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts voert de snelle PTY-lane met een nepbackend uit. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 of pnpm tui:pty:test:watch --mode local voert de tragere tui --local-smoketest uit, die alleen het externe modeleindpunt simuleert. Controleer stabiele zichtbare tekst of fixture-aanroepen, geen onbewerkte ANSI-snapshots.
• pnpm test:extensions en pnpm test extensions voeren alle shards voor extensies/plugins uit. Zware kanaalplugins, de browserplugin en OpenAI worden als afzonderlijke shards uitgevoerd; andere plugingroepen blijven gebundeld. pnpm test extensions/<id> voert één lane voor een gebundelde plugin uit.
• Bronbestanden met tests op hetzelfde niveau worden eerst aan die tests gekoppeld, voordat wordt teruggevallen op bredere directoryglobs. Wijzigingen aan helpers onder src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers en src/plugins/contracts gebruiken een lokale importgraaf om importerendetests uit te voeren in plaats van elke shard breed uit te voeren wanneer het afhankelijkheidspad nauwkeurig is.
• Doelen voor contractdirectory's waaieren uit naar hun contractlanes: pnpm test src/channels/plugins/contracts voert de vier configuraties voor kanaalcontracten uit en pnpm test src/plugins/contracts voert de configuratie voor plugincontracten uit, omdat de generieke projecten channels/plugins contracts/** uitsluiten.
• auto-reply wordt opgesplitst in drie afzonderlijke configuraties (core, top-level, reply), zodat de antwoordharnas niet de lichtere status-, token- en helpertests op het hoogste niveau overheerst.
• Geselecteerde testbestanden van plugin-sdk en commands worden via afzonderlijke lichte lanes geleid die alleen test/setup.ts behouden, terwijl runtime-intensieve gevallen op hun bestaande lanes blijven.
• De basisconfiguratie van Vitest gebruikt standaard pool: "threads" en isolate: false, waarbij de gedeelde niet-geïsoleerde runner voor alle repoconfiguraties is ingeschakeld.
• pnpm test:channels voert vitest.channels.config.ts uit.

Gateway en E2E

• Gateway-integratie is opt-in: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test of pnpm test:gateway.
• pnpm test:e2e: geaggregeerde repo-E2E = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: end-to-end-smoketests voor de Gateway (koppeling van meerdere instanties via WS/HTTP/Node). Gebruikt standaard threads + isolate: false met adaptieve workers in vitest.e2e.config.ts; stel af met OPENCLAW_E2E_WORKERS=<n>, uitgebreide logboeken met OPENCLAW_E2E_VERBOSE=1.
• pnpm test:live: live providertests (Claude/Minimax/DeepSeek/z.ai/enzovoort, afgeschermd door *.live.test.ts). Vereist API-sleutels en LIVE=1 (of OPENCLAW_LIVE_TEST=1) om overslaan uit te schakelen; uitgebreide uitvoer met OPENCLAW_LIVE_TEST_QUIET=0.

Volledige Docker-suite (pnpm test:docker:all)

Bouwt de gedeelde live-testimage, verpakt OpenClaw eenmaal als een npm-tarball, bouwt/hergebruikt een kale Node/Git-runnerimage plus een functionele image die die tarball in /app installeert, en voert vervolgens Docker-smoketestlanes uit via een gewogen planner. scripts/package-openclaw-for-docker.mjs is de enige lokale/CI-pakketverpakker en valideert de tarball plus dist/postinstall-inventory.json voordat Docker deze gebruikt.

• Kale image (OPENCLAW_DOCKER_E2E_BARE_IMAGE): lanes voor installatieprogramma's, updates en plugin-afhankelijkheden; koppelt de vooraf gebouwde tarball aan in plaats van gekopieerde repobronnen.
• Functionele image (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): lanes voor normale functionaliteit van de gebouwde app.
• Lanedefinities: scripts/lib/docker-e2e-scenarios.mjs. Planner: scripts/lib/docker-e2e-plan.mjs. Uitvoerder: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json produceert het CI-plan dat door de planner wordt beheerd (lanes, imagetypen, behoeften aan pakketten/live-images, statusscenario's, controle van referenties) zonder Docker te bouwen of uit te voeren.

Planningsinstellingen (omgevingsvariabelen, standaardwaarden tussen haakjes):

Het patroon voor omgevingsvariabelen voor resourcelimieten is OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (resourcenaam in hoofdletters, niet-alfanumerieke tekens samengevoegd tot _).

Overig gedrag: de runner voert standaard een preflightcontrole van Docker uit, ruimt verouderde OpenClaw E2E-containers op, deelt caches van CLI-tools van providers tussen compatibele lanes en stopt na de eerste fout met het plannen van nieuwe gepoolde lanes, tenzij OPENCLAW_DOCKER_ALL_FAIL_FAST=0 is ingesteld. Als één lane de effectieve gewichts-/resourcelimiet op een host met lage paralleliteit overschrijdt, kan deze toch vanuit een lege pool starten en alleen worden uitgevoerd totdat er capaciteit vrijkomt. Logboeken per lane, summary.json, failures.json en fasetimings worden weggeschreven onder .artifacts/docker-tests/<run-id>/; gebruik pnpm test:docker:timings <summary.json> om trage lanes te onderzoeken en pnpm test:docker:rerun <run-id|summary.json|failures.json> om goedkope, gerichte opdrachten voor opnieuw uitvoeren af te drukken.

Opmerkelijke Docker-lanes

Lokale PR-gate

Voer voor lokale controles voor het landen/de gate van een PR het volgende uit:

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

Als pnpm test op een zwaar belaste host onregelmatig faalt, voer deze dan één keer opnieuw uit voordat je dit als een regressie beschouwt en isoleer het probleem vervolgens met pnpm test <path/to/test>. Voor hosts met beperkt geheugen:

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

Tools voor testprestaties

• pnpm test:perf:imports: schakelt rapportage van Vitest-importduur en importuitsplitsing in, terwijl gerichte laneroutering voor expliciete bestands-/mapdoelen behouden blijft. pnpm test:perf:imports:changed beperkt dezelfde profilering tot bestanden die sinds origin/main zijn gewijzigd.
• pnpm test:perf:changed:bench -- --ref <git-ref> benchmarkt het gerouteerde pad voor de modus met wijzigingen tegenover de native uitvoering van het hoofdproject voor dezelfde gecommitte git-diff; pnpm test:perf:changed:bench -- --worktree benchmarkt de huidige wijzigingenset in de worktree zonder deze eerst te committen.
• pnpm test:perf:profile:main schrijft een CPU-profiel voor de hoofdthread van Vitest (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner schrijft CPU- en heap-profielen voor de unit-runner (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: voert elke Vitest-leafconfiguratie van de volledige suite serieel uit en schrijft gegroepeerde duurgegevens plus JSON-/logboekartefacten per configuratie. Rapporten van de volledige suite isoleren standaard bestanden, zodat behouden modulegrafen en GC-pauzes van eerdere bestanden niet aan latere asserties worden toegerekend; geef -- --no-isolate alleen door wanneer je bewust accumulatie in gedeelde workers profileert. De Test Performance Agent gebruikt dit als basislijn voordat deze probeert trage tests te verbeteren. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json vergelijkt gegroepeerde rapporten na een prestatiegerichte wijziging.
• Uitvoeringen van volledige suites, extensies en shards met opnamepatronen werken lokale timinggegevens bij in .artifacts/vitest-shard-timings.json; latere uitvoeringen van volledige configuraties gebruiken die timings om trage en snelle shards in balans te brengen. CI-shards met opnamepatronen voegen de shardnaam toe aan de timingsleutel, waardoor gefilterde shardtimings zichtbaar blijven zonder timinggegevens van volledige configuraties te vervangen. Stel OPENCLAW_TEST_PROJECTS_TIMINGS=0 in om het lokale timingartefact te negeren.

Benchmarks

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 voor onboarding (Docker)

Optioneel; alleen nodig voor gecontaineriseerde rooktests voor onboarding. Volledige koudestartstroom in een schone Linux-container:

scripts/e2e/onboard-docker.sh

Bestuurt de interactieve wizard via een pseudo-tty, verifieert configuratie-, werkruimte- en sessiebestanden, start vervolgens de Gateway en voert openclaw health uit.

Rooktest voor QR-import (Docker)

Waarborgt dat de onderhouden QR-runtimehelper wordt geladen onder de ondersteunde Docker Node-runtimes (standaard Node 24, compatibel met Node 22):

pnpm test:docker:qr

Gerelateerd

• Testen
• Live testen
• Updates en plugins testen