الخطوات الأولى

اربط مستودعك بـ Vera بأمر واحد — npx vera-agent init --url <your Vera host> --token <your token> — فيعرف محرِّرك ووكيلك البرمجي وخط التكامل المستمر (CI) جميعًا إلى أي مشروع في Vera ينتمي هذا المستودع. وتكرار الأمر لا يغيِّر شيئًا، ولا يكتب شيئًا قبل أن يعرضه عليك.

وهذا ما تشرحه هذه الصفحة. أما «البداية» الأخرى فليست موضوعها:

• تشغيل Vera نفسها — أن تستضيف الخدمة على بنيتك، أو تساهم في تطويرها. ابدأ من دليل الاستضافة الذاتية؛ ومَن لديه نسخة من المستودع يجد في ملف README بداية سريعة عبر pnpm setup وpnpm dev.
• ربط مستودع تعمل عليه بنسخة Vera قائمة بالفعل — وهو ما تتناوله هذه الصفحة من هنا فصاعدًا.

دقيقة واحدة حتى يصبح المستودع مربوطًا

npx vera-agent init --url https://your-vera-host --token vera_your_token

اكتب vera-agent لا vera. فالحزمة المنشورة تُثبِّت الاسمين معًا، غير أن npx vera يجلب حزمة أخرى لا صلة لها بـ Vera، حجز أحدهم هذا الاسم لها عام 2022. فالاسم المختصر لا يكون آمنًا إلا بعد تثبيت vera-agent، ولا يصحّ استخدامه في أمر npx مباشر.

تكرار init غير ضارّ: يخبرك بما تغيَّر، وإن أعدته ولم يتغير شيء قال لك ذلك بدل أن يمسّ ملفًا متتبَّعًا في Git.

ما الذي يفعله تشغيل واحد:

1. يستدلّ على المشروع. يقرأ جذر المستودع وعنوان origin، ثم يبحث عن مشروع يملك رمزك صلاحية رؤيته: الأولوية لمشروع مربوط بـ GitHub، ثم للتطابق في الاسم (my-app == My App). فإن وجد مشروعين بالاسم نفسه عدَّ الأمر ملتبسًا وطلب منك --project <id> بدل أن يخمِّن — لأن ربط مستودع بمشروع خاطئ يُفسد بصمت كل تشغيل وكل حساب تغطية يأتي بعده. وإن لم يجد شيئًا، طبع لك رابط لوحة التحكم لتُنشئ مشروعًا بنفسك؛ فالرمز لا يملك صلاحية إنشاء المشاريع، وهذا مقصود.
2. يكتب .vera/config.json — ويحوي {apiUrl, projectId, repoPathPrefix}. احفظه في المستودع (commit). فليس فيه ما هو سرّي.
3. يحفظ رمز الوصول في ~/.vera/cli.json — بصلاحيات chmod 600، مرتَّبًا حسب apiUrl، حتى يحمل الجهاز الواحد بيانات اعتماد لأكثر من نسخة، فلا يحتاج مستودع ثانٍ على المضيف نفسه إلا إلى --url.
4. يُسجِّل خادم MCP باسم vera عند جذر المستودع (عبر claude mcp add في النطاق المحلي، وهو نطاق مرتبط بالمجلد الذي تبدأ منه جلسة Claude Code)، فتجد أي جلسة تُفتح داخل هذا المستودع الأدوات جاهزة. ولك تخطّي ذلك بـ --no-mcp؛ وانظر إعداد MCP للنطاق الآخر وللعملاء من غير Claude Code. وإن كان خادم vera مُسجَّلًا في أي نطاق، تركه init على حاله وأخبرك بذلك.
5. يكتب تعليمات الوكيل في ملف التعليمات الذي يعتمده المستودع أصلًا (AGENTS.md، وإلا CLAUDE.md)، محصورةً بين <!-- vera:sdlc:begin --> و <!-- vera:sdlc:end -->. ولا يُعاد كتابة شيء خارج هاتين العلامتين، فما كتبتَه قبلهما وبعدهما يبقى كما هو. ويتخطّى هذه الخطوة --no-agents-md.

الخيارات

وإن أغفلت --url أو --token في الطرفية سألك عنهما. أما في السكربتات فلا بدّ منهما، إلا أن يكون الرمز محفوظًا من قبل لذلك العنوان.

ثلاثة ملفات، وأيها يحمل سرًّا

هنا يقع أكثر اللبس.

والسطر الأخير هو ما يلتبس على الناس: init وlogin يكتبان ملفين مختلفين، يحملان رمزين مختلفين، لغرضين مختلفين. فرمز init هو CI Token (vera_…) للواجهة البرمجية ولـ MCP؛ ورمز login هو رمز تسجيل جهاز (vera_agent_…) يخوِّل هذا الجهاز أن يستلم العمل وينفِّذه. والأوامر start وrun وwatch وverify كلها تقرأ ملف التسجيل، فإن اكتفيت بـ init أخبرك verify بفشل الاتصال — وعليك عندئذٍ تشغيل login أيضًا.

ومع --mcp-scope project، لا يحمل ملف .mcp.json المحفوظ في المستودع إلا النص ${VERA_TOKEN} حرفيًّا، ويُصدِّر كل مطوِّر رمزه في بيئته (export VERA_TOKEN=vera_…). فلا يدخل المستودعَ سرٌّ في الحالتين.

قبل ذلك كله: أنشئ رمز وصول

Settings ← CI Tokens ← سمِّه ← Create. ولك أن تضبط له تاريخ انتهاء، وأن تختار org-wide إن أردت رمزًا مشتركًا لا يرتبط بشخص فيظل صالحًا بعد مغادرة مُنشئه (ويحتاج ذلك صلاحية على مستوى المؤسسة). أما الافتراضي فرمز شخصي، وهو الأنسب لجهازك، إذ تُسجَّل عندها العمليات والاستخدام باسم شخص بعينه لا باسم جهة مجهولة.

ويُعرض الرمز vera_… بنصِّه مرة واحدة فقط. وإبطاله يسري فور طلبه.

ملاحظة عن الخطة، لأن العطل بدونها يبدو غامضًا. يقرأ init المسار GET /api/v1/projects، وفي النسخة السحابية يتطلب /api/v1 ميزة api-access المتاحة في خطة Pro. أما مساحة العمل السحابية المجانية فتحصل على mcp-basic، وهي تغطي /api/mcp وحده — فتعمل أدوات MCP بينما يرفض init قائلًا:

Vera token not accepted. It may be revoked, expired, or this workspace may no longer include API access. Check Settings → API tokens, and the workspace plan.

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

الدورة اليومية

ينتهي init بطباعة هذه الدورة، لأنها الغاية من تثبيت أي شيء من هذا كله:

1. غيِّر شيئًا في الواجهة.
2. تحقَّق منه في متصفح حقيقي وبدور مستخدم حقيقي. لا يكفي أن «الشيفرة تُترجَم بنجاح» — بل تشغيل فعلي، بحساب مستخدم مسجَّل الدخول، يخبرك بما رآه. من Claude Code عبر الإضافة: /vera:verify. وعبر MCP: run_scenario (بلا حفظ) أو run_test، ثم wait_for_run.
3. احتفظ بالفحص إن كان يستحق الاحتفاظ. أي سيناريو رأيته ينجح تَوًّا يمكن ترقيته إلى اختبار دائم باستدعاء واحد (save_scenario_as_test)، وهذا خير من كتابة اختبار دون أن تراه يعمل. وتُرجع Vera تنبيهات في warnings حين لا تُثبت الخطوات شيئًا، فلا تتجاوزها.
4. إذا جاءت النتيجة حمراء، شخِّص قبل أن تُصلح. اسأل أولًا: أالخطأ في الاختبار أم في التطبيق؟ استعن بـ /vera:fix، أو get_failure_details ثم suggest_fix. فإصلاحٌ يجعل اختبارًا فاشلًا يوافق عِلّة قائمة يحوِّل خللًا ظاهرًا إلى خلل صامت، ولذلك لا يُطبَّق شيء دون موافقتك.

وقبل أن تدفع تغييراتك، يربط npx vera-agent check تغييرك بالاختبارات التي تغطّيه، ويستطيع تشغيل تلك المجموعة وحدها (--run). واقرأ أثر التغيير قبل أن تطمئنّ إلى النتيجة، فالربط قائم على مؤشرات لا على يقين، والملف الذي لم يُربط بشيء ليس ملفًا آمنًا.

التحقق مقابل localhost

لا تصل نسخة Vera السحابية إلى http://localhost:3000. وأمامك طريقان لسدّ هذه الفجوة، وكلاهما يقتضي تسجيل جهاز (Settings ← Agents ← create ← انسخ الرمز vera_agent_…):

npx vera-agent login --url https://your-vera-host --token vera_agent_...

# run an ad-hoc check here, now, in this process — seconds, no queue
echo '[{"action":"goto","url":"/orders"},
       {"action":"assert","selector":"#total","assertType":"text","value":"42 orders"}]' \
  | npx vera-agent verify --project prj_123 --steps - --role admin

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

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

أما الإعداد الدائم — بيئة تُنفَّذ تشغيلاتها دائمًا على جهازك — فانظر دليل الوكيل المحلي.

إدخال اختباراتك الموجودة (دون إنفاق رصيد ذكاء اصطناعي)

إن كان في المستودع اختبارات E2E من قبل، فحوِّلها بدل أن تبدأ من مشروع فارغ. سبع صيغ تُحوَّل تحويلًا قاطعًا لا ينفق شيئًا من رصيد الذكاء الاصطناعي: postman, cypress, playwright, wdio, testcafe, har, openapi. أما الثامنة، selenium، فتشمل سيلينيوم بجافا وبايثون ولا محوِّل قاطع لها — ولا تُستورد إلا بتحويل بالذكاء الاصطناعي تختاره أنت، وهو ينفق من الرصيد. انظر الاستيراد والتصدير.

curl -s -X POST https://your-vera-host/api/v1/projects/prj_123/import/cypress \
  -H "Authorization: Bearer vera_your_token" \
  -H 'content-type: application/json' \
  -d '{"files":[{"path":"cypress/e2e/login.cy.ts","content":"…file text…"}]}'

ولهذه الحدود جميعًا حكم واحد: تُرفض الدفعة كلها ولا يُستورد بعضها — 50 ملفًا في الطلب الواحد، و5,000,000 حرف للملف، و16 ميبي بايت لجسم الطلب. ويُعيد الردّ 201 الاختبارات المنشأة، وcounts لكل صيغة، والملفات التي skipped مع سبب تخطّيها، وwarnings، وعدد unresolved.

وتنبَّه لما تستشهد به من ذلك الردّ. التحويل قاطع ولا يكلّف رصيدًا، ولهذا تحديدًا هو جزئي: التنقُّل والتفاعل يُترجمان بلا عناء، أما التحقُّق الذي يعجز المحوِّل عن التعبير عنه فيُبلَّغ عنه ولا يُحوَّل — يظهر في warnings ويُحصى في unresolved ويبقى خارج الاختبار. فمواصفة Cypress كان تحقُّقها الوحيد cy.contains('Welcome back') تُستورد على هيئة goto, fill, fill, click: اختبار يُعاد تشغيله فينجح ولا يُثبت شيئًا. فاقرأ unresolved قبل أن تثق بعدد الاختبارات، وأضِف ما نقص من تحقُّقات بيدك، أو بإعادة الاستيراد مع {"aiFallback": true} — وهي تنفق من رصيد الذكاء الاصطناعي على مفتاحك أنت.

أو اترك init يفعلها

يفحص init المستودع بحثًا عن اختبارات قابلة للتحويل، ثم يعرض عليك ما وجد:

npx vera-agent init --import all          # convert everything it finds
npx vera-agent init --import cypress,har  # or name the formats
npx vera-agent init --no-import           # skip the scan entirely

فإن لم تذكر --import، عرض init في الطرفية ما وجده وسألك. أما إذا لم يكن الإدخال طرفيةً — في CI مثلًا، أو في سكربت تهيئة — فلا يستورد شيئًا ويخبرك بذلك ويذكر لك الخيار الذي يُفعِّله؛ لأن الاستيراد يكتب اختبارات في مساحة عمل شخص ما، وسكربتٌ شغَّل vera-agent init لم يوافق على ذلك. ويحترم الفحص ملف .gitignore، ولا يُرسَل aiFallback من هذا الطريق أبدًا، فأول نتيجة ناجحة لا تكلّفك رصيدًا.

وهذا أيضًا هو الأمر الذي يقترحه vera check حين لا تكون لديه بعدُ خريطة للأثر: فالاختبارات المستوردة تحمل روابط goto الخاصة بها، وهي عين ما يعتمد عليه الربط بالمسارات.

إلى أين بعد ذلك

• إضافة Vera لـ Claude Code — المهارة وأوامر /vera:*، حتى لا تُعيد شرح الإجراء في كل جلسة.
• خادم MCP — الأدوات كلها، ونموذج المصادقة، وقاعدة «لا تطبيق دون تأكيد».
• الوكيل المحلي — أوامر vera-agent كاملةً، وأهداف تشغيل البيئات، وتطبيقات الهاتف الأصلية، ومعالجة المشكلات.
• أثر التغيير (vera check) — أي الاختبارات يمسّها تغييرك، وطرق الربط الثلاث وحدودها، والخيار --run والخيار الاختياري --strict.
• التكامل المستمر — إطلاق التشغيلات من CI بالرمز vera_… نفسه؛ وCI-rider لتشغيلها على مُنفِّذاتك أنت.