الوكيل المحلي (vera-agent)

شغِّل اختبارات Vera على جهازك، وتبقى الخدمة السحابية لوحة التحكم. فـ vera-agent مشغِّل صغير تثبِّته محليًّا: يستأجر التشغيلات المنتظرة عبر واجهة برمجية HTTPS موثَّقة، ويقود Playwright مقابل تطبيقك، ويرفع الفيديو والأثر (trace) ولقطات الشاشة، ثم يُبلغ بالنتائج. وتحتفظ Vera بكل ما تستعمله الآن — لوحة التحكم، والمشاريع، وسجلّ التشغيلات، والتوليد بالذكاء الاصطناعي، والإصلاح الذاتي — غير أن المتصفح يعمل بجوار تطبيقك بدل أن يعمل في السحابة.

الإصلاح الذاتي في تشغيلات الوكيل اختياري. إصلاح مُحدِّد معطوب استدعاءٌ للذكاء الاصطناعي تُحتسب كلفته على مساحة عملك، ولذلك لا يفعله الوكيل إلا إذا فعَّله مسؤول مساحة العمل (settings.agent.selfHeal، PUT /api/org/settings)، وفي خطة تشمل الإصلاح. والافتراضي أنه مُعطَّل، وهي القاعدة نفسها التي تتبعها بقية Vera: زر الإصلاح، وإعداد الإصلاح التلقائي في المشروع، وخيار الإصلاح الذاتي في التوليد بالذكاء الاصطناعي كلها اختيارات صريحة. والخطوة التي تعذَّر إصلاحها لأن الإصلاح مُعطَّل تقول ذلك في التشغيل.

لماذا وُجد:

• اختبر http://localhost دون أي نفق. المتصفح يعمل حيث يعمل تطبيقك، فالمضيفات الخاصة ومضيف الحلقة المحلية (loopback) في المتناول مباشرة — لا ngrok، ولا كشف عنوان معاينة.
• جهازك، وإعدادك. تجهيزات الإعداد من نوع command (سكربتات البذر، ومستخدمو الاختبار) تعمل على مسار الوكيل لأنه جهازك أنت؛ وتبقى الإجراءات نفسها مُعطَّلة على عمّال السحابة المشتركين.
• لا بيانات اعتماد لقاعدة البيانات على الوكيل — أبدًا. لا يحمل الوكيل DATABASE_URL قطّ. فكل ما يمسّ الحفظ (صفوف التشغيل، وإطارات التقدُّم، ومفاتيح الملفات الناتجة) يمرّ عبر الخادم، من خلال الواجهة /api/agent/v1 الموثَّقة بالرمز. فالوكيل موثوق على مستوى المؤسسة، وغير موثوق على مستوى المنصّة.

1. البدء السريع

الحزمة منشورة: npx vera-agent <command> يعمل دون نسخة من المستودع، و npm install -g vera-agent يمنحك الأداة على الدوام. وكل أمر أدناه مكتوب vera-agent عن قصد — فالحزمة تثبِّت كذلك اسمًا مختصرًا هو vera، لكن npx vera يجلب حزمة لا صلة لها، حجز أحدهم ذلك الاسم لها عام 2022، فالاسم المختصر لا يكون آمنًا إلا بعد تثبيت vera-agent، ولا يصحّ أبدًا في أمر npx مباشر.

1. أنشئ رمز تسجيل. في لوحة التحكم افتح Settings ← Agents وأنشئ وكيلًا. يُعرض الرمز vera_agent_… مرة واحدة — فانسخه الآن. (وهو ليس رمز CI من نوع vera_… — انظر الإعداد.)

2. سجِّل هذا الجهاز:

   npx vera-agent login --url https://app.vera.dev --token vera_agent_xxx

   يتحقق هذا من الرمز مقابل الخادم (مصافحة /hello)، ويكتب ~/.vera/agent.json بصلاحيات مالكه وحده (chmod 600).

3. ابدأ استئجار التشغيلات:

   npx vera-agent start

   التشغيل الأول يثبِّت Playwright Chromium تلقائيًّا إن لم يكن موجودًا. اتركه يعمل؛ واضغط Ctrl+C لإنهاء ما بين يديه والخروج.

4. وجِّه بيئةً إلى الوكيل. في إحدى بيئات المشروع، اضبط هدف التشغيل على agent (انظر توجيه البيئات). ثم اضغط Run في لوحة التحكم: يدخل التشغيل قائمة الانتظار، فيستلمه وكيلك، وتتدفَّق الخطوات حيّةً إلى عرض التشغيل كما في التشغيل السحابي تمامًا.

أتريد فحصًا لمرة واحدة الآن بدل عامل دائم؟ vera-agent verify يشغِّل اختبارًا — أو قائمة خطوات لم تُحفظ قطّ — في هذه العملية نفسها مقابل localhost لديك، دون قائمة انتظار. أما ربط المستودع نفسه (وما يحيط به من تهيئة للوكيل البرمجي) فهو vera-agent init.

2. الأوامر

أوامر التنفيذ (start، run، watch، verify، status، doctor) تقرأ الإعداد من ~/.vera/agent.json مع إمكان تجاوزه بمتغيرات البيئة؛ أما init وcheck وaffected فهي الاستثناء، وتستعمل .vera/config.json مع ~/.vera/cli.json (انظر الإعداد). وcheck --run --local هو الأمر الوحيد الذي يحتاج الاثنين معًا: رمز CLI لقراءة الخريطة، والتسجيل للتنفيذ.

ومتاح كذلك: --help / help، و--version / version.

init

vera-agent init --url https://app.vera.dev --token vera_xxxxx

يوجِّه المستودع الذي تشغِّله فيه إلى مشروع في Vera، ويهيِّئ ما يحيط به للوكيل البرمجي. يستدلّ على المشروع من origin الخاص بالمستودع (الربط بـ GitHub أولًا، ثم التطابق في الاسم؛ فإن التبس الأمر طلب --project <id>، وإن لم يتطابق شيء أحالك إلى لوحة التحكم، لأن الرمز لا يستطيع إنشاء المشاريع)، ثم يكتب:

• .vera/config.json — {apiUrl, projectId, repoPathPrefix}. احفظه في المستودع؛ فهو لا يحمل أي بيانات اعتماد عن قصد.
• ~/.vera/cli.json — الرمز vera_…، بصلاحيات chmod 600، مرتَّبًا حسب apiUrl، فلا يحتاج مستودع ثانٍ موجَّه إلى النشر نفسه إلا إلى --url.

…ثم يسجِّل، ما لم يُطلب منه غير ذلك، خادم MCP باسم vera (--mcp-scope local يكتب في ملفك الخاص ~/.claude.json؛ و--mcp-scope project يدمج مُدخلًا قائمًا على ${VERA_TOKEN} في ملف .mcp.json المحفوظ في المستودع؛ و--no-mcp يتخطّى ذلك)، ويضيف كتلة تعليمات محاطة بعلامات حارسة إلى ملف AGENTS.md أو CLAUDE.md في المستودع (و--no-agents-md يتخطّاها). وتكراره لا يغيِّر شيئًا، ويقول ذلك.

والرمز هنا رمز CI (vera_…، من Settings ← CI Tokens) — لا رمز التسجيل vera_agent_… الذي يأخذه login. وهو يحتاج في النسخة السحابية ميزة api-access من خطة Pro؛ فرمز مساحة العمل المجانية يعمل مع MCP، لكن init سيُبلغ بأن الرمز غير مقبول. والشرح الكامل خطوةً بخطوة: الخطوات الأولى.

login

vera-agent login --url https://app.vera.dev --token vera_agent_xxx

• --url — جذر واجهة Vera البرمجية لديك (لا حاجة إلى شرطة مائلة في آخره).
• --token — رمز التسجيل vera_agent_… من Settings ← Agents.

إن كان الوكيل أقدم من minAgentVersion الذي يطلبه الخادم، يحفظ login بيانات اعتمادك على أي حال لكنه يحذِّر بوضوح (فالتسجيل صالح؛ والوكيل يحتاج ترقية لا أكثر). أما الرمز الخاطئ أو العنوان الذي لا يُبلغ فيفشلان دون أن يُكتب شيء.

start

يستأجر العمل في حلقة استطلاع طويل مدتها 25 ثانية، وينفِّذ كل تشغيل يستلمه مع نبضات ونقل حيّ للتقدُّم. وعند SIGINT/SIGTERM يُنهي ما بين يديه: يكفّ عن الاستئجار، ويُتمّ التشغيل الجاري، ويُغلق المتصفحات، ثم يخرج (ومهلة قصوى مدتها 60 ثانية تضمن الخروج ولو علِق تشغيل).

run --test <testId>

يستأجر إلى أن يستلم المهمة المنتظرة للاختبار المطلوب، فينفِّذها، ويخرج بـ 0 عند النجاح / 1 عند الفشل. وإن صادف أن استلم مهمة اختبار آخر قبلها نفَّذها كذلك (فالاستئجار لا يُردّ)، ثم يواصل البحث. ويستسلم برمز خروج غير صفري بعد نحو 60 ثانية لا يجد فيها عملًا قابلًا للاستئجار.

run --drain [--timeout <s>]

شكل الدفعات لـ CI: يستأجر التشغيلات المنتظرة وينفِّذها باستمرار، ثم يخرج من تلقاء نفسه — حين تهدأ قائمة الانتظار (--idle-exits استطلاعات متتالية بلا عمل، والافتراضي 2 ⇐ نحو 50 ثانية) أو حين تنقضي مهلة --timeout <seconds> بالساعة الفعلية (0 أو غيابه = بلا حدّ؛ والتشغيل الجاري يكتمل دائمًا أولًا). ورمز الخروج إجمالي: 0 نجح الكل أو لم يكن في الانتظار شيء، 1 فشل أيٌّ منها، 2 خطأ قاتل في الوكيل (المصادقة/المصافحة). ويطبع سطر ملخَّص لكل تشغيل وسطرًا إجماليًّا في النهاية. وانظر دليل CI-rider لإجراء GitHub وحساب الكلفة.

verify --test <id> / verify --project <id> --steps <file|->

شكل المطوِّر الجالس أمام تطبيقه: تشغيل واحد، في هذه العملية، مقابل خادم التطوير لديك، ينتهي في ثوانٍ. لا قائمة انتظار، ولا استئجار، ولا انتظار عاملٍ يلتقطه — وهذا ما يجعله صالحًا في دورة تعديل ← فحص ← تعديل، وما يجعل http://localhost:3000 قابلًا للاختبار من لوحة تحكم سحابية.

# an ad-hoc check straight from stdin
echo '[{"action":"goto","url":"/orders"},
       {"action":"assert","selector":"#total","assertType":"text","value":"42 orders"}]' \
  | vera-agent verify --project prj_123 --steps - --role admin

# or replay something already saved
vera-agent verify --test tst_456 --json

• يأخذ --steps ملف JSON، أو - للإدخال القياسي، يحوي إما مصفوفة مجرَّدة أو {"steps": [...]} (وهو الشكل الذي تأخذه أداة MCP run_scenario). وتُولَّد لك قيم id الناقصة في الخطوات — فهي معرِّفات محلية للتشغيل، وكتابة nanoid بيدك ليست من شأنك.
• يتطلب --steps وجود --project (فقائمة خطوات مستقلة لا اختبار ترث منه المشروع). وقدِّم واحدًا فقط من --test أو --steps.
• --env <name> / --role <roleId> يختاران ملف البيئة ودور المصادقة الملتقَط؛ و--label <text> يسمّي التشغيل في السجلّ.
• --json يطبع كائنًا واحدًا مقروءًا آليًّا على stdout وينقل كل سطر موجَّه للبشر إلى stderr، فيمكن تمريره إلى jq أو إلى وكيل.
• رموز الخروج كرموز run --drain: 0 نجح، 1 فشل، 2 لم يقع التشغيل (خيارات خاطئة، أو لا تسجيل، أو لا Chromium).

ويبقى تشغيلًا حقيقيًّا: تُنشئ لوحة التحكم صفَّه، وتستقبل نتائج الخطوات والملفات الناتجة، وتحتسب الاستدعاء — فيشترك الفحص المحلي والسحابي في سجلّ واحد بدل أن ينقسما. الذي يعمل محليًّا هو المتصفح، لا حفظ السجلات.

ويحتاج verify بيانات التسجيل (~/.vera/agent.json، التي يكتبها login)، لا رمز init. فإن لم تشغِّل إلا init، خرج بـ 2 مع Cannot verify — agent handshake failed.

watch <dir> [--tag <tag> | --suite <id>] [--debounce <ms>]

وضع الدورة الداخلية: يراقب مجلد شيفرة محليًّا، وعند كل حفظ يعيد تشغيل طائفة من الاختبارات مقابل التطبيق العامل على جهازك — وتتدفَّق النتائج إلى لوحة التحكم لحظيًّا (فهي تشغيلات وكيل عادية على ناقل SSE نفسه، run_events).

# Re-run every test tagged `watch` on save (the default):
vera-agent watch ./src

# Re-run a specific tag, or a suite, with a custom debounce:
vera-agent watch ./src --tag smoke
vera-agent watch . --suite suite_9f2 --debounce 800

كيف يعمل عند كل دفعة حفظ بعد التهدئة:

1. التهدئة (debounce) — تُجمع أحداث تغيُّر الملفات على نافذة هدوء (--debounce، والافتراضي 500ms)، فحفظ الكل عبر ملفات كثيرة يُطلق مرة واحدة، لا عشرات المرات.
2. الإطلاق — يستدعي الوكيل POST /api/agent/v1/watch-trigger بواحد فقط من {tag} / {suiteId}. فيحسم الخادم الاختبارات المطابقة، ويُدخل تشغيلًا واحدًا لكل اختبار، مثبَّتًا على هذا الوكيل (الحمولة pinnedAgentId)، ويُرجع {runIds, testCount}. ولا يستطيع استلام تلك المهام إلا هذا الوكيل.
3. الإنهاء — يستأجر الوكيل مهامه المثبَّتة وينفِّذها عبر الحلقة المعتادة، طابعًا سطرًا موجزًا لكل تشغيل، ثم يعود إلى المراقبة (فالعملية لا تخرج). والدفعات التي تصل أثناء الإنهاء تُجمع في مرور لاحق واحد.

نطاق الحسم (فالوكيل لا يحمل سياق مشروع، ولذلك):

• --tag يطابق على مستوى المؤسسة كلها — كل اختبار في مؤسستك يحمل ذلك الوسم (بعد تطبيعه)، عبر كل المشاريع. فوسم watch اختيار مقصود، وامتداده عبر المشاريع مقصود كذلك؛ فضع الوسم على الاختبارات القليلة التي تريد أن تشغِّلها دورة الحفظ لديك.
• --suite يعيد تشغيل أعضاء مجموعة الاختبارات (قائمة testIds الثابتة ∪ مرشِّحاتها الديناميكية — الوسوم / ما فشل مؤخرًا / المتقلّبة)، تمامًا كتشغيل المجموعة المعتاد.

وكل إطلاق يُدخل 50 اختبارًا على الأكثر (ويُسقط ما بعدها) حتى لا يُغرق وسمٌ واسع قائمة الانتظار. وCtrl+C يوقف المراقب، ويدع التشغيل الجاري يكتمل، ويُغلق المتصفحات، ويخرج (بمهلة قصوى 60 ثانية).

المسارات المُتجاهَلة: node_modules و.git وdist وكل ملف أو مجلد يبدأ بنقطة لا تُراقَب أبدًا. ملاحظة عن المنصّات: المراقبة التعاودية تستعمل fs.watch(..., { recursive: true }) الأصلية على macOS/Windows؛ أما على Linux (حيث لا يُدعم الوضع التعاودي) فيلجأ الوكيل إلى مراقب لكل مجلد يُنصب عبر الشجرة، ويُعاد نصبه حين تظهر مجلدات فرعية جديدة.

check / affected

السؤال الذي شكله الفرق لا الملف: أي الاختبارات تغطّي ما غيَّرتُه للتوّ؟ كلاهما يقرأ ربط المستودع (.vera/config.json مع رمز CLI من نوع vera_…)، ويسأل خريطة الأثر في الخادم، ويطبع الاختبارات مع الدليل الذي اختارها.

vera-agent check                  # read-only: map and report
vera-agent check --run --local    # …and run exactly that set, HERE
vera-agent affected src/lib/pricing.ts

والجزء الخاص بالوكيل المحلي هو --run --local. فهو ينفِّذ الاختبارات المتأثرة في هذه العملية عبر المسار نفسه الذي يسلكه verify — فتبلغ http://localhost:3000 — ولذلك يحتاج بيانات التسجيل فوق رمز CLI. فإن لم تكن موجودة خرج بـ 1 وطلب منك login؛ ولا يلجأ أبدًا إلى تفريغ قائمة الانتظار بدلًا من ذلك، لأن قائمة انتظار فارغة ستُجمَع في نتيجة خضراء لا تُثبت شيئًا. أما --run وحده (دون --local) فيشغِّل في السحابة، أيًّا كان هدف التشغيل في المشروع.

وكل ما سوى ذلك — الروابط الثلاثة، وما لا تراه الخريطة، و--strict، ورموز الخروج، وشكل الاستعمال في CI — تجده في أثر التغيير (vera check).

status

vera-agent 0.5.1

Enrollment:
  config file: /Users/you/.vera/agent.json
  api url:     https://app.vera.dev
  token:       …x9f2
  name:        my-laptop

Connectivity:
  reachable:   yes (protocol v1)
  version:     0.5.1 ≥ min 0.1.0 — OK

Playwright:
  chromium:    installed (/Users/you/Library/Caches/ms-playwright)

doctor

يشخِّص جاهزية الجهاز بجدول فحوص مع علاج قابل للتنفيذ: Node (‏20 فأعلى)، والتسجيل وإمكان بلوغ الخادم، ومتصفحات Playwright، وأدوات الجوال الأصلية — adb والأجهزة الموصولة، والأداة emulator وأجهزة AVD، وappium والمشغِّلات المثبَّتة (uiautomator2 / xcuitest)، وعلى macOS‏ Xcode والمحاكيات المتاحة. وكل سطر يقرأ OK / WARN / FAIL مع علاج في سطر واحد (brew install --cask android-platform-tools، npm i -g appium، appium driver install uiautomator2، …).

vera-agent 0.5.1 — doctor

[OK  ] Node          v20.x
[OK  ] Enrollment    https://app.vera.dev (token …x9f2)
[OK  ] Server        reachable — protocol v1, min agent 0.1.0
[WARN] Playwright    Chromium not found
                     ↳ vera-agent install-browsers
[OK  ] Mobile caps   android=yes, ios=no
[OK  ] adb           on PATH — 1 usable device(s) attached
[FAIL] Appium        not on PATH
                     ↳ npm i -g appium && appium driver install uiautomator2

Summary: 4 OK, 1 warnings, 1 failures.

رمز الخروج: 0 حين تنجح كل الفحوص المطلوبة. وفحوص الجوال تحذيرية فقط على وكيل مخصَّص لسطح المكتب (فغياب المحاكي لا يُفشِل doctor أبدًا)؛ ولا تصير FAIL (رمز الخروج 1) إلا حين يُعلن هذا الجهاز تلك القدرة — فالوكيل الذي يُعلن قدرة على الجوال ولا يستطيع تشغيله فعلًا (كأن يغيب Appium أو مشغِّل المنصّة) يُكشف في CI.

install-browsers

يغلِّف npx playwright install chromium. وstart/run يعرضان التثبيت تلقائيًّا عند أول استعمال كذلك (ويثبِّتان دون تدخُّل في طرفية غير تفاعلية)، فنادرًا ما تستدعيه مباشرة.

3. الإعداد

بيانتا اعتماد، وثلاثة ملفات

أشيع أخطاء الإعداد أن تفترض أن رمزًا واحدًا يفعل كل شيء. وليس كذلك:

لا يُحفظ أيٌّ من ملفَّي الرموز في المستودع أبدًا؛ أما .vera/config.json فمُعَدّ لذلك. وإن كنت تنوي ربط المستودع وتنفيذ التشغيلات على هذا الجهاز معًا، فشغِّل init وlogin — فهما خطوتان منفصلتان تكتبان بيانتَي اعتماد منفصلتين.

التجاوز بمتغيرات البيئة

يسكن الإعداد في ~/.vera/agent.json (يكتبه login، بصلاحيات chmod 600). وتتجاوز متغيرات البيئة الملف حقلًا حقلًا:

الأولوية (الأعلى أولًا): متغير البيئة ← ~/.vera/agent.json. وقيم البيئة تغلب حقلًا حقلًا، فتسجِّل مرة واحدة وتتجاوز العنوان أو الاسم وحده في استدعاء بعينه. والرمز بيانات اعتماد لحامله — فأبقِ الملف بصلاحيات 600 وفضِّل VERA_AGENT_TOKEN (من مخزن أسرار مثلًا) في CI.

ينفِّذ الوكيل تشغيلًا مستأجَرًا واحدًا في كل مرة أيًّا كانت قيمة QA_MAX_BROWSERS (فالسقف يحكم التوازي داخل التشغيل الواحد). ويُجهَّز الفيديو والأثر مؤقتًا تحت ~/.vera/data قبل الرفع.

المتصفحات، وكيف تمنع الوكيل من تنزيل واحد

قبل أن يشغِّل أي شيء، يتحقق الوكيل من أن ذاكرة متصفحات Playwright المؤقتة تحوي Chromium صالحًا للاستعمال — لا مجرد مجلد باسمه، فتُكشف الذاكرة المنزَّلة نصفًا أو المحذوفة نصفًا هنا بدل أن يفشل كل تشغيل عند الإقلاع.

وحين لا يوجد متصفح:

• في طرفية تفاعلية، يسألك أيثبِّت واحدًا؛
• في جلسة غير تفاعلية (أي مشغِّل CI)، يثبِّت واحدًا دون تدخُّل، حتى لا يعلق تشغيل مُبرمَج عند سؤال لا يستطيع أحد إجابته؛
• وفي الحالتين، إن لم يحصل على متصفح رفض التشغيل، وطلب منك تشغيل vera-agent install-browsers.

اضبط VERA_AGENT_NO_AUTO_INSTALL=true لرفض التنزيل. فيرفض الوكيل عندئذ فورًا مع العلاج نفسه، بدل أن يجلب مئات الميغابايتات. وهذا ما تريده على صورة CI تشحن Chromium أصلًا: لا تنزيل في كل مهمة، وفشل صريح إن كانت الصورة خاطئة. وكل قيمة غير false أو 0 أو no أو off تُعدّ رفضًا، فيمكن أن يبقى المتغير في ملف إعداد الطرفية ويُبدَّل بقيمته.

ولتثبيت متصفح عن قصد:

vera-agent install-browsers

4. توجيه البيئات

التوجيه يجري على مستوى بيئة المشروع (وفق الخطة §10 H4). وتحمل ProjectEnvironment:

• runTarget?: 'cloud' | 'agent' — أين تُنفَّذ التشغيلات مقابل هذه البيئة.
• تثبيتًا اختياريًّا عبر agentId — يقصر هذه البيئة على وكيل مسجَّل بعينه (وإلا استطاع أي وكيل متصل من وكلاء المؤسسة أن يستلمها).

وهناك كذلك هدف تشغيل افتراضي على مستوى المشروع ترثه البيئة حين لا تضبط هدفها الخاص. وحين تنتهي بيئةٌ إلى agent، يُدرج مسار تشغيل الاختبارات صفَّ تشغيل queued مع صفّ agent_jobs ثم يعود؛ فينتظر التشغيل وكيلًا يستأجره. أما البيئات الموجَّهة إلى السحابة فتبقى على المسار المعتاد داخل العملية / عبر قائمة الانتظار دون تغيير. وفي الحالتين يسجِّل التشغيل مَن نفَّذه في runs.executor ({kind:'agent', agentId, agentName} لتشغيلات الوكيل)، ويظهر التشغيل السحابي وتشغيل الوكيل في عرض التشغيل بالشكل نفسه.

ومعنى هذا أن المشروع الواحد يستطيع أن يضم، جنبًا إلى جنب، بيئة staging تعمل في السحابة وبيئة local تعمل على جهازك — الاختبارات نفسها، بهدف تنفيذ مختلف.

5. تشغيل تطبيقات الجوال الأصلية على الوكيل

يستطيع الوكيل أن يقود تطبيقًا أصليًّا (.apk/.ipa) على محاكٍ محلي، أو جهاز موصول بـ USB، أو محاكي iOS — وهو النظير المحلي لسحابة الأجهزة.

• إعلان القدرات. في كل مصافحة لـ start/run يكتشف الوكيل { mobileAndroid, mobileIos } ويعلنها (Android حين يُبلغ adb عن جهاز أو تكون الأداة emulator موجودة؛ وiOS على macOS مع أدوات المحاكي). ولا توجِّه لوحة التحكم مهمة جوال إلا إلى وكيل يعلن منصّة تلك المهمة — فالوكيل المخصَّص لسطح المكتب لا يستلم تشغيل جوال أبدًا.

• تنزيل التطبيق. حين يشير config.mobile.appArtifactId في اختبار جوال إلى تطبيق مرفوع، يحمل الاستئجار وصف التطبيق؛ فينزِّل الوكيل الملف عبر واجهة الوكيل الموثَّقة ويخزِّنه مؤقتًا تحت ~/.vera/apps/<appId>.<ext> (ولا يعيد التنزيل إلا إن غاب). ويتحقق الخادم من مفتاح التنزيل مقابل مشروع التشغيل المستأجَر — فلا يستطيع وكيل أبدًا جلب ملفات عشوائية من ملفات المؤسسة.

• Appium محلي. عند استئجار مهمة جوال يتأكد الوكيل من وجود خادم Appium 2 يمكن بلوغه: يستطلع http://127.0.0.1:4723، ويعيد استعمال خادم تشغِّله أنت إن وُجد، أو يُطلق appium إن كان في PATH (ويوقفه حين تُنهى الحلقة). فإن لم يُبلغ أي خادم ولم يكن appium مثبَّتًا، فشل التشغيل برسالة قابلة للتنفيذ — فالوكيل لا يثبِّت أي شيء خفيةً أبدًا. ثبِّته بنفسك:

  npm i -g appium
  appium driver install uiautomator2   # Android
  appium driver install xcuitest        # iOS (macOS)

• Appium المحلي فقط. تشغيلات الجوال على الوكيل تستهدف Appium محليًّا؛ أما سحابات الأجهزة (BrowserStack / LambdaTest) فمسارها في الخادم، ولا تعمل على وكيل أبدًا.

• تحقَّق أولًا. شغِّل vera-agent doctor لتتأكد من adb والمحاكي وAppium (ومن Xcode والمحاكيات على macOS) قبل إرسال تشغيل جوال.

• خصوصيات iOS. تعمل تشغيلات iOS على محاكيات (بمعرِّف Apple مجاني؛ والجلسة الأولى تبني WebDriverAgent — ببطء، ومرة واحدة). ويحسم الوكيل deviceProfile الخاص بالاختبار إلى محاكٍ، ويُقلعه إن لزم، ويثبِّت الجلسة عليه. iOS يتطلب جهاز Mac الخاص بك أو حسابك في سحابة أجهزة — انظر دليل اختبار iOS الأصلي.

6. حقائق عن دورة الحياة تستحق المعرفة

• الاستئجار والنبضة. يعيش استئجار التشغيل المستلَم 60 ثانية دون نبضة؛ والوكيل ينبض كل نحو 20 ثانية أثناء التنفيذ. فإن تعطَّل وكيلك أو انقطعت شبكته، انتهى الاستئجار خلال دقيقة.

• الإيقاف يعمل، وليس فوريًّا. الضغط على إيقاف في لوحة التحكم (أو POST /api/runs/:id/cancel، أو cancel_run في MCP) لتشغيلٍ ينفِّذه وكيل يُجاب فورًا بـ 202، لكن معنى 202 هو أن الإيقاف سُجِّل، لا أن التشغيل توقَّف. فالخدمة السحابية لا تستطيع أن تدفع شيئًا إلى جهازك — فالوكيل خلف جدارك الناري، ممسكًا بالمتصفح — ولذلك يُدوَّن الطلب ويُسلَّم إلى الوكيل مع نبضته التالية. ثم يُتمّ الوكيل الخطوة التي هو فيها ويتوقف عند حدّها.

  فالحدّ الأعلى الصادق هو مدة نبضة واحدة (20 ثانية فأقل) زائد خطوة واحدة: في أسوأ الأحوال يصل الإيقاف بُعيد نبضة، وتكون الخطوة الجارية wait-for مدتها 30 ثانية. وفي الواقع يكون بضع ثوانٍ. وتُسجَّل الخطوات الباقية skipped مع السبب، ويُغلق المتصفح، وينتهي التشغيل cancelled — حالة نهائية حقيقية، تُحتسب في الاستهلاك كأي تشغيل وتُستثنى من حساب التقلّب، لا فشلًا. أما تشغيلات السحابة والعمّال فتتوقف عند حدّ الخطوة التالية دون انتظار نبضة؛ وهذا الحدّ هو ثمن أن يُنفَّذ التشغيل على جهازك لا على أجهزتنا. وإن كان اختبارٌ يفعل شيئًا لا تحتمل وقوعه مرة أخرى بعد أن تضغط إيقاف، فالخطوة التي عليك النظر فيها هي الجارية لحظتها.

• إعادة الإدخال مرة واحدة، ثم «agent lost». يمسح المجدول الاستئجارات المنتهية: الانتهاء الأول يعيد إدخال المهمة في قائمة الانتظار (فيستطيع وكيل آخر — أو وكيلك بعد إعادة تشغيله — أن يستلم صفّ التشغيل نفسه ويُتمّه)؛ والانتهاء الثاني يستسلم ويُفشِل التشغيل بـ agent lost.

• التشغيل المُعاد إدخاله يستأنف؛ ولا يعيد من البداية. يُبلغ الوكيل بنتيجة كل خطوة لحظة وقوعها، ويسجِّلها الخادم في صفّ التشغيل. فإذا انتهى الاستئجار، حملت المهمة المُعاد إدخالها تلك النتائج إلى الوكيل التالي، فيبدأ من أول خطوة لا نتيجة مسجَّلة لها. فعملية دفع نجحت قبل التعطُّل لا تُرسَل مرة ثانية.

  وقد تتكرَّر خطوة واحدة، والتشغيل يخبرك أيّها. الخطوة التي كانت جارية حين توقَّف الجهاز لا سبيل إلى معرفة مصيرها: فالعملية التي كانت ستُبلغ عنها ذهبت، فلا تستطيع Vera أن تعرف أبلغ طلبُها تطبيقك أم لا. فتُعاد تلك الخطوة، ويُعلَّم مُدخلها في نتائج خطوات التشغيل بأنه ربما تكرَّر — فإن كانت خطوة يلزمك التحقق منها، عرفت بالضبط أيّها تنظر فيه بدل أن تراجع الرحلة كلها. والخطوات التي نفَّذها الجهاز السابق تُعلَّم بأنها منقولة، فيظل التشغيل يعرض الرحلة كاملة وترى أيّ نصفيها نفَّذه هذا الجهاز.

  المحاولة المستأنَفة تبدأ بمتصفح جديد. تُعاد جلسة تسجيل الدخول الملتقَطة لمشروعك، لكن الصفحة وموضع التمرير وأي نموذج مُلئ نصفه في الجلسة الضائعة كلها ذهبت. ولن تبدأ Vera تشغيلًا عند خطوة تحتاجها — انظر الفقرة التالية، وهي الحدّ الذي يفرضه هذا على الميزة كلها.

  ومعظم التشغيلات لا تزال تُعاد من البداية، وهذه الفقرة التي يجب أن تقرأها قبل أن تعتمد على أي مما سبق. لأن الصفحة ذهبت، لا يُستأنف التشغيل المُعاد إدخاله إلا حين تكون الخطوة المقطوعة goto — فالتنقُّل لا يحتاج صفحة سابقة، وكل نوع آخر من الخطوات يحتاجها. فإن مات الوكيل عند نقرة، أو انتظار، أو تحقُّق، أو ملء نموذج، رفضت Vera الاستئناف وأعادت الاختبار كله من الخطوة 1، تمامًا كما كانت تفعل قبل وجود هذه الميزة. ويذكر سجلّ التشغيل أيّ الأمرين وقع ولماذا.

  فالتكرار مسدود للتشغيل الذي ضاع أثناء تنقُّل، وغير مسدود للتشغيل الذي ضاع بُعيد نقرة الدفع — وهي الحالة التي تهمّك غالبًا. وإلى أن يتغيَّر ذلك، تبقى النصيحة القديمة قائمة: إن كان اختبار يفعل شيئًا لا تحتمل وقوعه مرتين، فوجِّهه إلى بيئة يمكن التخلُّص منها، أو أعطِ الخطوة مفتاح عدم تكرار (idempotency key) يُسقط به تطبيقك المكرَّر. ولا تعتمد على أن التشغيل لن يُعاد إدخاله أبدًا.

  وحالتان أخريان تُعادان من البداية لأسباب مختلفة، ويذكرهما السجلّ كذلك: حين لا يمكن مطابقة النتائج المسجَّلة مع الخطوات المكتوبة واحدةً بواحدة (اختبار عُدِّل بين المحاولتين، أو loop أنتج نتائج أكثر من عدد الخطوات)، وحين تتضمَّن الخطوات المكتملة علامة if أو loop — فالبدء بعد فرعٍ اختارته عملية ميتة يشغِّل فرعًا لم يطلبه أحد.

  وإعادة المحاولة شيء آخر، وهي تعيد من البداية. الاختبار المضبوط بـ retries يطلب أن يُعاد تنفيذه من أوله؛ ونقطة الاستئناف لا تنطبق إلا على المحاولة الأولى لتشغيل مُعاد إدخاله.

• الانقطاع / مهلة الانتظار. إن ظلَّ تشغيل في قائمة الانتظار ولم يستلمه أي وكيل خلال 10 دقائق، أفشله المجدول برسالة: "No agent picked up this run within 10 minutes — start vera-agent on your machine." والمهمة المُعاد إدخالها تحصل على نافذة 10 دقائق جديدة من لحظة إعادة الإدخال، لا من لحظة إنشائها أول مرة. (فإن رأيت هذه الرسالة، فوكيلك لا يعمل، أو ليس مسجَّلًا في المؤسسة نفسها / مثبَّتًا على تلك البيئة.)

• الإنهاء لطيف. Ctrl+C يُتمّ التشغيل الجاري قبل الخروج، فلا تترك تشغيلًا نصف منجز عالقًا في running.

7. القيود في هذه المرحلة

• لا تُبلَّغ نتائج الانحدار البصري ولا نتائج إمكانية الوصول من تشغيلات الوكيل. خطوات screenshot لا تزال تلتقط وترفع، لكن لا مقارنة بخط الأساس، وتُسقط نتائج إمكانية الوصول. شغِّل تلك على الهدف السحابي في الوقت الحالي.
• السلاسل العابرة للمشاريع سحابية فقط. لا تُنفَّذ السلاسل على وكيل أبدًا في هذه المرحلة.
• الجوال عبر Appium المحلي فقط. تشغيلات الجوال على الوكيل تقود خادم Appium محليًّا؛ وسحابات الأجهزة مسارها في الخادم.

8. حلّ المشكلات

انظر أيضًا

• الخطوات الأولى — vera-agent init: ربط مستودع بمشروع، والملفات الثلاثة للإعداد، ودورة التحقق ← الاحتفاظ ← الفرز.
• أثر التغيير (vera check) — الروابط الثلاثة وراء check / affected، وما لا تستطيع رؤيته، وعقد --run --local.
• خادم MCP — الأدوات التي يسجِّلها init، والإعداد اليدوي للعملاء من غير Claude Code.
• CI-rider — شغِّل اختبارات Vera المنتظرة على مشغِّلات CI الخاصة بك عبر vera-agent run --drain مع إجراء GitHub مركَّب (اختبار انحدار مجدول لـ iOS والويب، مع حساب الكلفة).
• التكامل مع CI — تشغيلات تقودها الرموز من CI (المسار السحابي).
• اختبار iOS الأصلي — قصة iOS كما هي: محاكيات على Mac (معرِّف Apple مجاني مع WebDriverAgent)، وأجهزة حقيقية، وبدائل سحابة الأجهزة وCI.