الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
lousho/testing يوفّر mockModel: ‏LLMProvider يعمل بسكربت deterministic للـ unit tests. تكتب ما يُفترض أن يقوله الـ model في كل turn، وتشغّل الـ agent، ثم تتحقق بالضبط مما أرسله الـ agent إلى الـ model. بلا network، بلا API keys، بلا flakiness.

رد نصي

إذا كتبت string فقط، فهو اختصار لـ { text }.

flow مع tool call

كل عنصر في السكربت هو turn واحد للـ model. الـ turn الأول يطلب tool. الـ agent ينفّذه ويستدعي الـ model مرة أخرى. الـ turn الثاني يعطي الجواب النهائي. معرّفات الـ tool calls تتولّد بشكل deterministic ‏(call_1، call_2، …) إلا إذا مرّرت id.

turn فيه خطأ

‏{ error } تجعل استدعاء الـ model يفشل بـ reject. أي أنك تستطيع اختبار كيف يتصرف الـ agent عندما يتعطّل الـ provider.

التحقق من الـ requests

‏model.calls يحتفظ بـ snapshot مجمّدة (deep-frozen) لكل request، بالترتيب. أي تعديل لاحق من الـ agent لا يستطيع إعادة كتابة ما سُجّل. استخدم model.lastCall لآخر request.

turns ديناميكية

مرّر function تحسب الـ turn من الـ request. يمكن أن تكون async، وتعيد string أو أي turn object.

مرجع الـ turn

عندما تنفد الـ turns

إذا استدعى الـ agent الـ model أكثر مما كتبت في السكربت، يرمي mockModel خطأً يذكر رقم الاستدعاء غير المتوقع، ويعرض آخر message في الـ request، ويطلب منك إضافة turn. لكي تعيد آخر turn إلى ما لا نهاية (مفيد في اختبارات الـ loop وحدود الخطوات)، مرّر { onExhausted: 'repeat-last' }:
وهناك helpers أخرى: model.reset() تعيد السكربت إلى البداية وتمسح الـ calls المسجّلة، وmodel.assertExhausted() ترمي خطأً إذا بقيت في السكربت turns لم تُستخدم.

Streaming

‏mockModel ينفّذ stream() أيضًا: يُبث نص السكربت على شكل text-delta chunks (مقسّمة على حدود الكلمات)، تتبعها أي tool-call chunks ثم finish chunk أخير. أي أنك تستطيع اختبار مستهلكي الـ streaming أيضًا.

Record و replay

‏mockModel تكتب الـ turns يدويًا. recordReplay هي الأداة المكمّلة: VCR لسلوك الـ model الحقيقي. شغّل اختبارك مرة واحدة مع الـ provider الحقيقي، وكل تبادل generate() / stream() يُكتب في ملف cassette. في الـ CI يُجري الاختبار نفسه replay للـ cassette بلا network، بلا API key، وبلا تثبيت الـ peer package الخاصة بالـ provider. بادئة vendor/ في اسم الـ model تحدد الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثال openrouter/openai/gpt-4o-mini).
الوسيط الأول هو الـ provider الحقيقي، أو factory بالشكل () => provider لا تُستدعى إلا وقت التسجيل (أي أن الـ replay لا ينشئها أبدًا). ويمكن أن تكون undefined إذا كنت تُجري replay فقط.

خطوات العمل

  1. سجّل محليًا بمفتاح: LOUSHO_RECORD=1 OPENAI_API_KEY=... npx vitest run.
  2. راجع الـ cassette وأجرِ له commit (ملف JSON ثابت بإزاحة مسافتين، فالـ diffs مقروءة).
  3. الـ CI يشغّل npx vitest run ويُجري replay. لا يحتاج إلى أي شيء آخر.
  4. عندما تغيّر الـ prompt أو الـ tools أو الـ flow، يفشل الـ replay بـ CassetteMismatchError؛ أعد التسجيل بـ LOUSHO_RECORD=1.
‏mode: 'auto' يُجري replay إذا كان ملف الـ cassette موجودًا، ويسجّل في الحالة الأخرى. في evals المعرّفة بـ defineEval() لا تحتاج إلى تغليف الـ provider بنفسك: lousho eval --record يكتب cassette لكل eval case، و--replay يشغّل منها، و--drift يبيّن كيف تغيّر مسار كل case. انظر التسجيل وإعادة التشغيل والـ drift.

ماذا يفحص الـ replay

افتراضيًا يُجاب على الـ call رقم N بالـ entry رقم N، لكن بشرط أن يكون الـ request مطابقًا لما سُجّل: الـ model، ودور كل message ومحتواها والـ tool calls فيها، وأسماء الـ tools والـ parameter schemas الخاصة بها، وtemperature وmaxTokens. تُقارَن الـ tools بالاسم، فتسجيل الـ tools نفسها بترتيب آخر يظل مطابقًا (وهذا ينطبق أيضًا على الـ cassettes الأقدم التي كانت تحفظ ترتيب التسجيل). عند عدم التطابق يعرض الخطأ أول اختلاف مع تلميح لإعادة التسجيل:
هذا التلميح يفترض أنك ربطت mode بـ LOUSHO_RECORD كما في الأعلى. إذا كنت تسجّل بطريقة أخرى، مرّر rerecordHint مع الأمر الذي يستخدمه مشروعك؛ وتحت lousho eval يذكر التلميح npx lousho eval --record بدلًا من ذلك. للـ calls المتوازية أو غير المرتّبة مرّر match: 'request': كل call يجد أول entry غير مستخدمة بطلب مطابق تمامًا، بأي ترتيب. ونفاد الـ entries هو أيضًا CassetteMismatchError. القيم المتقلّبة لا تكسر المطابقة. الـ timestamps والتواريخ (2026-10-01 وOctober 1, 2026) والـ UUIDs والمعرّفات ذات البادئات (call_... وtoolu_... وchatcmpl_...) تُستبدل بـ placeholders على الطرفين، ومعرّفات الـ tool calls تُتجاهل (تتطابق الـ tool calls بالاسم والـ arguments). الـ parameter schema الخاصة بالـ tool تتطابق بما كتبته فيها (أسماء الخصائص والأنواع وoptional وقيم الـ enum والفحوص مثل min أو int والأوصاف)، لا بطريقة طباعة major version معيّن من zod. فالـ cassette المسجّلة بـ zod 3 تعمل في الـ replay مع zod 4 والعكس؛ وتغيير الـ schema نفسها يُفشل المطابقة. لأي شيء آخر، مرّر normalize:

الأخطاء والـ streaming والـ usage

  • رفض الـ provider يُسجَّل ويُعاد كرفض بالـ name والـ message نفسيهما.
  • stream() يسجّل الـ chunks ويعيدها كـ async iterable بلا تأخيرات؛ مرّر replayTiming: true لكي تسترجع التوقيت بين الـ chunks. وأثناء التسجيل يُقرأ الـ stream الحقيقي حتى نهايته قبل أن يُعاد.
  • استهلاك الـ tokens يُسجَّل ويُعاد بالكامل (بما في ذلك الـ cached-input tokens والـ reasoning tokens، والتكلفة التي يبلّغ عنها الـ provider)، فتتصرف ميزات التكلفة والـ usage بالطريقة نفسها في الـ replay.
  • الـ reasoning blocks الخاصة باستدعاء generate() ‏(result.reasoning، مع الـ signatures الخاصة بها) تُسجَّل وتُعاد؛ والـ stream يحتفظ بالـ reasoning داخل الـ chunks المسجّلة. والـ cassettes المسجّلة قبل أن نبدأ بالاحتفاظ بهذه البيانات تعمل في الـ replay كالمعتاد، لكن دونها.

متى تُكتب الـ cassette

يكتب التسجيل الـ cassette بشكل atomic (ملف مؤقت ثم rename) بعد كل call. أي أن الاختبار الذي يفشل في منتصف الطريق يترك cassette صالحة فيها كل الـ calls التي حدثت، لا cassette مكتوبة نصفها. await provider.save() يفرض الكتابة. لا يوجد hook عند خروج الـ process. وكل session تسجيل تبدأ cassette جديدة وتستبدل الملف القديم. وإذا كان التسجيل الجديد يحتوي التبادلات نفسها بالضبط الموجودة في الملف القديم، تُحفظ قيم recordedAt وsdkVersion القديمة، فإعادة التسجيل دون تغيير تترك الملف كما هو byte بـ byte ولا يظهر أي diff.

تنقيح البيانات (اقرأ هذا قبل الـ commit)

يُفترض أن تدخل الـ cassettes إلى الـ repo، لذا يكتب الـ wrapper مجموعة ثابتة فقط من حقول الـ request (لا headers ولا option bags الخاصة بالـ provider أبدًا)، ولا يكتب rawResponse أبدًا، ويستبدل بالـ strings التي تشبه API keys ‏(sk-... وsk-ant-... ورموز Bearer ... وصيغ شائعة أخرى) القيمة [REDACTED]. هذا safety net، وليس ضمانة: الـ prompts وردود الـ model تُخزَّن حرفيًا، أي أن البيانات الشخصية والـ URLs الداخلية ونصوص العملاء ينتهي بها المطاف في الملف. مرّر redact لكي تنقّيها (تعمل على كل string مسجّلة، في الـ requests والـ responses معًا، ويطبّقها الـ replay عند المطابقة):

mockModel أم cassettes؟

استخدم mockModel للـ unit tests على منطقك أنت: تتحكم بكل turn، وتستطيع حقن أخطاء وتأخيرات، ولا شيء يعتمد على model. استخدم الـ cassettes عندما يكون المقصود هو سلوك الـ model الحقيقي (هل يصل الـ prompt وهذه الـ tools فعلًا إلى الـ tool call الصحيح؟) وعندما تكون كتابة الـ turns يدويًا مجرد تثبيت لافتراضاتك في الاختبار. الـ cassettes تحتاج إلى إعادة تسجيل عندما تتغيّر الـ prompts؛ واختبارات mockModel لا تتغيّر إلا إذا تغيّر السلوك الذي تتحقق منه.