Testler

• Tam test kiti (paketler, canlı, Docker): Testler
• Güncelleme ve plugin paketi doğrulaması: Güncellemeleri ve plugin'leri test etme

Agent varsayılanı

Agent oturumları, yalnızca kaynak güvenilir olduğunda ve mevcut bağımlılık kurulumu hazır olduğunda bir/birkaç odaklı testi ve düşük maliyetli statik kontrolü yerel olarak çalıştırır. Güvenilmeyen depo araçlarını asla yerel olarak çalıştırmayın. Daha büyük test paketleri, tür denetimi/lint dağılımı içeren değişiklik kapıları, derlemeler, Docker, paket hatları, E2E, canlı kanıt ve platformlar arası doğrulama, Crabbox üzerinden uzaktan çalıştırılır. Güvenilir bakımcıların yoğun kanıt işlemleri varsayılan olarak Blacksmith Testbox kullanır. Yapılandırılan Testbox iş akışı kimlik bilgilerini yüklediğinden, güvenilmeyen katkıda bulunan veya fork kodu bunun yerine gizli bilgi içermeyen fork CI ya da yalıtılmış doğrudan AWS Crabbox kullanmalıdır.

Öngörülen işler için önceden ısıtma yapmayın. İlk yoğun komut hazır olduğunda arka ucu gecikmeli olarak edinin, döndürülen tbx_... kimliğini sonraki yoğun komutlarda yeniden kullanın, her çalıştırmada geçerli checkout'u eşitleyin ve devretmeden önce durdurun.

İlk başarılı yeniden kullanımdan sonra sarmalayıcı, kiralamanın taban, bağımlılık ve Testbox iş akışı parmak izini .crabbox/testbox-leases/ altında kaydeder. Yalnızca kaynak kodu içeren düzenlemeler, ısıtılmış kutuyu yeniden kullanmaya devam eder. Değişen birleştirme tabanı, kilit dosyası, paket yöneticisi girdisi, sarmalayıcı veya Testbox iş akışı kapalı biçimde başarısız olur ve yeni bir kiralama gerektirir. Her çalıştırma yine de geçerli checkout'u eşitler. OPENCLAW_TESTBOX_ALLOW_STALE=1 yalnızca kasıtlı tanılamalar içindir, sürüm kanıtı için değildir.

Aşağıdaki yerel test komutları insan iş akışları ve sınırlandırılmış agent kanıtı içindir. Uzak sağlayıcının kullanılamaması bildirilmelidir; bu durum, geniş kapsamlı bir yerel kapıyı sessizce çalıştırma izni vermez.

Güvenilmeyen yoğun kanıt için --provider aws ile gecikmeli olarak ısıtın. Her çalıştırma CRABBOX_ENV_ALLOW=CI değerini ayarlamalı, --provider aws --no-hydrate geçirmeli ve bağımlılıkları kurmadan ya da testleri çalıştırmadan önce yeni bir geçici uzak HOME kullanmalıdır. Bu güvenilmeyen kaynağa ayrılmış, yeni ısıtılmış bir kiralama kullanın; güvenilir veya daha önce kimlik bilgileri yüklenmiş bir kiralamayı asla yeniden kullanmayın. Temiz ve güvenilir bir main checkout'undan kurulu, güvenilir bir Crabbox ikili dosyasını başlatın ve yalnızca uzak PR'ı --fresh-pr ile getirin; güvenilmeyen checkout'un sarmalayıcısını veya yapılandırmasını asla yerel olarak çalıştırmayın. CRABBOX_AWS_INSTANCE_PROFILE ayarını kaldırın ve çözümlenen aws.instanceProfile boş olmadığı sürece kapalı biçimde başarısız olun. Herhangi bir kurulum/test öncesinde, IMDSv2 belirteci gerektirmek, IAM kimlik bilgileri uç noktasının 404 döndürdüğünü kanıtlamak ve uzak git rev-parse HEAD değerinin incelenen PR başının tam SHA'sına eşit olduğunu doğrulamak için güvenilir mutlak yollu araçlar kullanın. Kiralamayı bu SHA'ya bağlayın ve baş değiştiğinde durdurup yeniden ısıtın. Temiz main içinden güvenilir scripts/crabbox-untrusted-bootstrap.sh dosyasını --fresh-pr ile birlikte yükleyin; bu dosya sabitlenmiş Node/pnpm sürümlerini kurar, SHA'yı ve paket yöneticisi sabitlemesini doğrular, HOME öğesini yalıtır, bağımlılıkları kurar ve ardından istenen testi çalıştırır. Aracı, rol olmadığını kanıtlayamazsa veya uzak PR yoksa gizli bilgi içermeyen fork CI kullanın. hydrate-github, --no-sync veya kimlik bilgileri yüklenmiş bir Testbox iş akışı kullanmayın. Tüm CRABBOX_TAILSCALE* geçersiz kılmalarını kaldırın, --network public --tailscale=false kullanımını zorunlu kılın, çıkış düğümü/LAN bayraklarını temizleyin ve herhangi bir betiği yüklemeden önce crabbox inspect çıktısının Tailscale durumu olmadan genel ağ kullanımını bildirmesini zorunlu kılın.

Rutin yerel sıra

1. Değişiklik kapsamlı Vitest kanıtı için pnpm test:changed.
2. Tek bir dosya, dizin veya açık hedef için pnpm test <path-or-filter>.
3. Yalnızca tam yerel Vitest paketine kasıtlı olarak ihtiyaç duyduğunuzda pnpm test.

Bir Codex çalışma ağacında veya bağlı/seyrek checkout'ta agent'lar doğrudan yerel pnpm test* / pnpm check* / pnpm crabbox:run kullanımından kaçınır:

• Hazır bağımlılıklarla sınırlandırılmış odaklı kanıt: node scripts/run-vitest.mjs <path-or-filter>.
• Önce sınıflandırılan değişiklik kontrolü: node scripts/check-changed.mjs; yalnızca doküman, değişiklik olmayan ve küçük meta veri planları bağımlılıklar hazır olduğunda yerel kalırken, yoğun veya bağımlılıkları eksik planlar Testbox'a devredilir.
• Açıkça tutulan kiralamayla geniş kapsamlı kanıt: pnpm'nin Testbox içinde çalışması için 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.
• Sarmalayıcının son exitCode değeri ve zamanlama JSON'u komut sonucudur. Devredilmiş bir Blacksmith GitHub Actions çalıştırması, Testbox canlı tutma eyleminin dışından durdurulduğu için başarılı bir SSH komutundan sonra cancelled gösterebilir; bunu hata olarak değerlendirmeden önce sarmalayıcı özetini ve komut çıktısını kontrol edin.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: pnpm check:changed ve hedefli pnpm test ... gibi komutlarda yoğun kontrol serileştirmesini Git ortak dizini yerine geçerli çalışma ağacının içinde tutar. Yalnızca yüksek kapasiteli yerel ana makinelerde, bağlı çalışma ağaçları arasında bağımsız kontrolleri kasıtlı olarak çalıştırdığınızda kullanın.

Temel komutlar

Test sarmalayıcısı çalıştırmaları kısa bir [test] passed|failed|skipped ... in ... özetiyle sona erer; Vitest'in kendi süre satırı parça başına ayrıntı olarak kalır.

Paylaşılan test durumu ve işlem yardımcıları

• src/test-utils/openclaw-test-state.ts: bir test yalıtılmış bir HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, yapılandırma fikstürü, çalışma alanı, agent dizini veya kimlik doğrulama profili deposu gerektirdiğinde Vitest içinden kullanın.
• pnpm test:env-mutations:report: HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR veya ilgili ortam anahtarlarını doğrudan değiştiren testlerin/düzeneklerin engellemesiz raporu. Paylaşılan test durumu yardımcısı için geçiş adaylarını bulmak üzere kullanın.
• test/helpers/openclaw-test-instance.ts: çalışan bir Gateway, CLI ortamı, günlük yakalama ve temizlemeyi tek bir yerde gerektiren işlem düzeyinde E2E testleri.
• scripts/lib/docker-e2e-image.sh dosyasını kaynak olarak alan Docker/Bash E2E hatları, docker_e2e_test_state_shell_b64 <label> <scenario> değerini konteynere geçirebilir ve scripts/lib/openclaw-e2e-instance.sh ile çözebilir; çoklu ana dizin betikleri docker_e2e_test_state_function_b64 değerini geçirebilir ve her akışta openclaw_test_state_create <label> <scenario> çağırabilir. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json, kaynak olarak alınabilir bir ana makine ortam dosyası yazar (create öncesindeki --, yeni Node çalışma zamanlarının --env-file değerini bir Node bayrağı olarak değerlendirmesini önler). Gateway başlatan hatlar; giriş noktası çözümleme, sahte OpenAI başlatma, ön plan/arka plan başlatma, hazır olma yoklamaları, durum ortamını dışa aktarma, günlük dökümleri ve işlem temizliği için scripts/lib/openclaw-e2e-instance.sh dosyasını kaynak olarak alabilir.

Control UI, TUI ve uzantı hatları

• Sahte Control UI E2E: pnpm test:ui:e2e, Vite Control UI'yi başlatan ve sahte bir Gateway WebSocket'e karşı gerçek bir Chromium sayfasını yönlendiren Vitest + Playwright hattını çalıştırır. Testler ui/src/**/*.e2e.test.ts içinde; paylaşılan sahte nesneler/denetimler ui/src/test-helpers/control-ui-e2e.ts içinde bulunur. pnpm test:e2e bu hattı içerir. Hedefli doğrulama dahil olmak üzere Agent çalıştırmaları varsayılan olarak Testbox/Crabbox kullanır; 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 yalnızca açıkça belirtilen yerel bir geri dönüş için kullanılmalıdır.
• TUI PTY testleri: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts, hızlı sahte arka uç PTY hattını çalıştırır. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 veya pnpm tui:pty:test:watch --mode local, yalnızca harici model uç noktasını taklit eden daha yavaş tui --local duman testini çalıştırır. Ham ANSI anlık görüntüleri yerine kararlı görünür metni veya fikstür çağrılarını doğrulayın.
• pnpm test:extensions ve pnpm test extensions, tüm uzantı/plugin parçalarını çalıştırır. Ağır kanal plugin'leri, tarayıcı plugin'i ve OpenAI özel parçalar olarak çalışır; diğer plugin grupları toplu olarak kalır. pnpm test extensions/<id>, tek bir paketlenmiş plugin hattını çalıştırır.
• Kardeş testleri bulunan kaynak dosyalar, daha geniş dizin globlarına geri dönmeden önce bu kardeş testlerle eşleştirilir. src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers ve src/plugins/contracts altındaki yardımcı düzenlemeleri, bağımlılık yolu kesin olduğunda her parçayı geniş kapsamlı çalıştırmak yerine içe aktaran testleri çalıştırmak için yerel bir içe aktarma grafiği kullanır.
• Sözleşme dizini hedefleri kendi sözleşme hatlarına dağıtılır: genel channels/plugins projeleri contracts/** öğesini hariç tuttuğundan, pnpm test src/channels/plugins/contracts dört kanal sözleşmesi yapılandırmasını, pnpm test src/plugins/contracts ise plugin sözleşmeleri yapılandırmasını çalıştırır.
• auto-reply, yanıt test düzeneğinin daha hafif üst düzey durum/token/yardımcı testlerine baskın gelmemesi için üç özel yapılandırmaya (core, top-level, reply) ayrılır.
• Seçilen plugin-sdk ve commands test dosyaları, yalnızca test/setup.ts öğesini tutan özel hafif hatlar üzerinden yönlendirilir; çalışma zamanı açısından ağır durumlar mevcut hatlarında bırakılır.
• Temel Vitest yapılandırması varsayılan olarak pool: "threads" ve isolate: false kullanır; paylaşılan yalıtılmamış çalıştırıcı repo yapılandırmalarının tamamında etkindir.
• pnpm test:channels, vitest.channels.config.ts öğesini çalıştırır.

Gateway ve E2E

• Gateway entegrasyonu isteğe bağlıdır: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test veya pnpm test:gateway.
• pnpm test:e2e: repo E2E toplamı = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: Gateway uçtan uca duman testleri (çoklu örnek WS/HTTP/Node eşleştirmesi). vitest.e2e.config.ts içindeki uyarlanabilir işçilerle varsayılan olarak threads + isolate: false kullanır; OPENCLAW_E2E_WORKERS=<n> ile ayarlayın, ayrıntılı günlükler için OPENCLAW_E2E_VERBOSE=1 kullanın.
• pnpm test:live: sağlayıcı canlı testleri (Claude/Minimax/DeepSeek/z.ai/vb., *.live.test.ts tarafından denetlenir). Atlamayı kaldırmak için API anahtarları ve LIVE=1 (veya OPENCLAW_LIVE_TEST=1) gerekir; ayrıntılı çıktı için OPENCLAW_LIVE_TEST_QUIET=0 kullanılır.

Tam Docker paketi (pnpm test:docker:all)

Paylaşılan canlı test imajını oluşturur, OpenClaw'ı bir npm tarball'ı olarak bir kez paketler, yalın bir Node/Git çalıştırıcı imajı ile bu tarball'ı /app içine yükleyen işlevsel bir imajı oluşturur/yeniden kullanır ve ardından Docker duman testi hatlarını ağırlıklı bir zamanlayıcı aracılığıyla çalıştırır. scripts/package-openclaw-for-docker.mjs, tek yerel/CI paketleyicisidir ve Docker tarball'ı kullanmadan önce tarball'ı ve dist/postinstall-inventory.json öğesini doğrular.

• Yalın imaj (OPENCLAW_DOCKER_E2E_BARE_IMAGE): yükleyici/güncelleme/plugin bağımlılığı hatları; kopyalanmış repo kaynakları yerine önceden oluşturulmuş tarball'ı bağlar.
• İşlevsel imaj (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): normal oluşturulmuş uygulama işlevselliği hatları.
• Hat tanımları: scripts/lib/docker-e2e-scenarios.mjs. Planlayıcı: scripts/lib/docker-e2e-plan.mjs. Yürütücü: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json, Docker'ı oluşturmadan veya çalıştırmadan zamanlayıcının sahip olduğu CI planını (hatlar, imaj türleri, paket/canlı imaj gereksinimleri, durum senaryoları, kimlik bilgisi denetimleri) üretir.

Zamanlama ayarları (ortam değişkenleri, varsayılanlar parantez içinde):

Kaynak üst sınırlarına yönelik ortam değişkeni kalıbı OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT şeklindedir (kaynak adı büyük harfe dönüştürülür, alfasayısal olmayan karakterler _ biçiminde daraltılır).

Diğer davranışlar: çalıştırıcı varsayılan olarak Docker ön denetimini gerçekleştirir, eski OpenClaw E2E konteynerlerini temizler, uyumlu hatlar arasında sağlayıcı CLI aracı önbelleklerini paylaşır ve OPENCLAW_DOCKER_ALL_FAIL_FAST=0 ayarlanmadığı sürece ilk hatadan sonra yeni havuzlanmış hatları zamanlamayı durdurur. Bir hat, düşük paralellikli bir ana makinede etkin ağırlık/kaynak sınırını aşarsa yine de boş bir havuzdan başlayabilir ve kapasiteyi serbest bırakana kadar tek başına çalışabilir. Hat başına günlükler, summary.json, failures.json ve aşama zamanlamaları .artifacts/docker-tests/<run-id>/ altında yazılır; yavaş hatları incelemek için pnpm test:docker:timings <summary.json>, düşük maliyetli hedefli yeniden çalıştırma komutlarını yazdırmak için pnpm test:docker:rerun <run-id|summary.json|failures.json> kullanın.

Dikkate değer Docker hatları

Yerel PR geçidi

Yerel PR birleştirme/geçit denetimleri için şunları çalıştırın:

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

pnpm test yüklü bir ana makinede kararsız sonuç verirse bunu regresyon olarak değerlendirmeden önce bir kez yeniden çalıştırın, ardından pnpm test <path/to/test> ile yalıtın. Belleği kısıtlı ana makineler için:

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

Test performansı araçları

• pnpm test:perf:imports: açık dosya/dizin hedefleri için kapsamlı hat yönlendirmesini kullanmaya devam ederken Vitest içe aktarma süresi + içe aktarma dökümü raporlamasını etkinleştirir. pnpm test:perf:imports:changed, aynı profillemeyi origin/main tarihinden beri değişen dosyalarla sınırlar.
• pnpm test:perf:changed:bench -- --ref <git-ref>, yönlendirilmiş değişiklik modundaki yolu aynı kaydedilmiş git farkı için yerel kök proje çalıştırmasıyla karşılaştırmalı olarak ölçer; pnpm test:perf:changed:bench -- --worktree, önce kaydetmeden mevcut çalışma ağacı değişiklik kümesini karşılaştırmalı olarak ölçer.
• pnpm test:perf:profile:main, Vitest ana iş parçacığı için bir CPU profili yazar (.artifacts/vitest-main-profile); pnpm test:perf:profile:runner, birim çalıştırıcısı için CPU + yığın profilleri yazar (.artifacts/vitest-runner-profile).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: her tam paket Vitest yaprak yapılandırmasını seri olarak çalıştırır ve gruplandırılmış süre verilerinin yanı sıra yapılandırma başına JSON/günlük eserleri yazar. Tam paket raporları, önceki dosyalardan kalan modül grafiklerinin ve GC duraklamalarının sonraki savlara yüklenmemesi için varsayılan olarak dosyaları yalıtır; -- --no-isolate parametresini yalnızca paylaşımlı çalışan birikimini bilinçli olarak profillerken geçirin. Test Performansı Aracısı, yavaş test düzeltmelerini denemeden önce bunu temel çizgi olarak kullanır. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json, performans odaklı bir değişiklikten sonra gruplandırılmış raporları karşılaştırır.
• Tam, uzantı ve içerme deseni parça çalıştırmaları .artifacts/vitest-shard-timings.json içindeki yerel zamanlama verilerini günceller; sonraki tüm yapılandırma çalıştırmaları, yavaş ve hızlı parçaları dengelemek için bu zamanlamaları kullanır. İçerme deseni CI parçaları, filtrelenmiş parça zamanlamalarını tüm yapılandırma zamanlama verilerinin yerine koymadan görünür tutmak için parça adını zamanlama anahtarına ekler. Yerel zamanlama eserini yok saymak için OPENCLAW_TEST_PROJECTS_TIMINGS=0 ayarlayın.

Karşılaştırmalı ölçümler

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

İlk kurulum E2E'si (Docker)

İsteğe bağlıdır; yalnızca konteyner tabanlı ilk kurulum duman testleri için gereklidir. Temiz bir Linux konteynerinde tam soğuk başlatma akışı:

scripts/e2e/onboard-docker.sh

Etkileşimli sihirbazı sözde tty üzerinden çalıştırır, yapılandırma/çalışma alanı/oturum dosyalarını doğrular, ardından Gateway'i başlatır ve openclaw health komutunu çalıştırır.

QR içe aktarma duman testi (Docker)

Bakımı yapılan QR çalışma zamanı yardımcısının desteklenen Docker Node çalışma zamanlarında (varsayılan Node 24, Node 22 ile uyumlu) yüklenmesini sağlar:

pnpm test:docker:qr

İlgili

• Testler
• Canlı testler
• Güncellemeleri ve Plugin'leri test etme