ApiTestCase

ApiTestCase

ApiTestCase هو PHPUnit TestCase الذي سيجعل حياتك كمطور Symfony API أسهل بكثير. فهو يمتد Symfony WebTestCase الأساسي مع بعض الميزات الرائعة.

بفضل PHP-Matcher، يمكنك، وفقًا للملف التمهيدي الخاص به، "كتابة استجابات json المتوقعة مثل رجل العصابات". نحن نتفق بالتأكيد.

كما أنه يستخدم Alice لسهولة تحميل تركيبات Doctrine.

سمات:

• مسح سير عمل TDD لتطوير واجهة برمجة التطبيقات (API) باستخدام Symfony؛
• مطابقة JSON/XML مع رسائل خطأ واضحة؛
• تحميل المباريات مع أليس (اختياري) ؛

تثبيت

بافتراض أن برنامج Composer مثبت عالميًا بالفعل:

composer require --dev lchrusciel/api-test-case

وقد تم ذلك! يعمل ApiTestCase مع التكوين الافتراضي.

الاستخدام

نحن نقدم فئتين أساسيتين لحالات الاختبار الخاصة بك: JsonApiTestCase وXmlApiTestCase. اختر واحدًا بناءً على تنسيق واجهة برمجة التطبيقات (API) التي تريد إنشاءها.

مثال جيسون

سير العمل الأساسي لـ TDD هو كما يلي:

1. اكتب حالة اختبار ترسل الطلب واستخدم طريقة تأكيد assertResponse للتحقق مما إذا كانت محتويات الاستجابة تتوافق مع توقعاتك. أنت بحاجة إلى اسم لملف الاستجابة؛
2. قم بإنشاء الملف بالاسم الذي اخترته في الخطوة 1. ثم ضع محتويات الاستجابة المتوقعة هناك. يجب وضعه في src/AppBundle/Tests/Responses/Expected/hello_world.json على سبيل المثال.
3. اجعلها حمراء.
4. اجعلها خضراء.
5. إعادة البناء.

دعونا نرى مثالا بسيطا! اكتب الاختبار التالي:

 namespace AppBundle  Tests  Controller  HelloWorldTest ;

use ApiTestCase  JsonApiTestCase ;

class HelloWorldTest extends JsonApiTestCase
{
    public function testGetHelloWorldResponse ()
    {
        $ this -> client -> request ( ' GET ' , ' / ' );

        $ response = $ this -> client -> getResponse ();

        $ this -> assertResponse ( $ response , ' hello_world ' );
    }
}

الآن حدد ملف الاستجابة المتوقعة:

{
    "message" : " Hello ApiTestCase World! "
}

قم بإجراء اختباراتك:

vendor/bin/phpunit

من المفترض أن يفشل الاختبار الخاص بك مع وجود بعض الأخطاء، ومن المحتمل أنك تفتقد وحدة التحكم والتوجيه، لذا تابع وحددهما! بمجرد تنفيذ وحدة التحكم الخاصة بك وتكوين التوجيه المناسب، يمكنك تشغيل اختباراتك مرة أخرى:

إذا كانت محتويات الاستجابة تتوافق مع توقعاتنا، فسوف تقدم وحدة التحكم رسالة بسيطة:

OK (1 tests, 2 assertions)

وإلا فإنه سيظهر اختلافًا في الرسائل المستلمة:

 " Hello ApiTestCase World " does not match " Hello ApiTestCase World! " .
@@ -1,4 +1,3 @@
 {
-    " message " : " Hello ApiTestCase World! "
+    " message " : " Hello ApiTestCase World "
 }
-

أولاً، ستتحقق الدالة assertResponse من رمز الاستجابة (200 هو رمز الاستجابة الافتراضي)، ثم ستتحقق مما إذا كان رأس الاستجابة يحتوي على نوع محتوى application/json . في النهاية سيتم التحقق مما إذا كانت محتويات الاستجابة تطابق التوقعات. في بعض الأحيان، لا يمكنك التنبؤ ببعض القيم في الاستجابة، على سبيل المثال التاريخ أو المعرف الذي تم إنشاؤه تلقائيًا من قاعدة البيانات. ليست هناك حاجة إلى السحر هنا لأن PHP-Matcher يأتي مع يد المساعدة. هذه مجرد أمثلة قليلة من الأنماط المتاحة:

• @string@
• @integer@
• @boolean@
• @array@

تحقق من المزيد حول وثائق PHP-Matcher.

مع هذه الأنماط، ستبدو استجابتك المتوقعة كما يلي:

{
    "message" : " @string@ "
}

مع وضع هذا في مكانه، فإن أي سلسلة أسفل message الرئيسية سوف تتطابق مع النمط. قد تبدو الاستجابة المتوقعة الأكثر تعقيدًا كما يلي:

[
    {
        "id" : " @integer@ " ,
        "name" : " Star-Wars T-shirt " ,
        "sku" : " SWTS " ,
        "price" : 5500 ,
        "sizes" : " @array@ " ,
        "created_at" : " @[email protected]() "
    },
    {
        "id" : " @integer@ " ,
        "name" : " Han Solo Mug " ,
        "sku" : " HSM " ,
        "price" : 500 ,
        "sizes" : " @array@ " ,
        "created_at" : " @[email protected]() "
    }
]

وسوف تتطابق مع قائمة المنتجات التالية:

 array (
    array (
        ' id ' => 1 ,
        ' name ' => ' Star-Wars T-shirt ' ,
        ' sku ' => ' SWTS ' ,
        ' price ' => 5500 ,
        ' sizes ' => array ( ' S ' , ' M ' , ' L ' ),
        ' created_at ' => new  DateTime (),
    ),
    array (
        ' id ' => 2 ,
        ' name ' => ' Han Solo Mug ' ,
        ' sku ' => ' HSM ' ,
        ' price ' => 500 ,
        ' sizes ' => array ( ' S ' , ' L ' ),
        ' created_at ' => new  DateTime (),
    ),
)

اختبار مع تركيبات قاعدة البيانات

تم دمج ApiTestCase مع nelmio/alice . بفضل هذه المكتبة الرائعة، يمكنك بسهولة تحميل تجهيزاتك عندما تحتاج إليها. يجب عليك تحديد التركيبات الخاصة بك ووضعها في الدليل المناسب. فيما يلي بعض الأمثلة على كيفية تحديد التركيبات وحالة الاستخدام. لمزيد من المعلومات حول كيفية تحديد التركيبات الخاصة بك، راجع وثائق أليس.

من أجل استخدام Alice with Doctrine، يجب عليك تمكين حزمتين إضافيتين:

سيمفوني 4.0+

 // config/bundles.php
return [
    // ...
    
    Nelmio  Alice  Bridge  Symfony NelmioAliceBundle::class => [ ' test ' => true ],
    Fidry  AliceDataFixtures  Bridge  Symfony FidryAliceDataFixturesBundle::class => [ ' test ' => true ],
];

الآن، لنفترض أن لديك كيان Doctrine معين يسمى Book في تطبيقك:

    class Book 
    {
        private $ id ;
        private $ title ;
        private $ author ;
    
        // ... 
    }

لتحميل التجهيزات للاختبار، تحتاج إلى تحديد ملف YAML بسيط في src/AppBundle/Tests/DataFixtures/ORM/books.yml :

    ApiTestCaseTestEntityBook :
        book1 :
            title : " Lord of The Rings "
            author : " J. R. R. Tolkien "
        book2 :
            title : " Game of Thrones "
            price : " George R. R. Martin "

أخيرًا، لاستخدام هذه التركيبات في الاختبار، ما عليك سوى استدعاء الطريقة المناسبة:

    public function testBooksIndexAction ()
    {
        // This method require subpath to locate specific fixture file in your DataFixtures/ORM directory.
        $ this -> loadFixturesFromFile ( ' books.yml ' );  
      
        // There is another method that allows you to load fixtures from directory.
        $ this -> loadFixturesFromDirectory ( ' big_library ' );
    }

مرجع التكوين

لتخصيص تكوين مجموعة الاختبار الخاصة بك، يمكنك إضافة بعض الخيارات الإضافية إلى phpunit.xml:

< php >
    < server name = " KERNEL_CLASS " value = " AcmeKernel " />
    < server name = " EXPECTED_RESPONSE_DIR " value = " /path/to/expected/responses/ " />
    < server name = " FIXTURES_DIR " value = " /path/to/DataFixtures/ORM/ " />
    < server name = " OPEN_ERROR_IN_BROWSER " value = " true/false " />
    < server name = " OPEN_BROWSER_COMMAND " value = " open %s " />
    < server name = " IS_DOCTRINE_ORM_SUPPORTED " value = " true/false " />
    < server name = " TMP_DIR " value = " /tmp/path/to/temporary/folder/ " />
    < server name = " ESCAPE_JSON " value = " true/false " />
</ php >

• يتيح لك KERNEL_CLASS تحديد الفئة التي يجب استخدامها بالضبط لإعداد Kernel.
• يحتوي متغير ERESPONSE_DIR على مسارات للمجلد مع الاستجابات المتوقعة. يتم استخدامه عند مقارنة نتيجة API بملف json الموجود. إذا لم يتم تعيين هذه القيمة، فسيحاول ApiTestCase تخمين موقع الاستجابات، والبحث عن الاستجابات في مجلد: '../Responses' الموجود نسبيًا في فئة اختبار وحدة التحكم الخاصة بك.
• يحتوي المتغير FIXTURES_DIR على مسار إلى المجلد الذي يحتوي على تركيبات البيانات الخاصة بك. افتراضيًا، إذا لم يتم تعيين هذا المتغير، فسوف يبحث عن ../DataFixtures/ORM/ الموجود نسبيًا في فئة الاختبار الخاصة بك. يقوم ApiTestCase بطرح RunTimeException في حالة عدم وجود المجلد أو لن يكون هناك أي ملفات للتحميل.
• OPEN_ERROR_IN_BROWSER هي علامة تعمل على عرض الخطأ في نافذة المتصفح. القيمة الافتراضية خاطئة.
• OPEN_BROWSER_COMMAND هو أمر سيتم استخدامه لفتح المتصفح مع استثناء.
• IS_DOCTRINE_ORM_SUPPORTED هي علامة تعمل على تشغيل دعم العقيدة، بما في ذلك أداة تحميل تركيبات البيانات سهلة الاستخدام وأداة تنظيف قاعدة البيانات.
• يحتوي متغير TMP_DIR على مسار إلى المجلد المؤقت، حيث سيتم تخزين ملفات السجل.
• ESCAPE_JSON هي علامة تقوم بتشغيل الهروب (أحرف Unicode والشرط المائلة) لمخرجات JSON الخاصة بك قبل مقارنتها بالبيانات المتوقعة. القيمة الافتراضية خاطئة. توجد هذه العلامة فقط للتوافق مع الإصدارات السابقة مع الإصدارات السابقة من ApiTestCase (عند تشغيلها) وستتم إزالتها في إصدار مستقبلي.

مشروع عينة

في الدليل test/ ، يمكنك العثور على نموذج لمشروع Symfony مع الحد الأدنى من التكوين المطلوب لاستخدام هذه المكتبة.

اختبار

من أجل تشغيل مجموعة اختبارات PHPUnit الخاصة بنا، قم بتنفيذ الأوامر التالية:

composer install
test/app/console doctrine:database:create
test/app/console doctrine:schema:create
vendor/bin/phpunit

تتبع الأخطاء والاقتراحات

إذا وجدت خطأ ما أو كانت لديك فكرة رائعة للتحسين، فيرجى فتح مشكلة في هذا المستودع.

الإصدار

سيتم ترقيم الإصدارات بالتنسيق major.minor.patch .

وتم بناؤها وفقًا للمبادئ التوجيهية التالية.

• كسر التوافق مع الإصدارات السابقة يصطدم بالتخصص.
• إضافات جديدة دون كسر التوافق مع الإصدارات السابقة.
• إصلاحات الأخطاء والتغييرات المتنوعة تصطدم بالتصحيح.

لمزيد من المعلومات حول SemVer، يرجى زيارة موقع semver.org.

رخصة معهد ماساتشوستس للتكنولوجيا

يمكن العثور على الترخيص هنا.

المؤلفون

تم إنشاء المكتبة في الأصل بواسطة:

• لوكاس كروشيل
• ميشال مارسينكوفسكي
• باول Jędrzejewski
• أركاديوس كراكوفياك

في شركة Lakion ضمن مستودع https://github.com/Lakion/ApiTestCase.

انظر قائمة المساهمين.