Tests

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

Standaardinstelling voor agents

Agentsessies voeren alleen lokaal één of 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, pakkettaken, E2E, live bewijs en platformoverschrijdende validatie worden extern via Crabbox uitgevoerd. Zwaar bewijs voor vertrouwde maintainers wordt standaard via Blacksmith Testbox uitgevoerd. De geconfigureerde Testbox-workflow laadt aanmeldgegevens, dus niet-vertrouwde code van bijdragers of forks moet in plaats daarvan fork-CI zonder geheimen 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 succesvolle hergebruik registreert de wrapper de basis-, afhankelijkheids- en Testbox-workflowvingerafdruk van de lease onder .crabbox/testbox-leases/. Bij wijzigingen die alleen de broncode betreffen, wordt de opgewarmde box hergebruikt. Bij een gewijzigde samenvoegbasis, lockfile, invoer voor de pakketbeheerder, wrapper of Testbox-workflow wordt veilig gestopt en is een nieuwe lease vereist. 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 een externe provider moet worden gemeld; dit geeft geen toestemming om stilzwijgend een brede lokale gate uit te voeren.

Warm voor niet-vertrouwd zwaar 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 aan die niet-vertrouwde bron is toegewezen; hergebruik nooit een vertrouwde of eerder met aanmeldgegevens geladen lease. Start een geïnstalleerd, vertrouwd Crabbox- binair bestand 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 stop veilig tenzij de herleide 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 endpoint voor IAM-aanmeldgegevens 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 vastgepinde Node/pnpm, verifieert de SHA en de pin van de pakketbeheerder, isoleert HOME, installeert afhankelijkheden en voert daarna de aangevraagde test uit. Als de broker niet kan aantonen dat er geen rol is of als er geen externe PR bestaat, gebruik dan fork-CI zonder geheimen. Gebruik geen hydrate-github, --no-sync of een Testbox-workflow die met aanmeldgegevens is geladen. Verwijder alle CRABBOX_TAILSCALE*-overschrijvingen uit de omgeving, dwing --network public --tailscale=false af, wis exit-node-/LAN-vlaggen en vereis dat crabbox inspect openbare netwerken zonder Tailscale-status rapporteert voordat een script wordt geüpload.

Gebruikelijke lokale volgorde

1. pnpm test:changed voor Vitest-bewijs met gewijzigd bereik.
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 rechtstreeks lokaal gebruik van pnpm test* / pnpm check* / pnpm crabbox:run:

• Begrensd gericht bewijs met gereedstaande afhankelijkheden: node scripts/run-vitest.mjs <path-or-filter>.
• Controle met eerst classificatie van wijzigingen: node scripts/check-changed.mjs; plannen met alleen documentatie, zonder wijzigingen en met beperkte metadata 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 uiteindelijke exitCode en timing-JSON van de wrapper vormen het opdrachtresultaat. Een gedelegeerde uitvoering van Blacksmith GitHub Actions kan na een geslaagde SSH-opdracht cancelled tonen omdat de Testbox buiten de keepalive-actie wordt gestopt; controleer de samenvatting van de wrapper en de 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 in gekoppelde worktrees uitvoert.

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 dit vanuit Vitest wanneer een test een geïsoleerde HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, configuratiefixture, werkruimte, agentmap of opslag voor auth-profielen 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 helper voor gedeelde teststatus 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-taken die scripts/lib/docker-e2e-image.sh sourcen, kunnen docker_e2e_test_state_shell_b64 <label> <scenario> aan de container doorgeven en deze 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). Taken die een Gateway starten, kunnen scripts/lib/openclaw-e2e-instance.sh sourcen voor het herleiden van het entrypoint, het starten van een mock-OpenAI, starten op de voorgrond/achtergrond, gereedheidscontroles, export van de statusomgeving, logdumps en procesopschoning.

Taken voor Control UI, TUI en extensies

• Gemockte E2E voor de Control UI: pnpm test:ui:e2e voert de Vitest + Playwright-lane uit die de Vite Control UI start en een echte Chromium-pagina aanstuurt via een gemockte Gateway-WebSocket. Tests staan in ui/src/**/*.e2e.test.ts; gedeelde mocks/besturingselementen staan in ui/src/test-helpers/control-ui-e2e.ts. pnpm test:e2e bevat deze lane. Agentruns 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 voor een expliciete lokale fallback.
• TUI-PTY-tests: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts voert de snelle PTY-lane met 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 mockt. Controleer stabiele zichtbare tekst of fixture-aanroepen, niet onbewerkte ANSI-snapshots.
• pnpm test:extensions en pnpm test extensions voeren alle extensie-/Plugin-shards 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 in 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 importerende tests uit te voeren in plaats van elke shard breed uit te voeren wanneer het afhankelijkheidspad precies is.
• Doelen voor contractdirectory's waaieren uit naar hun contractlanes: pnpm test src/channels/plugins/contracts voert de vier kanaalcontractconfiguraties uit en pnpm test src/plugins/contracts voert de configuratie voor Plugin-contracten uit, omdat de algemene channels-/plugins-projecten contracts/** uitsluiten.
• auto-reply wordt opgesplitst in drie afzonderlijke configuraties (core, top-level, reply), zodat de antwoordharness de lichtere tests op het hoogste niveau voor status, tokens en helpers niet domineert.
• Geselecteerde plugin-sdk- en commands-testbestanden 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 in 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 (WS/HTTP/Node-koppeling met meerdere instanties). 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 tests voor providers (Claude/Minimax/DeepSeek/z.ai/enz., afgeschermd door *.live.test.ts). Vereist API-sleutels en LIVE=1 (of OPENCLAW_LIVE_TEST=1) om het 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 scheduler. 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, updates en Plugin-afhankelijkheden; koppelt de vooraf gebouwde tarball 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 genereert het CI-plan dat door de scheduler 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 parallelliteit overschrijdt, kan deze toch vanuit een lege pool starten en zelfstandig worden uitgevoerd totdat capaciteit wordt vrijgegeven. Logs per lane, summary.json, failures.json en fasetimings worden onder .artifacts/docker-tests/<run-id>/ geschreven; gebruik pnpm test:docker:timings <summary.json> om trage lanes te inspecteren en pnpm test:docker:rerun <run-id|summary.json|failures.json> om eenvoudige gerichte opdrachten voor opnieuw uitvoeren weer te geven.

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 onregelmatig faalt op een zwaar belaste host, voer deze dan eenmaal opnieuw uit voordat je dit als een regressie beschouwt en isoleer 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 + importuitsplitsing in, terwijl voor expliciete bestands-/mapdoelen nog steeds routering via lanes met een beperkt bereik wordt gebruikt. pnpm test:perf:imports:changed beperkt dezelfde profilering tot bestanden die sinds origin/main zijn gewijzigd.
• pnpm test:perf:changed:bench -- --ref <git-ref> vergelijkt de prestaties van het gerouteerde pad in gewijzigde modus met de native uitvoering van het rootproject 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-/logartefacten per configuratie. Rapporten voor de volledige suite isoleren standaard bestanden, zodat behouden modulegraphs en GC-pauzes van eerdere bestanden niet worden toegerekend aan latere asserties; geef -- --no-isolate alleen door wanneer je doelbewust de accumulatie in een gedeelde worker profileert. De Test Performance Agent gebruikt dit als basislijn voordat wordt geprobeerd 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, extensieshards en shards met opnamepatronen werken lokale timinggegevens in .artifacts/vitest-shard-timings.json bij; latere uitvoeringen van volledige configuraties gebruiken die timings om trage en snelle shards evenwichtig te verdelen. CI-shards met opnamepatronen voegen de shardnaam aan de timingsleutel toe, zodat timings van gefilterde shards zichtbaar blijven zonder timinggegevens van de volledige configuratie 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 smoke-tests van onboarding. Volledige cold-startflow in een schone Linux-container:

scripts/e2e/onboard-docker.sh

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

Smoke-test voor QR-import (Docker)

Garandeert 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