اختبار الملفات الذهبية

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

لمحة سريعة

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

لماذا يهمّ هذا

توليد ⁨PDF⁩ مسار طويل تتعدد فيه المواضع التي قد تنحرف بصمت. قد تؤدي إعادة هيكلة “لا تغيّر شيئًا” إلى إعادة ترتيب المُعامِلات بهدوء، أو تغيير مصفوفة تحويل، أو إزاحة خلية جدول بمقدار ضئيل. نادرًا ما تكتشف اختبارات الوحدة ذلك: فهي تؤكّد قيمة فكّرت في فحصها، لا آلاف البايتات التي لم تفحصها. تكتشف التقنيات المستندة إلى البنية والمستندة إلى المواصفة أخطاءً مختلفة، ولا تُغني إحداهما عن الأخرى (⁨ISO/IEC/IEEE 29119-4⁩, ⁨Annex A⁩). الملف الذهبي هو المواصفة بالمثال التي تثبّت المخرجات بأكملها، لا تأكيدًا واحدًا.

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

باختصار

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

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

تستخدم البنية التحتية الذهبية للمحرك مقارنة فرق ذات طبقتين صريحة بدلًا من مقارنة بايتية:

Generate Render the fixture input through the current engine.
Layer 1 — text Extract human-readable text from the content stream; diff against the text golden. Catches dropped or reordered content and encoding regressions.
Layer 2 — structure Extract ordered PDF operators, normalise coordinates to a fixed precision, diff against the operator golden. Catches layout shifts and broken structure.
Decide Any diff fails the test; a human judges whether it is a regression or an intended change.

كيف تجري مقارنة ذهبية في NextPDF: تولّد ملف PDF، وتستخرج الطبقات المُجدية (النص، ثم المُعامِلات البنيوية المُطبَّعة)، وتقارن فرق كلٍّ منها بالمرجع المثبَّت، وتفشل بتقرير قابل للقراءة البشرية عند أي اختلاف.

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

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

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

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

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

Evidence: Test-backed آلية الصدق ملموسة: المراجع الذهبية مُصنَعات مُولَّدة، لا مكتوبة باليد. والكتابة فوقها محصورة خلف مفتاح بيئة GOLDEN_UPDATE صريح موثَّق بوصفها عملية نادرة ومُراجَعة دائمًا. في المقابل، تُعاد توليد اختبارات اللقطة في المحرك عند أول تشغيل، ويُقرّ بالانحراف عبر علامة تحديث. أما اختبارات التوصيف فتثبّت السلوك القديم دون أن تدّعي أنه صحيح. الأدوات الثلاث مختلفة عن قصد.

Evidence: Standard-backed الملف الذهبي هو مواصفة بالمثال. Spec: ISO/IEC/IEEE 29119-4, Annex A يشير إلى أن التقنيات المستندة إلى المواصفة والمستندة إلى البنية تكتشف فئات مختلفة من الأخطاء، وأن أي استراتيجية ينبغي أن تجمع بينها. لذلك تقف الملفات الذهبية جنبًا إلى جنب مع اختبارات الوحدة والاختبارات البنيوية في هرم الاختبار.

مثال عملي

الاختبار الذهبي بسيط من الناحية الميكانيكية؛ والانضباط يكمن في سير العمل المحيط به:

<?php

declare(strict_types=1);

// 1. The fixture: a fixed HTML input committed next to the test.
//    tests/Golden/fixtures/html-inputs/002-basic-table.html

// 2. The pinned references, generated once from known-good behaviour:
//    002-basic-table.text.golden       (Layer 1 — extracted text)
//    002-basic-table.operators.golden  (Layer 2 — normalised operators)

// 3. The run compares; ANY difference fails:
//    vendor/bin/phpunit --testsuite Golden

// 4. An intended behaviour change is the ONLY time references move,
//    and it is explicit and reviewed — never automatic:
//    GOLDEN_UPDATE=1 vendor/bin/phpunit --testsuite Golden
//
//    The regenerated *.golden files land in the diff of the same change
//    that altered behaviour, so a reviewer sees the output delta next to
//    the code delta and signs off on both together.

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

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

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

الخطأ الثاني هو افتراض أن مجموعة اختبارات ذهبية خضراء تثبت الصحة. إنها تثبت عدم التغيير. الملف الذهبي المُولَّد من مخرجات معيبة يحمي العلّة بأمانة. تحرس الملفات الذهبية من الانحدار عن خط أساس معلوم الصحة؛ لكنها لا تثبت أن خط الأساس كان جيدًا. ذلك هو الغرض من طبقات الوحدة والبنية والمطابقة.

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

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

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

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

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

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

الملف الذهبي — مخرجات مرجعية مثبَّتة، مُولَّدة من سلوك محرك معلوم الصحة ومودَعة، يقارن بها الاختبار في كل تشغيل. لا يُحدَّث آليًا أبدًا.
مقارنة الفرق ذات الطبقتين — المقارنة الذهبية في ⁨NextPDF⁩: النص المستخرَج (الطبقة 1) إضافةً إلى المُعامِلات البنيوية المُطبَّعة (الطبقة 2)، بدلًا من البايتات الخام.
اختبار اللقطة — تقنية ذات صلة لكنها متمايزة، يُعاد فيها توليد المرجع عند أول تشغيل ويُقرّ بالانحراف عبر علامة تحديث.
اختبار التوصيف — اختبار يثبّت السلوك القائم دون تأكيد صحته، عادةً لجعل إعادة الهيكلة آمنة.
ملف قابلية إعادة الإنتاج — المستوى الذي يجب أن تُعاد عنده المخرجات: بِتّي (البايتات بالضبط)، أو بنيوي (مخطط الكائنات وتسلسل المُعامِلات، مع السماح بتباين بايتي حميد)، أو دلالي (المعنى). تؤكّد الاختبارات الذهبية هنا الملف البنيوي.
GOLDEN_UPDATE — مفتاح البيئة الصريح الذي يأذن بالكتابة فوق المراجع الذهبية؛ عملية نادرة ومُراجَعة.