Holarch

مرجع

وصفة: نتائج الاختبار عبر Claude

أدخل النتائج من نظام اختبار إلى حالات الاختبار في Holarch، بسكربت REST لـCI أو باستخدام Claude، الذي يشغّل الاختبارات ويقترح النتائج للمراجعة ويُبلغ عما يعرضه RVTM؛ الإعداد، وسكربت، ومثال تطبيقي، واستكشاف الأخطاء وإصلاحها.

طريقة استخدامها ←

في هذه الصفحة
  1. نظرة عامة
  2. المتطلبات المسبقة
  3. طريقة استخدامها
    1. متى ولماذا
    2. سمِّ حالة الاختبار في كل اختبار
    3. تسجيل النتائج من CI
    4. تشغيل الاختبارات واقتراح النتائج بـ Claude
    5. مثال عملي: المشروع التوضيحي CubeSat EO-1
    6. نصائح
  4. استكشاف الأخطاء وإصلاحها
  5. صفحات ذات صلة

نظرة عامة

تسجّل هذه الوصفة النتائج من نظام اختبار آلي على حالات الاختبار المطابقة في Holarch، فتعرض RVTM المتطلبات الناجحة. ولها جزآن:

  • النتائج من CI (REST API): يقرأ برنامج نصي تقرير JUnit XML الذي تكتبه معظم مشغّلات الاختبار ويسجّل كل نتيجة على حالة الاختبار المطابقة: الحالة والنتيجة الفعلية وأجراه وتاريخ الاختبار وإدخالًا في سجل التشغيل.
  • النتائج عبر Claude (MCP): يشغّل Claude Code الاختبارات، ويطابق النتائج مع حالات الاختبار، ويقترح النتائج لتراجعها في Holarch. ثم يقرأ RVTM ويخبرك بالمتطلبات التي لا تزال تفشل.

لاستيراد ملف نتائج يدويًا، استخدم التحقق ← مركز الاختبار ← استيراد النتائج… بدلًا من ذلك (استيراد النتائج من نظام اختبار آخر). ويسجّل REST API وMCP النتائج بالطريقة نفسها: أجراه وتاريخ الاختبار وإدخال في سجل التشغيل على كل حالة اختبار.

المتطلبات المسبقة

  • خطة فيها API وMCP: Individual أو Team، أو الفترة التجريبية لـ Individual. وفي خطة Free، يملكهما أيضًا الحساب الذي له عنوان بريد إلكتروني أكاديمي موثَّق أو الذي في مؤسسة صف دراسي نشطة (الخطط والحدود).
  • مشروع Holarch فيه حالات اختبار تستطيع الاختبارات تسمية أرقامها، مثل TC-14. وتحتاج إلى دور المحرر أو المالك.
  • للبرنامج النصي: رمز القراءة والكتابة مقصور على المشروع (إعدادات الحساب ← رموز API ← رمز جديد، إنشاء رمز)، وPython 3.9 أو أحدث مع حزمة requests (python3 -m pip install requests).
  • لجزء Claude: Claude Code متصل بـ Holarch بوصول القراءة واقتراح التغييرات (ربط Holarch بـ Claude)، في المستودع الذي يحتوي على الاختبارات.
  • مشغّل اختبارات يكتب JUnit XML، مثل pytest --junitxml=results.xml، أو معظم خطوات الاختبار في CI.

طريقة استخدامها

متى ولماذا

يغلق التحقق الحلقة من المتطلب إلى الدليل. وحين تعمل الاختبارات آليًا، تكون كتابة نتائجها في Holarch بطيئة وعرضة للأخطاء. استخدم البرنامج النصي حين ينبغي أن تصل النتائج دون مراجعة، مثل تشغيلات الانحدار الليلية. واستخدم Claude حين ينبغي أن يرى شخص النتائج قبل تسجيلها، مثل تشغيل تأهيل.

سمِّ حالة الاختبار في كل اختبار

يطابق البرنامج النصي وClaude الاختبار مع حالة اختبار في Holarch برقم حالة الاختبار في اسم الاختبار.

  1. ضع الرقم في اسم الاختبار: test_TC_14_off_nadir_imaging في pytest، أو TC-14 off-nadir imaging في المشغّلات الأخرى.
  2. أبقِ حالة اختبار واحدة في Holarch لكل اختبار. وحالة الاختبار التي لها حالات اختبار فرعية تأخذ حالتها من فروعها؛ سجّل النتائج على الفروع.

تسجيل النتائج من CI

يسجّل البرنامج النصي Passed أو Failed على كل حالة اختبار مطابقة، في طلب واحد. وعند الفشل يسجّل أيضًا رسالة الفشل في Actual Result. وتبقى الاختبارات المتخطاة دون تغيير.

# junit_to_holarch.py: record JUnit XML results on Holarch test cases.
# Usage: python3 junit_to_holarch.py results.xml
import os
import re
import sys
import xml.etree.ElementTree as ET

import requests

HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
NUMBER = re.compile(r"TC[-_ ](\d+)")  # TC-14 or test_TC_14_…; change it to match your numbering


def holarch(method, path, **kw):
    r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
    if r.status_code >= 400:
        d = r.json()
        raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
    return r.json()


results = []
for test in ET.parse(sys.argv[1]).getroot().iter("testcase"):
    m = NUMBER.search(test.get("name", ""))
    if not m or test.find("skipped") is not None:
        continue
    failure = test.find("failure")
    if failure is None:
        failure = test.find("error")
    result = {"testCase": "TC-" + m.group(1), "status": "Passed" if failure is None else "Failed"}
    if failure is not None:
        result["actualResult"] = (failure.get("message") or failure.text or "Failed").strip()[:4000]
    results.append(result)

answer = holarch("POST", f"/projects/{PROJECT}/test-results",
                 json={"source": os.path.basename(sys.argv[1]), "testedBy": "CI", "results": results})
for r in answer["recorded"]:
    print(f"{r['number']} {r['name']}: {r['status']}")
for r in answer["skipped"]:
    if r["code"] == "not-found":
        print(f"{r['testCase']}: no test case with this number in Holarch")
    else:
        print(f"{r['testCase']}: not recorded ({r['reason']})")
  1. اضبط متغيري البيئة HOLARCH_TOKEN (الرمز) وHOLARCH_PROJECT (معرّف المشروع من GET /api/v1/projects).
  2. شغّل اختباراتك مع تقرير JUnit، مثل pytest --junitxml=results.xml.
  3. شغّل python3 junit_to_holarch.py results.xml.

    ترى سطرًا واحدًا لكل نتيجة مسجلة، مثل TC-14 Off-Nadir Imaging Test: Passed.

  4. في Holarch، افتح التحقق ← RVTM.

    تعرض المتطلبات التي تتحقق منها حالات الاختبار تلك الحالة الجديدة.

كيف يعمل:

  • يسجّل POST /api/v1/projects/<project>/test-results كل نتائج التقرير تغييرًا واحدًا، كما يفعل استيراد النتائج…: الحالة، والنتيجة الفعلية لحالات الفشل، وأجراه (CI هنا؛ واسم حسابك حين يُستبعد)، وتاريخ الاختبار (وقت الطلب) وإدخال في سجل التشغيل مع ضبط source على اسم ملف التقرير (نتائج الاختبار).
  • يسمي testCase حالة الاختبار برقمها، مثل TC-14؛ ويعمل المعرّف أو الاسم أيضًا. وتأخذ الحالة هنا Passed أو Failed؛ وتأخذ نقطة النهاية أيضًا Blocked وIn Progress وNot Run، وكلمات أدوات الاختبار مثل pass وfail.
  • النتيجة التي لا يمكن تسجيلها، مثل رقم ليس في Holarch، تُسرد في skipped مع سببها؛ ولا تزال الأخرى تُسجَّل.
  • يُسجَّل التغيير باسمك ويراه فورًا كل من يفتح المشروع.

في مهمة CI، شغّل البرنامج النصي خطوةً بعد الاختبارات، مع الرمز سرًّا. في GitHub Actions، مثلًا:

      - name: Record results in Holarch
        if: always()
        env:
          HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
          HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
        run: |
          python3 -m pip install requests
          python3 junit_to_holarch.py results.xml

يسجّل if: always() النتائج حتى حين تفشل الاختبارات، وهو الوقت الذي تكون فيه أهم.

تشغيل الاختبارات واقتراح النتائج بـ Claude

  1. في المستودع الذي يحتوي على الاختبارات، اسأل Claude Code، مثلًا: “Run the pointing tests with a JUnit report. Then propose their results in the Holarch CubeSat project: set Status and, for failures, Actual Result on the matching test cases.”
  2. يشغّل Claude Code الاختبارات. وفي Holarch يضيف النتائج إلى مقترح بـ record_test_results (تغيير واحد لكل نتيجة، مع الحالة والنتيجة الفعلية وأجراه وتاريخ الاختبار). ثم يرسل المقترح بـ propose_changes.

    يجيب Claude Code بعنوان المقترح، والنتائج التي يقترحها، ورابط لمراجعته.

  3. في Holarch، افتح ✦ الذكاء الاصطناعي ▾ ← مراجعة “<title>”…، أو الإشعار تحت الجرس.

    يعرض مربع الحوار كل حالة اختبار مع قيمها الحالية والمقترحة.

  4. ألغِ تحديد أي نتيجة لا تقبلها، ثم انقر تطبيق المحدد.

    تُسجَّل النتائج باسمك في السجل، ولكل منها إدخال في سجل التشغيل كما من استيراد النتائج…، ويُلغي تراجع واحد ذلك كله.

  5. اسأل Claude Code: “Which requirements in the CubeSat project still fail verification?”

    يقرأ Claude Code RVTM بـ get_matrix (matrix rvtm، status Failed) ويسرد كل متطلب مع حالات الاختبار الفاشلة الخاصة به.

يستطيع Claude Code أيضًا العمل من تقرير كتبه CI لديك أصلًا: أرفق results.xml أو وجّهه إليه بدلًا من أن تطلب منه تشغيل الاختبارات.

مثال عملي: المشروع التوضيحي CubeSat EO-1

  1. أنشئ المشروع التوضيحي بـ إدارة المشاريع ← ملفات المشروع ▾ ← مشروع توضيحي جديد.

    في التحقق ← مركز الاختبار، TC-14 Off-Nadir Imaging Test بحالة Not Run وTC-04 Pointing Accuracy Test بحالة Failed.

  2. اكتب تقرير JUnit باختبارين: test_TC_14_off_nadir_imaging نجح، وtest_TC_04_pointing_accuracy فشل بالرسالة 0.12 degrees on 2 of 20 targets.
  3. شغّل python3 junit_to_holarch.py results.xml.

    ترى TC-14 Off-Nadir Imaging Test: Passed وTC-04 Pointing Accuracy Test: Failed.

  4. افتح التحقق ← RVTM.

    يعرض 1.6.2 Off-Nadir Imaging الآن Passed. ولا يزال 2.1 Pointing Accuracy يفشل، وتقول النتيجة الفعلية لـ TC-04 0.12 degrees on 2 of 20 targets.

  5. مع Claude، تصل النتائج نفسها مقترحًا أولًا. وبعد تطبيق المحدد، تعرض RVTM الشيء نفسه.

نصائح

  • سجّل النتائج على أدنى حالات الاختبار. وتُجمَّع الأصول من فروعها.
  • أبقِ رمز البرنامج النصي مقصورًا على المشروع الواحد، وألغِه حين يُتقاعد خط المعالجة.
  • الاختبار الذي يسمي رقمًا ليس في Holarch يُسرد بـ “no test case with this number” (لا حالة اختبار بهذا الرقم). أصلح اسم الاختبار أو أنشئ حالة الاختبار.
  • احفظ دورة اختبار في مركز الاختبار حين تنتهي حملة، لتبقى نتائجها منفصلة عن التشغيل التالي (حفظ دورة اختبار).

استكشاف الأخطاء وإصلاحها

الرسالة أو العَرَضالسبب والإصلاح
Holarch answered 401 token-invalidالرمز خاطئ أو ملغى أو منتهي الصلاحية. أنشئ رمزًا جديدًا تحت إعدادات الحساب ← رموز API.
Holarch answered 403 plan-apiخطة الحساب لا تتضمن API وMCP. ابدأ الفترة التجريبية لـ Individual أو اختر خطة؛ ثم يعمل الرمز مرة أخرى.
Holarch answered 403 read-only-tokenيكتب البرنامج النصي النتائج. أنشئ رمز القراءة والكتابة.
Holarch answered 403 forbiddenدورك في المشروع مشاهد أو مراجع. يستطيع مالك أن يجعلك محررًا.
TC-14: not recorded (…)تعذّر على Holarch تسجيل تلك النتيجة، مثلًا لأن حالة الاختبار مقفلة أو لها حالات اختبار فرعية. ويقول السبب أيهما؛ وتُسجَّل النتائج الأخرى.
TC-04: not recorded (… configuration control …)حالة الاختبار خاضعة للتحكم في التكوين. سجّل نتيجتها في التطبيق عبر طلب تغيير.
Holarch answered 429 rate-limitedطلبات كثيرة جدًا في الدقيقة. انتظر الثواني المذكورة في Retry-After، ثم شغّل البرنامج النصي مرة أخرى.
تحتفظ حالة اختبار بحالتها القديمةتعرض حالة الاختبار التي لها فروع الحالة المجمَّعة من فروعها. سجّل النتيجة على فرع.
لا يعرض Claude Code أدوات الكتابة في Holarchالاتصال للقراءة فقط. شغّل /mcp، وأعد ربط holarch بـ القراءة واقتراح التغييرات، ثم ابدأ محادثة جديدة.