Release and CI

آزمون‌ها

پیش‌فرض عامل

نشست‌های عامل، آزمون‌ها و اعتبارسنجی‌های محاسباتی سنگین را از راه دور از طریق Crabbox اجرا می‌کنند. کد مورداعتماد نگه‌دارندگان به‌طور پیش‌فرض از Blacksmith Testbox استفاده می‌کند. گردش‌کار پیکربندی‌شدهٔ Testbox اطلاعات احراز هویت را آماده‌سازی می‌کند؛ بنابراین کد نامطمئن مشارکت‌کنندگان یا انشعاب‌ها باید به‌جای آن از CI انشعاب بدون اطلاعات محرمانه یا AWS Crabbox مستقیم و پاک‌سازی‌شده استفاده کند.

وقتی احتمال دارد یک وظیفهٔ کدنویسی مورداعتماد به آزمون یا اثبات سنگین نیاز داشته باشد، فوراً در یک نشست فرمان پس‌زمینه آن را پیش‌گرم کنید، هنگام آماده‌سازی به کار ادامه دهید، شناسهٔ بازگردانده‌شدهٔ tbx_... را دوباره استفاده کنید، در هر اجرا نسخهٔ کاری فعلی را همگام‌سازی کنید و پیش از تحویل آن را متوقف کنید:

bash
node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json

پس از نخستین استفادهٔ مجدد موفق، پوشش‌دهنده اثرانگشت مبنا، وابستگی و گردش‌کار Testbox اجاره را در .crabbox/testbox-leases/ ثبت می‌کند. ویرایش‌های صرفاً منبعی همچنان از محیط پیش‌گرم‌شده استفاده می‌کنند. تغییر در مبنای ادغام، فایل قفل، ورودی مدیر بسته، پوشش‌دهنده یا گردش‌کار Testbox به‌صورت بسته شکست می‌خورد و به اجاره‌ای تازه نیاز دارد. هر اجرا همچنان نسخهٔ کاری فعلی را همگام‌سازی می‌کند. OPENCLAW_TESTBOX_ALLOW_STALE=1 فقط برای عیب‌یابی عمدی است، نه اثبات انتشار.

فرمان‌های آزمون محلی زیر برای گردش‌کارهای انسانی یا حالت جایگزین صریح عامل هستند که کاربر درخواست کرده باشد. دردسترس‌نبودن ارائه‌دهندهٔ راه دور باید گزارش شود؛ این وضعیت اجازهٔ اجرای بی‌سروصدای یک دروازهٔ محلی گسترده را نمی‌دهد.

برای کد نامطمئن، با --provider aws پیش‌گرم کنید. هر اجرا باید CRABBOX_ENV_ALLOW=CI را تنظیم کند، --provider aws --no-hydrate را ارسال کند و پیش از نصب وابستگی‌ها یا اجرای آزمون‌ها از یک HOME موقت و تازه در محیط راه دور استفاده کند. از اجاره‌ای تازه و اختصاصی برای همان منبع نامطمئن استفاده کنید؛ هرگز اجارهٔ مورداعتماد یا ازپیش‌آماده‌شده را دوباره استفاده نکنید. یک فایل اجرایی Crabbox نصب‌شده و مورداعتماد را از نسخهٔ کاری پاک و مورداعتماد main اجرا کنید و فقط PR راه دور را با --fresh-pr دریافت کنید؛ هرگز پوشش‌دهنده یا پیکربندی نسخهٔ کاری نامطمئن را به‌صورت محلی اجرا نکنید. CRABBOX_AWS_INSTANCE_PROFILE را لغو تنظیم کنید و مگر اینکه مقدار نهایی aws.instanceProfile خالی باشد، به‌صورت بسته شکست دهید. پیش از هر نصب یا آزمون، با ابزارهای مورداعتماد دارای مسیر مطلق، وجود توکن IMDSv2 را الزامی کنید، ثابت کنید نقطهٔ پایانی اطلاعات احراز هویت IAM پاسخ 404 می‌دهد و تأیید کنید git rev-parse HEAD راه دور با SHA کامل سرِ PR بررسی‌شده برابر است. اجاره را به آن SHA مقید کنید و هنگام تغییر سر، آن را متوقف و دوباره پیش‌گرم کنید. فایل مورداعتماد scripts/crabbox-untrusted-bootstrap.sh را از main پاک همراه با --fresh-pr بارگذاری کنید؛ این فایل Node/pnpm سنجاق‌شده را نصب می‌کند، SHA و سنجاق مدیر بسته را تأیید می‌کند، HOME را ایزوله می‌کند، وابستگی‌ها را نصب می‌کند و سپس آزمون درخواستی را اجرا می‌کند. اگر کارگزار نتواند نبود نقش یا وجودنداشتن PR راه دور را اثبات کند، از CI انشعاب بدون اطلاعات محرمانه استفاده کنید. از hydrate-github، --no-sync یا گردش‌کار Testbox آماده‌سازی‌شده با اطلاعات احراز هویت استفاده نکنید. همهٔ بازنویسی‌های CRABBOX_TAILSCALE* را لغو تنظیم کنید، --network public --tailscale=false را اجباری کنید، پرچم‌های گرهٔ خروجی/LAN را پاک کنید و پیش از بارگذاری هر اسکریپت، الزام کنید crabbox inspect شبکهٔ عمومی بدون وضعیت Tailscale را گزارش دهد.

ترتیب معمول محلی

  1. pnpm test:changed برای اثبات Vitest در محدودهٔ تغییرات.
  2. pnpm test <path-or-filter> برای یک فایل، پوشه یا هدف صریح.
  3. pnpm test فقط وقتی عمداً به مجموعهٔ کامل محلی Vitest نیاز دارید.

در نسخهٔ کاری Codex یا نسخهٔ کاری پیوندی/تنک، عامل‌ها از اجرای مستقیم محلی pnpm test* / pnpm check* / pnpm crabbox:run پرهیز می‌کنند:

  • حالت جایگزین محلی که کاربر صراحتاً برای یک فایل کوچک درخواست کرده است: node scripts/run-vitest.mjs <path-or-filter>.
  • دروازه‌های تغییرات یا اثبات گسترده: 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 تا pnpm درون Testbox اجرا شود.
  • exitCode نهایی پوشش‌دهنده و JSON زمان‌بندی، نتیجهٔ فرمان هستند. اجرای واگذارشدهٔ Blacksmith GitHub Actions ممکن است پس از فرمان موفق SSH وضعیت cancelled نشان دهد، زیرا Testbox از بیرون کنش زنده‌نگه‌دار متوقف می‌شود؛ پیش از تلقی آن به‌عنوان شکست، خلاصهٔ پوشش‌دهنده و خروجی فرمان را بررسی کنید.
  • OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: برای فرمان‌هایی مانند pnpm check:changed و pnpm test ... هدفمند، سریال‌سازی بررسی‌های سنگین را به‌جای پوشهٔ مشترک Git در نسخهٔ کاری فعلی نگه می‌دارد. فقط وقتی عمداً بررسی‌های مستقل را در نسخه‌های کاری پیوندی روی میزبان‌های محلی پرظرفیت اجرا می‌کنید، از آن استفاده کنید.

فرمان‌های اصلی

اجرای پوشش‌دهندهٔ آزمون با خلاصه‌ای کوتاه به‌شکل [test] passed|failed|skipped ... in ... پایان می‌یابد؛ خط مدت‌زمان خود Vitest به‌عنوان جزئیات هر شارد باقی می‌ماند.

فرمان کاری که انجام می‌دهد
pnpm test اهداف صریح فایل/پوشه از مسیرهای محدود Vitest عبور می‌کنند. اجراهای بدون هدف، اثبات مجموعهٔ کامل هستند: گروه‌های ثابت شارد برای اجرای موازی محلی به پیکربندی‌های برگ گسترش می‌یابند و پراکندگی موردانتظار شارد پیش از شروع نمایش داده می‌شود. گروه افزونه همیشه به‌جای یک فرایند عظیم پروژهٔ ریشه، به پیکربندی‌های شارد جداگانه برای هر افزونه گسترش می‌یابد.
pnpm test:changed اجرای هوشمند و کم‌هزینهٔ آزمون تغییرات: اهداف دقیق از ویرایش مستقیم آزمون‌ها، فایل‌های هم‌ردهٔ *.test.ts، نگاشت‌های صریح منبع و گراف واردسازی محلی. تغییرات گسترده/پیکربندی/بسته رد می‌شوند، مگر اینکه به آزمون‌های دقیقی نگاشت شوند.
OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed اجرای صریح و گستردهٔ آزمون تغییرات؛ وقتی ویرایش ابزار آزمون/پیکربندی/بسته باید به رفتار گسترده‌تر آزمون تغییرات Vitest بازگردد، از آن استفاده کنید.
pnpm test:force درگاه پیکربندی‌شدهٔ Gateway مربوط به OpenClaw را آزاد می‌کند (پیش‌فرض 18789) و سپس مجموعهٔ کامل را با درگاه Gateway ایزوله اجرا می‌کند تا آزمون‌های سرور با نمونهٔ درحال‌اجرا تداخل نداشته باشند.
pnpm test:coverage گزارش اطلاعاتی پوشش V8 را برای مسیر پیش‌فرض واحد (vitest.unit.config.ts) تولید می‌کند؛ هیچ آستانهٔ پوششی اعمال نمی‌شود.
pnpm test:coverage:changed پوشش واحد فقط برای فایل‌هایی که از origin/main تغییر کرده‌اند.
pnpm changed:lanes مسیرهای معماری فعال‌شده توسط تفاوت با origin/main را نشان می‌دهد.
pnpm check:changed بیرون از CI به‌طور پیش‌فرض اجرا را به Crabbox/Testbox واگذار می‌کند، سپس دروازهٔ هوشمند بررسی تغییرات را در فرزند راه دور اجرا می‌کند: قالب‌بندی به‌همراه بررسی نوع، وارسی و فرمان‌های محافظ برای مسیرهای تحت‌تأثیر. Vitest را اجرا نمی‌کند؛ برای اثبات آزمون از pnpm test:changed یا pnpm test <target> استفاده کنید.

وضعیت مشترک آزمون و ابزارهای کمکی فرایند

  • src/test-utils/openclaw-test-state.ts: وقتی یک آزمون Vitest به HOME، OPENCLAW_STATE_DIR، OPENCLAW_CONFIG_PATH، نمونهٔ پیکربندی، فضای کاری، پوشهٔ عامل یا مخزن نمایهٔ احراز هویت ایزوله نیاز دارد، از آن استفاده کنید.
  • pnpm test:env-mutations:report: گزارش غیرمسدودکنندهٔ آزمون‌ها/ابزارهایی که مستقیماً HOME، OPENCLAW_STATE_DIR، OPENCLAW_CONFIG_PATH، OPENCLAW_WORKSPACE_DIR یا کلیدهای محیطی مرتبط را تغییر می‌دهند. از آن برای یافتن نامزدهای مهاجرت به ابزار مشترک وضعیت آزمون استفاده کنید.
  • test/helpers/openclaw-test-instance.ts: برای آزمون‌های E2E سطح فرایند که به Gateway درحال‌اجرا، محیط CLI، ثبت گزارش و پاک‌سازی یکپارچه نیاز دارند.
  • مسیرهای E2E مربوط به Docker/Bash که scripts/lib/docker-e2e-image.sh را منبع‌گذاری می‌کنند، می‌توانند docker_e2e_test_state_shell_b64 <label> <scenario> را به کانتینر ارسال و با scripts/lib/openclaw-e2e-instance.sh رمزگشایی کنند؛ اسکریپت‌های چندخانه‌ای می‌توانند docker_e2e_test_state_function_b64 را ارسال کنند و در هر جریان openclaw_test_state_create <label> <scenario> را فراخوانی کنند. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json یک فایل محیطی قابل منبع‌گذاری میزبان می‌نویسد (-- پیش از create مانع می‌شود زمان‌اجرای جدیدتر Node، گزینهٔ --env-file را پرچم Node تلقی کند). مسیرهایی که Gateway راه‌اندازی می‌کنند می‌توانند scripts/lib/openclaw-e2e-instance.sh را برای تفکیک نقطهٔ ورود، راه‌اندازی OpenAI شبیه‌سازی‌شده، اجرای پیش‌زمینه/پس‌زمینه، کاوش‌های آمادگی، برون‌بری محیط وضعیت، تخلیهٔ گزارش‌ها و پاک‌سازی فرایند منبع‌گذاری کنند.

مسیرهای رابط کاربری کنترل، TUI و افزونه

  • آزمون E2E شبیه‌سازی‌شدهٔ رابط کنترل: pnpm test:ui:e2e مسیر Vitest + Playwright را اجرا می‌کند که رابط کنترل Vite را راه‌اندازی می‌کند و یک صفحهٔ واقعی Chromium را در برابر WebSocket شبیه‌سازی‌شدهٔ Gateway هدایت می‌کند. آزمون‌ها در ui/src/**/*.e2e.test.ts قرار دارند؛ شبیه‌سازها/کنترل‌های مشترک در ui/src/test-helpers/control-ui-e2e.ts قرار دارند. pnpm test:e2e شامل این مسیر است. اجرای عامل‌ها، از جمله اثبات هدفمند، به‌طور پیش‌فرض در Testbox/Crabbox انجام می‌شود؛ فقط برای یک مسیر جایگزین محلیِ صریح از 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 استفاده کنید.
  • آزمون‌های PTY در TUI: فرمان node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts مسیر سریع PTY با بک‌اند جعلی را اجرا می‌کند. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 یا pnpm tui:pty:test:watch --mode local آزمون دودِ کندتر tui --local را اجرا می‌کند که فقط نقطهٔ پایانی مدل خارجی را شبیه‌سازی می‌کند. متن قابل‌مشاهدهٔ پایدار یا فراخوانی‌های فیکسچر را بررسی کنید، نه اسنپ‌شات‌های خام ANSI را.
  • pnpm test:extensions و pnpm test extensions همهٔ شاردهای افزونه/Plugin را اجرا می‌کنند. Pluginهای سنگین کانال، Plugin مرورگر و OpenAI به‌صورت شاردهای اختصاصی اجرا می‌شوند؛ سایر گروه‌های Plugin به‌صورت دسته‌بندی‌شده باقی می‌مانند. pnpm test extensions/<id> مسیر یک Plugin همراه را اجرا می‌کند.
  • فایل‌های منبعی که آزمون هم‌جوار دارند، پیش از بازگشت به الگوهای گسترده‌تر دایرکتوری، به همان آزمون هم‌جوار نگاشت می‌شوند. ویرایش ابزارهای کمکی زیر src/channels/plugins/contracts/test-helpers، src/plugin-sdk/test-helpers و src/plugins/contracts از گراف واردسازی محلی استفاده می‌کند تا وقتی مسیر وابستگی دقیق است، به‌جای اجرای گستردهٔ همهٔ شاردها، آزمون‌های واردکننده اجرا شوند.
  • هدف‌های دایرکتوری قرارداد به مسیرهای قرارداد خود منشعب می‌شوند: pnpm test src/channels/plugins/contracts چهار پیکربندی قرارداد کانال را اجرا می‌کند و pnpm test src/plugins/contracts پیکربندی قراردادهای Plugin را اجرا می‌کند، زیرا پروژه‌های عمومی channels/plugins مسیر contracts/** را مستثنا می‌کنند.
  • auto-reply به سه پیکربندی اختصاصی (core، top-level، reply) تقسیم می‌شود تا چارچوب آزمون پاسخ بر آزمون‌های سبک‌تر وضعیت/توکن/ابزار کمکی در سطح بالا غالب نشود.
  • فایل‌های آزمون منتخب plugin-sdk و commands از مسیرهای سبک اختصاصی عبور می‌کنند که فقط test/setup.ts را نگه می‌دارند و موارد سنگین از نظر زمان اجرا را در مسیرهای موجودشان باقی می‌گذارند.
  • پیکربندی پایهٔ Vitest به‌طور پیش‌فرض از pool: "threads" و isolate: false استفاده می‌کند و اجراکنندهٔ مشترکِ بدون جداسازی در پیکربندی‌های مخزن فعال است.
  • pnpm test:channels فایل vitest.channels.config.ts را اجرا می‌کند.

Gateway و E2E

  • یکپارچه‌سازی Gateway انتخابی است: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test یا pnpm test:gateway.
  • pnpm test:e2e: مجموعهٔ E2E مخزن = pnpm test:e2e:gateway && pnpm test:ui:e2e.
  • pnpm test:e2e:gateway: آزمون‌های دود سرتاسری Gateway (جفت‌سازی چندنمونه‌ای WS/HTTP/Node). به‌طور پیش‌فرض از threads + isolate: false با workerهای تطبیقی در vitest.e2e.config.ts استفاده می‌کند؛ با OPENCLAW_E2E_WORKERS=<n> تنظیم کنید و برای گزارش‌های مفصل از OPENCLAW_E2E_VERBOSE=1 استفاده کنید.
  • pnpm test:live: آزمون‌های زندهٔ ارائه‌دهندگان (Claude/Minimax/DeepSeek/z.ai/و غیره، محدودشده با *.live.test.ts). برای خارج‌شدن از حالت ردشدن به کلیدهای API و LIVE=1 (یا OPENCLAW_LIVE_TEST=1) نیاز دارد؛ برای خروجی مفصل از OPENCLAW_LIVE_TEST_QUIET=0 استفاده کنید.

مجموعهٔ کامل Docker (pnpm test:docker:all)

تصویر مشترک آزمون زنده را می‌سازد، OpenClaw را یک‌بار به‌صورت tarball مربوط به npm بسته‌بندی می‌کند، یک تصویر اجرای پایهٔ Node/Git و یک تصویر عملیاتی را که آن tarball را در /app نصب می‌کند می‌سازد/دوباره استفاده می‌کند، سپس مسیرهای آزمون دود Docker را از طریق یک زمان‌بند وزن‌دار اجرا می‌کند. scripts/package-openclaw-for-docker.mjs تنها بسته‌بند محلی/CI است و پیش از استفادهٔ Docker، tarball و dist/postinstall-inventory.json را اعتبارسنجی می‌کند.

  • تصویر پایه (OPENCLAW_DOCKER_E2E_BARE_IMAGE): مسیرهای نصب‌کننده/به‌روزرسانی/وابستگی Plugin؛ به‌جای منابع کپی‌شدهٔ مخزن، tarball ازپیش‌ساخته‌شده را متصل می‌کند.
  • تصویر عملیاتی (OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): مسیرهای عادی قابلیت‌های برنامهٔ ساخته‌شده.
  • تعریف مسیرها: scripts/lib/docker-e2e-scenarios.mjs. برنامه‌ریز: scripts/lib/docker-e2e-plan.mjs. اجراکننده: scripts/test-docker-all.mjs.
  • node scripts/test-docker-all.mjs --plan-json برنامهٔ CI متعلق به زمان‌بند (مسیرها، انواع تصویر، نیازهای بسته/تصویر زنده، سناریوهای وضعیت، بررسی‌های اعتبارنامه) را بدون ساختن یا اجرای Docker تولید می‌کند.

گزینه‌های زمان‌بندی (متغیرهای محیطی، مقادیر پیش‌فرض درون پرانتز):

متغیر محیطی پیش‌فرض هدف
OPENCLAW_DOCKER_ALL_PARALLELISM 10 جایگاه‌های پردازش.
OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM 10 مخزن انتهایی حساس به ارائه‌دهنده.
OPENCLAW_DOCKER_ALL_LIVE_LIMIT 9 سقف مسیرهای سنگین ارائه‌دهندهٔ زنده.
OPENCLAW_DOCKER_ALL_NPM_LIMIT 5 سقف مسیرهای وابسته به منابع npm.
OPENCLAW_DOCKER_ALL_SERVICE_LIMIT 7 سقف مسیرهای وابسته به منابع سرویس.
OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT / _CODEX_LIMIT / _GEMINI_LIMIT / _DROID_LIMIT / _OPENCODE_LIMIT 4 سقف مسیرهای سنگین به‌ازای هر ارائه‌دهنده.
OPENCLAW_DOCKER_ALL_LIVE_OPENAI_LIMIT / _TELEGRAM_LIMIT 1 سقف‌های محدودتر به‌ازای هر ارائه‌دهنده.
OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT / OPENCLAW_DOCKER_ALL_DOCKER_LIMIT - بازنویسی برای میزبان‌های بزرگ‌تر.
OPENCLAW_DOCKER_ALL_START_STAGGER_MS 2000 تأخیر میان شروع مسیرها؛ از هجوم ایجاد به سرویس Docker محلی جلوگیری می‌کند.
OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS 7,200,000 (120 دقیقه) مهلت زمانی جایگزین به‌ازای هر مسیر؛ مسیرهای زنده/انتهایی منتخب از سقف‌های سخت‌گیرانه‌تری استفاده می‌کنند.
OPENCLAW_DOCKER_ALL_LIVE_RETRIES 1 تعداد تلاش‌های مجدد برای خطاهای گذرای ارائه‌دهندهٔ زنده.
OPENCLAW_DOCKER_ALL_DRY_RUN خاموش مانیفست مسیرها را بدون اجرای Docker چاپ می‌کند.
OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS 30000 فاصلهٔ زمانی چاپ وضعیت مسیرهای فعال.
OPENCLAW_DOCKER_ALL_TIMINGS روشن از .artifacts/docker-tests/lane-timings.json برای ترتیب طولانی‌ترین‌ها در ابتدا دوباره استفاده می‌کند؛ برای غیرفعال‌کردن روی 0 تنظیم کنید.
OPENCLAW_DOCKER_ALL_LIVE_MODE - skip فقط برای مسیرهای قطعی/محلی و only فقط برای مسیرهای ارائه‌دهندهٔ زنده. نام‌های مستعار: pnpm test:docker:local:all، pnpm test:docker:live:all. حالت فقط زنده، مسیرهای زندهٔ اصلی و انتهایی را در یک مخزن با ترتیب طولانی‌ترین‌ها در ابتدا ادغام می‌کند تا باکت‌های ارائه‌دهنده، کار Claude/Codex/Gemini را کنار هم بسته‌بندی کنند.
OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS 180 مهلت زمانی راه‌اندازی بک‌اند CLI در Docker.

الگوی متغیر محیطی برای سقف منابع OPENCLAW_DOCKER_ALL_&lt;RESOURCE&gt;_LIMIT است (نام منبع با حروف بزرگ و نویسه‌های غیرالفبایی‌عددی که به _ تبدیل شده‌اند).

رفتارهای دیگر: اجراکننده به‌طور پیش‌فرض Docker را پیش‌بررسی می‌کند، کانتینرهای قدیمی E2E مربوط به OpenClaw را پاک‌سازی می‌کند، حافظه‌های نهان ابزارهای CLI ارائه‌دهندگان را میان مسیرهای سازگار به اشتراک می‌گذارد و پس از نخستین شکست، زمان‌بندی مسیرهای تجمیعی جدید را متوقف می‌کند؛ مگر اینکه OPENCLAW_DOCKER_ALL_FAIL_FAST=0 تنظیم شده باشد. اگر وزن یا منابع مؤثر یک مسیر از سقف میزبان کم‌هم‌زمانی فراتر رود، همچنان می‌تواند از یک مجموعه خالی آغاز شود و تا زمان آزادکردن ظرفیت، به‌تنهایی اجرا شود. گزارش‌های هر مسیر، summary.json،‏ failures.json و زمان‌بندی مرحله‌ها در .artifacts/docker-tests/<run-id>/ نوشته می‌شوند؛ برای بررسی مسیرهای کند از pnpm test:docker:timings <summary.json> و برای چاپ فرمان‌های کم‌هزینه و هدفمند اجرای مجدد از pnpm test:docker:rerun <run-id|summary.json|failures.json> استفاده کنید.

مسیرهای شاخص Docker

فرمان موارد بررسی‌شده
pnpm test:docker:browser-cdp-snapshot کانتینر E2E مبدأ مبتنی بر Chromium با CDP خام و Gateway ایزوله؛ تصویرهای فوری نقش CDP در browser doctor --deep شامل نشانی‌های پیوند، عناصر قابل‌کلیکی که با نشانگر شناسایی شده‌اند، ارجاع‌های iframe و فراداده فریم هستند.
pnpm test:docker:skill-install بسته tarball را در یک اجراکننده Docker خالی با skills.install.allowUploadedArchives: false نصب می‌کند، شناسه کوتاه یک skill فعلی را از جست‌وجوی زنده ClawHub استخراج می‌کند، آن را از طریق openclaw skills install نصب می‌کند و SKILL.md،‏ .clawhub/origin.json،‏ .clawhub/lock.json و skills info --json را بررسی می‌کند.
pnpm test:docker:live-cli-backend:claude, :claude:resume, :claude:mcp کاوش‌های زنده و متمرکز پشتیبان CLI؛ Gemini نام‌های مستعار متناظر :resume و :mcp را دارد.
pnpm test:docker:openwebui OpenClaw و Open WebUI کانتینری‌شده: ورود به سامانه، بررسی /api/models و اجرای یک گفت‌وگوی واقعیِ عبور‌داده‌شده از پراکسی از طریق /api/chat/completions. به یک کلید قابل‌استفاده برای مدل زنده نیاز دارد و یک تصویر خارجی را دریافت می‌کند؛ انتظار نمی‌رود مانند مجموعه‌های واحد/E2E در CI پایدار باشد.
pnpm test:docker:mcp-channels کانتینر Gateway دارای داده اولیه، به‌همراه کانتینر کلاینتی که openclaw mcp serve را اجرا می‌کند: کشف مکالمه مسیریابی‌شده، خواندن رونوشت‌ها، فراداده پیوست، رفتار صف رویداد زنده، مسیریابی ارسال خروجی و اعلان‌های کانال و مجوز به سبک Claude روی پل واقعی stdio (اعتبارسنجی، فریم‌های خام stdio مربوط به MCP را مستقیماً می‌خواند).
pnpm test:docker:upgrade-survivor بسته tarball را روی نمونه‌ای نامرتب از کاربر قدیمی نصب می‌کند، به‌روزرسانی بسته و doctor غیرتعاملی را بدون کلیدهای زنده ارائه‌دهنده/کانال اجرا می‌کند، یک Gateway روی local loopback راه‌اندازی می‌کند و بررسی می‌کند که عامل‌ها، پیکربندی کانال، فهرست‌های مجاز Plugin، فضای کاری، فایل‌های نشست، وضعیت قدیمی و منسوخ وابستگی Plugin، راه‌اندازی و وضعیت RPC حفظ شوند.
pnpm test:docker:published-upgrade-survivor به‌طور پیش‌فرض openclaw@latest را نصب می‌کند، فایل‌های واقع‌گرایانه کاربر موجود را مقداردهی اولیه می‌کند، با دستورالعمل ازپیش‌آماده openclaw config set پیکربندی می‌کند، به بسته tarball به‌روزرسانی می‌کند، doctor غیرتعاملی را اجرا می‌کند، .artifacts/upgrade-survivor/summary.json را می‌نویسد و /healthz،‏ /readyz و وضعیت RPC را بررسی می‌کند. با OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC بازنویسی کنید، با OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS یک ماتریس را گسترش دهید یا با OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues نمونه‌های سناریو را اضافه کنید (شامل configured-plugin-installs و stale-source-plugin-shadow). پذیرش بسته این موارد را به‌صورت published_upgrade_survivor_baseline(s) / _scenarios ارائه می‌کند و توکن‌های فراداده‌ای مانند last-stable-4 یا all-since-2026.4.23 را تفکیک می‌کند.
pnpm test:docker:update-migration چارچوب آزمون بقای ارتقای نسخه منتشرشده در سناریوی plugin-deps-cleanup که به‌طور پیش‌فرض از openclaw@2026.4.23 آغاز می‌شود. گردش‌کار Update Migration این مورد را با baselines=all-since-2026.4.23 گسترش می‌دهد تا پاک‌سازی وابستگی Plugin پیکربندی‌شده را خارج از CI انتشار کامل اثبات کند.
pnpm test:docker:plugins آزمون دود نصب/به‌روزرسانی برای مسیر محلی، file:، بسته‌های رجیستری npm با وابستگی‌های بالاکشیده‌شده، ارجاع‌های متغیر git، نمونه‌های ClawHub، به‌روزرسانی‌های بازارچه و فعال‌سازی/بازرسی بسته Claude.

دروازه محلی PR

برای بررسی‌های محلی فرود/دروازه PR، فرمان‌های زیر را اجرا کنید:

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

اگر pnpm test روی میزبانی تحت بار دچار شکست ناپایدار شد، پیش از درنظرگرفتن آن به‌عنوان پسرفت، یک بار دیگر اجرا کنید؛ سپس با pnpm test <path/to/test> آن را ایزوله کنید. برای میزبان‌های دارای محدودیت حافظه:

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

ابزارهای عملکرد آزمون

  • pnpm test:perf:imports: گزارش مدت‌زمان import و تفکیک import در Vitest را فعال می‌کند، درحالی‌که برای هدف‌های صریح فایل/دایرکتوری همچنان از مسیریابی lane محدودشده استفاده می‌کند. pnpm test:perf:imports:changed همان پروفایل‌گیری را به فایل‌های تغییرکرده از زمان origin/main محدود می‌کند.
  • pnpm test:perf:changed:bench -- --ref <git-ref> مسیر مسیریابی‌شدهٔ حالت تغییرات را برای همان diff ثبت‌شدهٔ git با اجرای بومی پروژهٔ ریشه بنچمارک می‌کند؛ pnpm test:perf:changed:bench -- --worktree مجموعه‌تغییرات worktree فعلی را بدون نیاز به commit اولیه بنچمارک می‌کند.
  • pnpm test:perf:profile:main یک پروفایل CPU برای رشتهٔ اصلی Vitest در .artifacts/vitest-main-profile می‌نویسد؛ pnpm test:perf:profile:runner پروفایل‌های CPU و heap را برای اجراکنندهٔ تست‌های واحد در .artifacts/vitest-runner-profile می‌نویسد.
  • pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: همهٔ پیکربندی‌های برگِ Vitest در مجموعه‌آزمون کامل را به‌صورت ترتیبی اجرا می‌کند و داده‌های مدت‌زمان گروه‌بندی‌شده را همراه با مصنوعات JSON/گزارش هر پیکربندی می‌نویسد. گزارش‌های مجموعه‌آزمون کامل به‌طور پیش‌فرض فایل‌ها را ایزوله می‌کنند تا گراف‌های ماژولِ باقی‌مانده و مکث‌های GC ناشی از فایل‌های قبلی به assertionهای بعدی منظور نشوند؛ -- --no-isolate را فقط هنگام پروفایل‌گیری عمدی از انباشت worker مشترک ارسال کنید. عامل عملکرد آزمون پیش از تلاش برای رفع تست‌های کند، از این مورد به‌عنوان خط مبنا استفاده می‌کند. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json گزارش‌های گروه‌بندی‌شده را پس از تغییری با تمرکز بر عملکرد مقایسه می‌کند.
  • اجراهای shard کامل، افزونه و الگوی include، داده‌های زمان‌بندی محلی را در .artifacts/vitest-shard-timings.json به‌روزرسانی می‌کنند؛ اجراهای بعدیِ کل پیکربندی از این زمان‌بندی‌ها برای متعادل‌کردن shardهای کند و سریع استفاده می‌کنند. shardهای CI با الگوی include نام shard را به کلید زمان‌بندی می‌افزایند تا زمان‌بندی shardهای فیلترشده بدون جایگزین‌کردن داده‌های زمان‌بندی کل پیکربندی قابل‌مشاهده بماند. برای نادیده‌گرفتن مصنوع زمان‌بندی محلی، OPENCLAW_TEST_PROJECTS_TIMINGS=0 را تنظیم کنید.

بنچمارک‌ها

تأخیر مدل (scripts/bench-model.ts)
bash
pnpm tsx scripts/bench-model.ts --runs 10

متغیرهای محیطی اختیاری: MINIMAX_API_KEY، MINIMAX_BASE_URL، MINIMAX_MODEL، ANTHROPIC_API_KEY. پرامپت پیش‌فرض: «با یک کلمه پاسخ بده: ok. بدون نشانه‌گذاری یا متن اضافی.»

راه‌اندازی CLI (scripts/bench-cli-startup.ts)
bash
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

پیش‌تنظیم‌ها:

  • startup: --version، --help، health، health --json، status --json، status
  • real: health، status، status --json، sessions، sessions --json، tasks --json، tasks list --json، tasks audit --json، agents list --json، gateway status، gateway status --json، gateway health --json، config get gateway.port
  • all: ترکیب هر دو پیش‌تنظیم

خروجی برای هر فرمان شامل sampleCount، میانگین، p50، p95، کمینه/بیشینه، توزیع کد خروج/سیگنال و حداکثر RSS است. --cpu-prof-dir / --heap-prof-dir برای هر اجرا پروفایل‌های V8 می‌نویسند.

خروجی ذخیره‌شده: pnpm test:startup:bench:smoke در .artifacts/cli-startup-bench-smoke.json می‌نویسد؛ pnpm test:startup:bench:save در .artifacts/cli-startup-bench-all.json می‌نویسد (runs=5 warmup=1). fixture ثبت‌شده در مخزن: test/fixtures/cli-startup-bench.json که با pnpm test:startup:bench:update تازه‌سازی و با pnpm test:startup:bench:check مقایسه می‌شود.

راه‌اندازی Gateway (scripts/bench-gateway-startup.ts)

به‌طور پیش‌فرض از ورودی CLI ساخته‌شده در dist/entry.js استفاده می‌کند؛ ابتدا pnpm build را اجرا کنید. برای اندازه‌گیری اجراکنندهٔ کد منبع، به‌جای آن --entry scripts/run-node.mjs را ارسال کنید و نتایجش را از خطوط مبنای ورودی ساخته‌شده جدا نگه دارید.

bash
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

شناسه‌های حالت: default، skipChannels (راه‌اندازی کانال رد می‌شود)، oneInternalHook، allInternalHooks، fiftyPlugins (۵۰ Plugin مانیفست)، fiftyStartupLazyPlugins (۵۰ Plugin مانیفست با بارگذاری تنبل هنگام راه‌اندازی).

خروجی شامل نخستین خروجی فرایند، /healthz، /readyz، زمان گزارش آغاز گوش‌دادن HTTP، زمان گزارش آماده‌شدن Gateway، زمان CPU، نسبت هستهٔ CPU، حداکثر RSS، heap، معیارهای ردگیری راه‌اندازی، تأخیر حلقهٔ رویداد و معیارهای جزئیات جدول جست‌وجوی Plugin است. اسکریپت در محیط Gateway فرزند، OPENCLAW_GATEWAY_STARTUP_TRACE=1 را تنظیم می‌کند.

/healthz نشان‌دهندهٔ زنده‌بودن است (سرور HTTP می‌تواند پاسخ دهد). /readyz نشان‌دهندهٔ آمادگی قابل‌استفاده است (sidecarهای Plugin راه‌اندازی، کانال‌ها و کارهای پس از اتصال که برای آمادگی حیاتی‌اند، پایدار شده‌اند). hookهای راه‌اندازی به‌صورت ناهمگام dispatch می‌شوند و بخشی از تضمین آمادگی نیستند. زمان گزارش آمادگی، timestamp داخلی Gateway است که برای انتساب در سمت فرایند مفید است، اما جایگزین probe خارجی /readyz نیست.

هنگام مقایسهٔ تغییرات، از خروجی JSON یا --output استفاده کنید. از --cpu-prof-dir فقط زمانی استفاده کنید که خروجی ردگیری به import، کامپایل یا کاری محدودشده به CPU اشاره می‌کند که زمان‌بندی مراحل به‌تنهایی قادر به توضیح آن نیست.

راه‌اندازی مجدد Gateway (scripts/bench-gateway-restart.ts)

فقط macOS و Linux (برای راه‌اندازی مجدد درون‌فرایندی از SIGUSR1 استفاده می‌کند؛ در Windows فوراً با شکست مواجه می‌شود). همان ورودی ساخته‌شدهٔ پیش‌فرض و بازنویسی --entry scripts/run-node.mjs که در راه‌اندازی Gateway در بالا آمده است.

bash
pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1

شناسه‌های حالت: skipChannels، skipChannelsAcpxProbe (probe راه‌اندازی ACPX روشن)، skipChannelsNoAcpxProbe (probe خاموش)، default، fiftyPlugins.

خروجی شامل /healthz بعدی، /readyz بعدی، زمان ازکارافتادگی، زمان‌بندی آمادگی راه‌اندازی مجدد، CPU، RSS، معیارهای ردگیری راه‌اندازی برای فرایند جایگزین و معیارهای ردگیری راه‌اندازی مجدد برای مدیریت سیگنال، تخلیهٔ کار فعال، مراحل بستن، شروع بعدی، زمان‌بندی آمادگی و snapshotهای حافظه است. اسکریپت OPENCLAW_GATEWAY_STARTUP_TRACE=1 و OPENCLAW_GATEWAY_RESTART_TRACE=1 را تنظیم می‌کند.

از این بنچمارک زمانی استفاده کنید که تغییری سیگنال‌دهی راه‌اندازی مجدد، مدیریت‌کننده‌های بستن، راه‌اندازی پس از راه‌اندازی مجدد، خاموش‌سازی sidecar، تحویل سرویس یا آمادگی پس از راه‌اندازی مجدد را تحت‌تأثیر قرار می‌دهد. برای جداسازی سازوکارهای Gateway از راه‌اندازی کانال، با skipChannels شروع کنید؛ فقط پس از آنکه حالت محدود مسیر راه‌اندازی مجدد را توضیح داد، از default یا حالت‌های سنگین از نظر Plugin استفاده کنید. معیارهای ردگیری سرنخ‌های انتساب‌اند، نه حکم نهایی — تغییر راه‌اندازی مجدد را بر اساس چندین نمونه، بازهٔ مالک متناظر، رفتار /healthz//readyz و قرارداد راه‌اندازی مجدد قابل‌مشاهده برای کاربر ارزیابی کنید.

E2E راه‌اندازی اولیه (Docker)

اختیاری؛ فقط برای تست‌های دودِ راه‌اندازی اولیه در کانتینر لازم است. جریان کامل شروع سرد در یک کانتینر پاک Linux:

bash
scripts/e2e/onboard-docker.sh

wizard تعاملی را از طریق pseudo-tty هدایت می‌کند، فایل‌های پیکربندی/workspace/session را تأیید می‌کند، سپس Gateway را راه‌اندازی کرده و openclaw health را اجرا می‌کند.

تست دودِ import کردن QR (Docker)

اطمینان می‌دهد helper نگه‌داری‌شدهٔ runtime مربوط به QR در runtimeهای پشتیبانی‌شدهٔ Docker Node بارگذاری می‌شود (Node 24 پیش‌فرض، سازگار با Node 22):

bash
pnpm test:docker:qr

مرتبط

Was this useful?
On this page

On this page