7. اختبار خوارزميات المعالجة

7.1. اختبارات الخوارزميات

ملاحظة

النسخة الأصلية من هذه التعليمات متاحة في https://github.com/qgis/QGIS/blob/release-3_44/python/plugins/processing/tests/README.md

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

لاختبار الخوارزميات يمكنك إضافة مدخلات إلى testdata/qgis_algorithm_tests.yaml أو testdata/gdal_algorithm_tests.yaml حسب الاقتضاء.

هذا الملف مبني وفق صيغة yaml.

يظهر الاختبار الأساسي تحت المفتاح tests في المستوى الأعلى ويبدو هكذا:

- name: centroid
  algorithm: qgis:polygoncentroids
  params:
    - type: vector
      name: polys.gml
  results:
    OUTPUT_LAYER:
      type: vector
      name: expected/polys_centroid.gml

7.1.1. طريقة العمل

لإضافة اختبار جديد يُرجى اتباع هذه الخطوات:

1. شغّل الخوارزمية التي تريد اختبارها في QGIS من صندوق أدوات المعالجة. إذا كانت النتيجة طبقة متجهية ففضّل صيغة GML مع ملف XSD الخاص بها كمخرج، لدعمها أنواع الأشكال الهندسية المختلطة وسهولة قراءتها. وجّه المخرج إلى python/plugins/processing/tests/testdata/expected. وبالنسبة لطبقات الإدخال ففضّل استخدام ما هو موجود بالفعل في المجلد testdata. وإذا احتجت إلى بيانات إضافية فضعها في testdata/custom.

2. بعد تشغيل الخوارزمية، انتقل إلى Processing ► History وابحث عن الخوارزمية التي شغّلتها للتو.

3. انقر بزر الفأرة الأيمن على الخوارزمية ثم انقر Create Test. ستُفتح نافذة جديدة تحتوي على تعريف نصي.

4. افتح الملف python/plugins/processing/tests/testdata/algorithm_tests.yaml وانسخ التعريف النصي إليه.

تذهب السلسلة النصية الأولى من الأمر إلى المفتاح algorithm، والسلاسل اللاحقة إلى params، والأخيرة (أو الأخيرات) إلى results.

يُترجَم ما سبق إلى

- name: densify
  algorithm: qgis:densifygeometriesgivenaninterval
  params:
    - type: vector
      name: polys.gml
    - 2 # Interval
  results:
    OUTPUT:
      type: vector
      name: expected/polys_densify.gml

يمكن أيضًا إنشاء اختبارات لسكربتات المعالجة. ويجب وضع السكربتات في المجلد الفرعي scripts داخل مجلد بيانات الاختبار python/plugins/processing/tests/testdata/. ويجب أن يطابق اسم ملف السكربت اسم خوارزمية السكربت.

7.1.2. المعاملات والنتائج

معاملات الأنواع البسيطة

تُحدَّد المعاملات والنتائج كقوائم أو قواميس:

params:
  INTERVAL: 5
  INTERPOLATE: True
  NAME: A processing test

أو

params:
  - 2
  - string
  - another param

معاملات من نوع طبقة

ستحتاج غالبًا إلى تحديد طبقات كمعاملات. ولتحديد طبقة ستحتاج إلى تحديد:

• النوع، أي vector أو raster

• اسم، مع مسار نسبي مثل expected/polys_centroid.gml

وهذا ما يبدو عليه الأمر عمليًا:

params:
  PAR: 2
  STR: string
  LAYER:
    type: vector
    name: polys.gml
  OTHER: another param

معاملات من نوع ملف

إذا احتجت إلى ملف خارجي لاختبار الخوارزمية، فعليك تحديد النوع 'file' والمسار (النسبي) للملف في 'name':

params:
  PAR: 2
  STR: string
  EXTFILE:
    type: file
    name: custom/grass7/extfile.txt
  OTHER: another param

النتائج

تُحدَّد النتائج بطريقة مشابهة جدًا.

ملفات متجهية أساسية

لا يمكن أن يكون الأمر أبسط من ذلك

OUTPUT:
 name: expected/qgis_intersection.gml
 type: vector

أضف ملفات GML و XSD المتوقعة إلى المجلد.

بيانات متجهية مع هامش تسامح

أحيانًا تُنتج المنصات المختلفة نتائج مختلفة قليلًا لكنها تظل مقبولة. في هذه الحالة (وفيها فقط) يمكنك أيضًا استخدام خصائص إضافية لتحديد كيفية مقارنة الطبقة.

للتعامل مع هامش تسامح معين لقيم المخرجات يمكنك تحديد الخاصية compare للمخرج. ويمكن أن تحتوي خاصية المقارنة على خصائص فرعية لـ fields. وتتضمن هذه معلومات عن مدى دقة مقارنة حقل معين (precision)، أو حتى تجاهل حقل بالكامل (skip). ويوجد اسم حقل خاص __all__ يطبّق هامش تسامح معينًا على جميع الحقول. وهناك خاصية أخرى geometry تقبل أيضًا precision يُطبَّق على كل رأس.

OUTPUT:
 type: vector
 name: expected/abcd.gml
 compare:
   fields:
     __all__:
       precision: 5 # compare to a precision of .00001 on all fields
     A: skip # skip field A
   geometry:
     precision: 5 # compare coordinates with a precision of 5 digits

الملفات الشبكية (رستر)

تُقارَن الملفات الشبكية باستخدام مجموع تحقق (hash checksum). ويُحسب هذا عند إنشاء اختبار من سجل المعالجة.

OUTPUT:
 type: rasterhash
 hash: f1fedeb6782f9389cf43590d4c85ada9155ab61fef6dc285aaeb54d6

الملفات

يمكنك مقارنة محتوى ملف مخرج بملف مرجعي للنتيجة المتوقعة

OUTPUT_HTML_FILE:
 name: expected/basic_statistics_string.html
 type: file

أو يمكنك استخدام تعبير نمطي (regular expression) واحد أو أكثر يُطابَق مع محتوى الملف

OUTPUT:
 name: layer_info.html
 type: regex
 rules:
   - 'Extent: \(-1.000000, -3.000000\) - \(11.000000, 5.000000\)'
   - 'Geometry: Line String'
   - 'Feature Count: 6'

المجلدات

يمكنك مقارنة محتوى مجلد مخرج بمجلد مرجعي للنتيجة المتوقعة

OUTPUT_DIR:
 name: expected/tiles_xyz/test_1
 type: directory

7.1.3. سياق الخوارزمية

هناك بعض التعريفات الإضافية التي يمكنها تعديل سياق الخوارزمية، ويمكن تحديدها في المستوى الأعلى من الاختبار:

• project - يحمّل ملف مشروع QGIS محددًا قبل تشغيل الخوارزمية. وإذا لم يُحدَّد، فستعمل الخوارزمية بمشروع فارغ

• project_crs - يتجاوز نظام الإحداثيات المرجعي الافتراضي للمشروع، مثلًا EPSG:27700

• ellipsoid - يتجاوز الشكل الإهليلجي (ellipsoid) الافتراضي للمشروع المستخدم في القياسات، مثلًا GRS80

7.1.4. تشغيل الاختبارات محليًا

ctest -V -R ProcessingQgisAlgorithmsTest

أو إحدى القيم التالية المدرجة في CMakelists.txt