هرم الاختبارات في NextPDF

Spec: ISO/IEC/IEEE 29119-4 Spec: ISO/IEC 25010 Evidence: Test-backed PHPStan: Level 10

لمحة سريعة

لا يعتمد ⁨NextPDF⁩ على نوع واحد من الاختبارات. لديه خمس طبقات، وتجيب كل طبقة منها عن سؤال مختلف حول المحرك. والسبب أن ملف ⁨PDF⁩ قد يجتاز اختبار الوحدة، ومع ذلك يبقى ملفًا معطوبًا بنيويًا على القرص. تُسمّي هذه الصفحة الطبقات الخمس وتوضح ما تثبته كل واحدة منها.

لماذا يهم هذا

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

أدبيات المعايير واضحة في هذا الشأن. فتقنيات تصميم الاختبار المستندة إلى المواصفة والمستندة إلى البنية لا ترتبط ببعضها، ويُنصح بأن تستخدم استراتيجية الاختبار أكثر من معيار واحد، بحيث يكون أحدها على الأقل وظيفيًا وآخر بنيويًا (⁨ISO/IEC/IEEE 29119-4⁩، الملحق ⁨A⁩). الطبقة الواحدة ليست نسخة مصغّرة من استراتيجية جيدة؛ بل هي استراتيجية مختلفة وغير مكتملة.

النسخة المختصرة

يُنظّم ⁨NextPDF⁩ اختباراته في خمس طبقات، من القاعدة إلى القمة:

الوحدة — صنف واحد أو دالّة واحدة، بمعزل عن غيرها. القاعدة العريضة.
التكامل — وحدات تتعاون عبر حدّ وحدة برمجية.
البنيوي — أن يكون مخطط كائنات ⁨PDF⁩ المُصدَر وجدول الإحالات المرجعية والذيل (⁨trailer⁩) سليمة التكوين ومتوافقة.
البصري — أن تطابق الصفحة المعروضة مرجعًا معتمدًا ضمن هامش تسامح محدد.
الذهبي — تجهيزات اختبار شاملة (⁨end-to-end⁩) مثبَّتة تلتقط أي انحراف غير مقصود في الخرج النهائي. القمة.

تُثبت كل طبقة شيئًا لا تستطيع الطبقات التي دونها إثباته. ولا توجد طبقة منها للزينة. يرتبط شكل الهرم بـالكمية — اختبارات وحدة كثيرة ومنخفضة التكلفة، واختبارات شاملة (⁨end-to-end⁩) أقل عددًا وأعلى تكلفة — لا بالأهمية.

كيف يتعامل ⁨NextPDF⁩ مع ذلك

الطبقات موجودة فعليًا، وليست مجرد طموحات. يعلن تكوين ⁨PHPUnit⁩ في المستودع كل طبقة منها بوصفها مجموعة اختبار مسمّاة مرتبطة مباشرة بدليل. لذلك فالطبقة وجهة يمكنك توجيه مُشغِّل الاختبارات إليها، وليست مجرد تسمية في شريحة عرض. من المجموعات التي سيتعرّف عليها المهندس الخبير Unit، وIntegration، وGolden، وSnapshot، وReproducibility، وConformance، وStandards، وPerformance، ولكل منها مِلف تنفيذ خاص بها (العزل، ونطاق الزمن، وما إذا كانت تُشغَّل افتراضيًا في التكامل المستمر).

هذا الفصل مقصود. تُشغَّل طبقة القاعدة السريعة (Unit) عند كل تغيير بميزانية ثانية واحدة لكل اختبار. أما الطبقات الأبطأ والحساسة للبيئة — العرض البصري، والتوافق الكامل، والأداء — فهي اختيارية أو ليلية. يُبقي ذلك المسار الشائع سريعًا وحتميًا دون التخلي عن الفحوص الأعمق. يقوم النظام بأكمله على الكتابة الصارمة للأنواع. يُجري المحرك التحليل عند Spec: PHPStan, Level 10 مع تثبيت ميزانية الأخطاء عند الصفر، فلا يصل صنف واسع من العيوب إلى أي اختبار أصلًا.

Tier 1 of 5 Unit Isolated behaviour of a single class or function; the broad base.
Tier 2 of 5 Integration Collaborating units across a module boundary.
Tier 3 of 5 Structural The emitted PDF object/xref structure is well-formed and conformant.
Tier 4 of 5 Visual Rendered output matches an approved reference within tolerance.
Tier 5 of 5 Golden End-to-end byte/lossless fixtures pinned as the contract; the apex.

طبقات الاختبار الخمس في NextPDF، من القاعدة إلى القمة. الوحدة هي القاعدة العريضة السريعة؛ وكل طبقة فوقها تُثبت خاصية يعجز عنها ما دونها، وصولًا إلى التجهيزات الذهبية الشاملة (end-to-end) عند القمة. العرض مجرد إشارة إلى الكمية — وهو لا يرتّب الأهمية.

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

ماذا تقول الأدلة

Evidence: Test-backed توجد المجموعات الخمس بوصفها مجموعات اختبار ⁨PHPUnit⁩ مُعلَنة في تكوين المحرك، وترتبط كل واحدة منها بدليلها وملف تنفيذها الخاص. مصطلحات الطبقات في هذه الصفحة هي المصطلحات نفسها التي تستخدمها بنية الاختبار التحتية.

Evidence: Standard-backed السبب في وجود أكثر من طبقة واحدة راسخ في Spec: ISO/IEC/IEEE 29119-4, Annex A : معايير التغطية لا ترتبط جميعها ببعضها، ويُنصح بأن تجمع الاستراتيجية بين التقنيات الوظيفية والبنيوية. والأهم أن الملحق نفسه يشير إلى أن ترتيب الاحتواء بين معايير التغطية لا يعطي أي مؤشر على قدرتها على كشف العيوب — فاعلية الاختبار (⁨ISO/IEC/IEEE 29119-4⁩، §⁨C.2.4⁩). “تغطية أكثر” لا تعني الادعاء نفسه الذي تعنيه “اختبارات أفضل”.

Evidence: Standard-backed إن اختيار أيّ الخصائص يجب إثباتها يقابل خصائص جودة المنتج في Spec: ISO/IEC 25010 وهي: الصحة الوظيفية (الوحدة، التكامل)، والخصائص على مستوى الملف التي تجعل ⁨PDF⁩ قابلًا للاستخدام فعلًا في المراحل اللاحقة (البنيوي، البصري، الذهبي). ونموذج الجودة واضح في أن خصائص مختلفة تكون مهمة في سياقات استخدام مختلفة.

مثال عملي

الطبقات قابلة للاستدعاء من سكربتات المحرك نفسها. يُتحقق من التغيير في مُنسّق واحد عند القاعدة. أما التغيير في واجهة المستند فيُتحقق منه عبر الطبقات:

<?php

declare(strict_types=1);

// Tier 1 — Unit: one unit, isolated, fast.
// composer test:unit         → phpunit --testsuite Unit

// Tier 2 — Integration: collaborating units across a boundary.
// composer test:integration  → phpunit --testsuite Integration

// Tier 3 — Structural: the emitted PDF object graph is well-formed.
// vendor/bin/phpunit --testsuite Conformance

// Tier 4/5 — Visual + Golden: rendered/serialized output vs a pinned
// reference (golden is byte/structure-pinned, never auto-updated).
// vendor/bin/phpunit --testsuite Golden

// A change to the document facade touches every API, so the routing
// guidance escalates it from "unit only" to the full unit + integration
// surface — the tier you run is a function of blast radius, not habit.

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

مفهوم خاطئ شائع

كثيرًا ما يُقرأ الهرم بوصفه ترتيبًا تفاضليًا — اختبارات الوحدة في الأسفل لأنها الأقل أهمية، والاختبارات الشاملة (⁨end-to-end⁩) في الأعلى لأنها الأكثر أهمية (أو العكس). وهذا غير صحيح إطلاقًا. يمثل المحور الرأسي تقريبًا التكلفة والكمية: اختبارات وحدة كثيرة وسريعة ومنخفضة التكلفة تُشكّل قاعدة عريضة؛ ثم اختبارات أقل عددًا وأبطأ وأعلى دقة تدريجيًا في الأعلى. الاختبار الذهبي ليس “أفضل” من اختبار الوحدة. إنه يلتقط نوعًا مختلفًا من الفشل، في وقت لاحق، وبتكلفة أعلى، وسيكون بديلًا رديئًا عن آلاف الفحوص السريعة التي تحته.

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

الحدود والقيود

تصف هذه الصفحة شكل الاستراتيجية ومقصدها، لا نتائجها الحالية. أعداد الاختبارات ونسب التغطية ودرجات الطفرات غير مذكورة هنا عن قصد. فهي إشارات جودة حيّة، تُولَّد من مُخرجات التكامل المستمر. تُنشَر الأرقام الحالية مع البناء. ولو ثُبّتت في النص، لأصبحت قديمة بصمت. الرقم الوحيد المذكور — ⁨PHPStan Level 10⁩ — حقيقة تكوين مستقرة، يمكن التحقق منها في تكوين التحليل الساكن للمحرك، وليس قياسًا.

أسماء الطبقات مصطلحات معمارية مستقرة. أما المجموعة الدقيقة للمجموعات وملفات تنفيذها فتتطور مع المحرك، ويمتلكها تكوين الاختبار، وهو المرجع المعتمد إذا اختلف يومًا مع هذا الشرح. لا تؤكد هذه الصفحة أي معدل نجاح محدد ولا تُجري أي مقارنة باستراتيجية اختبار أي مكتبة أخرى.

مستندات ذات صلة

اختبار الملفات الذهبية — كيف تُثبّت طبقة القمة الخرج المرجعي وتحافظ على أمانته.
اختبار الطفرات، شرح مفصّل — لماذا لا يُثبت رقم التغطية أن الاختبارات في هذه الطبقات تعمل فعلًا.
الأنواع الصارمة، في كل مكان — كيف يُزيل ⁨PHPStan Level 10⁩ صنفًا من العيوب قبل تشغيل أي طبقة.

مسرد المصطلحات

طبقة الاختبار — مستوى من الاستراتيجية يُثبت نوعًا واحدًا من الخصائص (على سبيل المثال، سلوك الوحدة أو الصلاحية البنيوية). يستخدم ⁨NextPDF⁩ خمس طبقات.
الاختبار البنيوي — فحص يتأكد من أن مخطط كائنات ⁨PDF⁩ المُصدَر وجدول الإحالات المرجعية والذيل (⁨trailer⁩) سليمة التكوين ومتوافقة، لا مجرد فحص قيمة مُعادة.
الاختبار البصري — فحص يتأكد من أن صفحة معروضة تطابق صورة مرجعية معتمدة ضمن هامش تسامح مُعلَن.
الاختبار الذهبي — فحص شامل (⁨end-to-end⁩) مقابل خرج مرجعي مثبَّت لا يُحدَّث تلقائيًا أبدًا؛ وهو العقد الذي يضمن “أن الخرج لم يتغير”.
فاعلية الاختبار — قدرة مجموعة اختبار على كشف العيوب، وهو ما يميّزه ⁨ISO/IEC/IEEE 29119-4⁩ عن التغطية. ملاحظة بشأن الاختصار: يُعرَّف ⁨MSI⁩ (⁨Mutation Score Indicator⁩) في صفحة اختبار الطفرات.
⁨PHPStan Level 10⁩ — أصرم مستوى للتحليل الساكن؛ يُشغّله ⁨NextPDF⁩ مع تثبيت ميزانية الأخطاء عند الصفر.