الاختبارات

• حزمة الاختبار الكاملة (مجموعات الاختبارات، الاختبارات الحية، Docker): الاختبار
• التحقق من التحديثات وحزم Plugin: اختبار التحديثات وPlugins

الإعداد الافتراضي للوكيل

تشغّل جلسات الوكيل الاختبارات وعمليات التحقق كثيفة الحوسبة عن بُعد عبر Crabbox. تستخدم شيفرة المشرفين الموثوقين Blacksmith Testbox افتراضيًا. يقوم سير عمل Testbox المُعدّ بتحميل بيانات الاعتماد، لذلك يجب أن تستخدم شيفرة المساهمين غير الموثوقين أو التفرعات CI للتفرعات بلا أسرار، أو AWS Crabbox المباشر والمُنقّى بدلًا منه.

عندما يُرجّح أن تتطلب مهمة شيفرة موثوقة اختبارات أو إثباتًا مكثفًا، ابدأ الإحماء المسبق فورًا في جلسة أوامر تعمل في الخلفية، وواصل العمل أثناء تجهيزها، وأعِد استخدام المعرّف tbx_... المُعاد، وزامن نسخة العمل الحالية في كل تشغيل، وأوقفها قبل التسليم:

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 موثوقة ونظيفة، واجلب طلب السحب البعيد فقط باستخدام --fresh-pr؛ ولا تنفّذ أبدًا غلاف نسخة العمل غير الموثوقة أو إعداداتها محليًا. ألغِ ضبط CRABBOX_AWS_INSTANCE_PROFILE، وأخفق بأمان ما لم تكن قيمة aws.instanceProfile المحلولة فارغة. قبل أي تثبيت أو اختبار، استخدم أدوات موثوقة ذات مسارات مطلقة لفرض رمز IMDSv2، وإثبات أن نقطة نهاية بيانات اعتماد IAM تعيد 404، والتحقق من أن git rev-parse HEAD البعيد يساوي قيمة SHA الكاملة لرأس طلب السحب الذي تمت مراجعته. اربط الحجز بقيمة SHA هذه وأوقفه وأعد إحماءه عند تغيّر الرأس. ارفع scripts/crabbox-untrusted-bootstrap.sh الموثوق من نسخة main نظيفة إلى جانب --fresh-pr؛ فهو يثبّت إصدارات Node وpnpm المثبّتة، ويتحقق من SHA وتثبيت إصدار مدير الحزم، ويعزل HOME، ويثبّت الاعتماديات، ثم ينفّذ الاختبار المطلوب. إذا تعذّر على الوسيط إثبات عدم وجود دور أو عدم وجود طلب سحب بعيد، فاستخدم CI للتفرعات بلا أسرار. لا تستخدم hydrate-github أو --no-sync أو سير عمل Testbox محمّلًا ببيانات الاعتماد. ألغِ ضبط جميع تجاوزات CRABBOX_TAILSCALE*، وافرض --network public --tailscale=false، وامسح أعلام عقدة الخروج/الشبكة المحلية، واشترط أن يفيد 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 المفوّضة بالحالة cancelled بعد نجاح أمر SSH لأن Testbox يُوقَف من خارج إجراء إبقاء الاتصال؛ تحقّق من ملخص الغلاف ومخرجات الأمر قبل اعتبار ذلك إخفاقًا.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: يُبقي تسلسل عمليات التحقق الثقيلة داخل شجرة العمل الحالية بدلًا من دليل Git المشترك لأوامر مثل pnpm check:changed وpnpm test ... المستهدف. استخدمه فقط على المضيفات المحلية عالية السعة عندما تشغّل عمدًا عمليات تحقق مستقلة عبر أشجار عمل مرتبطة.

الأوامر الأساسية

تنتهي عمليات تشغيل غلاف الاختبار بملخص قصير [test] passed|failed|skipped ... in ...؛ ويظل سطر المدة الخاص بـ Vitest هو تفاصيل كل شظية.

حالة الاختبار المشتركة ومساعدات العمليات

• 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 والتقاط السجلات والتنظيف في مكان واحد.
• يمكن لمسارات Docker/Bash الخاصة باختبارات E2E التي تستورد 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 فقط كخيار احتياطي محلي صريح.
• اختبارات TUI PTY: يشغّل 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 جميع أجزاء الامتدادات/الإضافات. تعمل Plugins القنوات الثقيلة وPlugin المتصفح وOpenAI كأجزاء مخصصة؛ وتبقى مجموعات Plugins الأخرى مجمّعة. يشغّل pnpm test extensions/<id> مسار Plugin مضمّنة واحدة.
• تُربط ملفات المصدر التي لها اختبارات شقيقة بذلك الاختبار الشقيق قبل الرجوع إلى أنماط glob أوسع للدليل. تستخدم تعديلات الأدوات المساعدة ضمن 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 إعداد عقود Plugins، لأن مشروعي 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 وعمّالًا متكيفين في 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 مرة واحدة في أرشيف npm، وتبني/تعيد استخدام صورة تشغيل أساسية تتضمن Node/Git وصورة وظيفية تثبّت ذلك الأرشيف في /app، ثم تشغّل مسارات اختبارات الدخان في Docker من خلال مجدول موزون. يمثّل scripts/package-openclaw-for-docker.mjs أداة التحزيم الوحيدة المحلية/الخاصة بالتكامل المستمر، ويتحقق من الأرشيف ومن dist/postinstall-inventory.json قبل أن يستخدمه Docker.

• الصورة الأساسية (OPENCLAW_DOCKER_E2E_BARE_IMAGE): مسارات المثبّت/التحديث/تبعيات Plugins؛ تُركّب الأرشيف المبني مسبقًا بدلًا من نسخ مصادر المستودع.
• الصورة الوظيفية (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 خطة التكامل المستمر التي يملكها المجدول (المسارات، وأنواع الصور، واحتياجات الحزمة/الصورة المباشرة، وسيناريوهات الحالة، وعمليات التحقق من بيانات الاعتماد) دون بناء Docker أو تشغيله.

عناصر التحكم في الجدولة (متغيرات البيئة، والقيم الافتراضية بين قوسين):

نمط متغيرات البيئة لحدود الموارد هو OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT (يُحوّل اسم المورد إلى أحرف كبيرة، وتُدمج المحارف غير الأبجدية الرقمية في _).

سلوك آخر: يجري المشغّل فحوصات Docker التمهيدية افتراضيًا، وينظّف حاويات OpenClaw E2E القديمة، ويشارك ذاكرات التخزين المؤقت لأدوات 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 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 إعداد تقارير مدة الاستيراد وتفاصيله في Vitest، مع الاستمرار في استخدام توجيه المسارات المحددة للأهداف الصريحة من الملفات/الأدلة. ويحصر pnpm test:perf:imports:changed التحليل نفسه في الملفات التي تغيرت منذ origin/main.
• يقيس pnpm test:perf:changed:bench -- --ref <git-ref> أداء مسار الوضع المتغير الموجّه مقارنةً بالتشغيل الأصلي للمشروع الجذري لنفس فرق git المُثبَت؛ بينما يقيس pnpm test:perf:changed:bench -- --worktree أداء مجموعة تغييرات شجرة العمل الحالية من دون تثبيتها أولًا.
• يكتب pnpm test:perf:profile:main ملف تعريف CPU لخيط Vitest الرئيسي (.artifacts/vitest-main-profile)؛ ويكتب pnpm test:perf:profile:runner ملفات تعريف CPU والذاكرة الديناميكية لمشغّل اختبارات الوحدة (.artifacts/vitest-runner-profile).
• يشغّل pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json كل إعداد فرعي لمجموعة Vitest الكاملة تسلسليًا، ويكتب بيانات المدة المجمعة، بالإضافة إلى عناصر JSON/السجل لكل إعداد. تعزل تقارير المجموعة الكاملة الملفات افتراضيًا، كي لا تُحتسب مخططات الوحدات المحتفظ بها وتوقفات GC الناتجة من الملفات السابقة على التأكيدات اللاحقة؛ ولا تمرّر -- --no-isolate إلا عند تحليل تراكم العامل المشترك عمدًا. يستخدم وكيل أداء الاختبارات هذا خطًا أساسًا قبل محاولة إصلاح الاختبارات البطيئة. يقارن pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json التقارير المجمعة بعد تغيير يركز على الأداء.
• تحدّث عمليات تشغيل الأجزاء الكاملة وأجزاء الإضافات وأجزاء نمط التضمين بيانات التوقيت المحلية في .artifacts/vitest-shard-timings.json؛ وتستخدم عمليات التشغيل اللاحقة للإعداد الكامل تلك التوقيتات لموازنة الأجزاء البطيئة والسريعة. تُلحق أجزاء CI ذات نمط التضمين اسم الجزء بمفتاح التوقيت، ما يُبقي توقيتات الأجزاء المرشّحة ظاهرة من دون استبدال بيانات توقيت الإعداد الكامل. عيّن OPENCLAW_TEST_PROJECTS_TIMINGS=0 لتجاهل عنصر التوقيت المحلي.

قياسات الأداء

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

الاختبار الشامل للتأهيل (Docker)

اختياري؛ ولا يلزم إلا لاختبارات الدخان للتأهيل داخل الحاويات. تدفق بدء التشغيل البارد الكامل داخل حاوية Linux نظيفة:

scripts/e2e/onboard-docker.sh

يشغّل المعالج التفاعلي عبر طرفية زائفة، ويتحقق من ملفات الإعداد/مساحة العمل/الجلسة، ثم يبدأ Gateway ويشغّل openclaw health.

اختبار دخان استيراد QR (Docker)

يضمن تحميل مساعد وقت تشغيل QR المُصان ضمن بيئات تشغيل Docker Node المدعومة (Node 24 افتراضيًا، ومتوافق مع Node 22):

pnpm test:docker:qr

ذو صلة

• الاختبار
• الاختبار المباشر
• اختبار التحديثات والـPlugin