عرض مصدر Laravel/http tests

 <noinclude>{{DISPLAYTITLE:اختبارات HTTP}}</noinclude>
== مقدمة ==
يزوّدك Laravel بـواجهة برمجيّة سلسة للقيام بطلبات HTTP لتطبيقك وتحليل الناتج. على سبيل المثال، القِ نظرة على الاختبار التالي:<syntaxhighlight lang="php">
<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Foundation\Testing\WithoutMiddleware;

class ExampleTest extends TestCase
{
   /**
    * مثال اختبار بسيط.
    *
    * @return void
    */
   public function testBasicTest()
   {
       $response = $this->get('/');
       $response->assertStatus(200);
   }
}
</syntaxhighlight>

ينشئ التابع <code>get</code> طلب <code>GET</code> للتطبيق، بينما يتأكد التابع <code>assertStatus</code> من أنّ الرد المُعاد يحتوي على رمز حالة HTTP المعطى. إضافةً إلى هذا التأكد البسيط، يحتوي Laravel على مجموعة من توابع التأكيد لفحص المعلومات المتعلقة بالرد، كترويسات الرد (response headers)‎، ومحتوى الرد، وبنية JSON، والمزيد من المعلومات.

=== تعديل ترويسات الطلب ===
يمكنك استخدام التابع <code>withHeaders</code> من أجل تعديل ترويسات الطلب قبل إرساله للتطبيق. يمكنك من خلال هذا التابع إضافة أي ترويسة إلى الطلب المرسل.<syntaxhighlight lang="php">
<?php

class ExampleTest extends TestCase
{
   /**
    * مثال اختبار بسيط.
    *
    * @return void
    */
   public function testBasicExample()
   {
       $response = $this->withHeaders([
           'X-Header' => 'Value',
       ])->json('POST', '/user', ['name' => 'Sally']);

       $response
           ->assertStatus(201)
           ->assertJson([
               'created' => true,
           ]);
   }
}
</syntaxhighlight>'''ملاحظة:''' تتوقف البرمجيّة الوسيطة CSRF تلقائيًا أثناء تشغيل الاختبارات.

== الجلسة والاستيثاق ==
يزوّدك Laravel بمجموعة من التوابع المساعدة للعمل مع الجلسات أثناء القيام باختبارات HTTP. أولًا، يمكنك تعيين بيانات الجلسة إلى مصفوفة محدّدة وذلك باستخدام التابع <code>withSession</code>؛ إذ يساعد هذا التابع على تحميل الجلسة بالبيانات قبل إرسال الطلب لتطبيقك:<syntaxhighlight lang="php">
<?php

class ExampleTest extends TestCase
{
   public function testApplication()
   {
       $response = $this->withSession(['foo' => 'bar'])
                        ->get('/');
   }
}
</syntaxhighlight>

بالطبع، إن أحد أهم استخدامات الجلسة هو الحاجة للاحتفاظ بحالة مستخدم الاستيثاق. يزوّدك التابع المساعد <code>actingAs</code> بطريقة بسيطة لتسجيل الدخول باستخدام المستخدم المعطى. فعلى سبيل المثال، يمكننا استخدام [[Laravel/database testing|model factory]] لتوليد المستخدم وتسجيل الدخول باستخدامه:<syntaxhighlight lang="php">
<?php

use App\User;

class ExampleTest extends TestCase
{
   public function testApplication()
   {
       $user = factory(User::class)->create();

       $response = $this->actingAs($user)
                        ->withSession(['foo' => 'bar'])
                        ->get('/');
   }
}
</syntaxhighlight>يمكنك أيضًا تعيين أي حارس (guard) سيتمّ استخدامه للمصادقة على المستخدم، وذلك بتمرير اسم الحارس كوسيط الثاني للتابع <code>actingAs</code> كالتالي:<syntaxhighlight lang="php">
$this->actingAs($user, 'api')
</syntaxhighlight>

== اختبار الواجهات البرمجيّة JSON ==
يزوّدك Laravel أيضًا بمجموعة من التوابع المساعدة لاختبار الواجهات البرمجيّة التي تخص JSON وردودها. على سبيل المثال، يمكن استخدام التوابع <code>json</code> و <code>get</code> و <code>post</code> و <code>put</code> و <code>patch</code> و <code>delete</code> لإرسال الطلبات باستخدام طرق HTTP المتعددة. يمكنك أيضًا تمرير البيانات والترويسات بسهولة لهذه التوابع. للبدء، لنكتب اختبار يرسل طلب <code>POST</code> إلى <code>user/</code> ويتأكّد من أنّ البيانات المتوقّعة توافق البيانات المعادة:<syntaxhighlight lang="php">
<?php

class ExampleTest extends TestCase
{
   /**
    * مثال اختبار بسيط.
    *
    * @return void
    */
   public function testBasicExample()
   {
       $response = $this->json('POST', '/user', ['name' => 'Sally']);

       $response
           ->assertStatus(201)
           ->assertJson([
               'created' => true,
           ]);
   }
}
</syntaxhighlight>'''ملاحظة:''' يحوّل التابع <code>assertJson</code> الرد إلى مصفوفة ويستخدم التابع <code>PHPUnit::assertArraySubset</code> للتأكد من أنّ المصفوفة المعطاة موجودة ضمن البيانات المعادة في الرد. لذلك في حال كان هناك بيانات إضافيّة في رد JSON، سيعطي نتيجة إيجابية ما دامت القطعة المعطاة من المصفوفة موجودة في الرد.

=== التأكّد من موافقة تامّة لرد الـ JSON ===
في حال أردت التأكّد من أنّ المصفوفة المعطاة توافق تمامًا الرد JSON المعاد من التطبيق، استخدم التابع <code>assertExactJson</code>:<syntaxhighlight lang="php">
<?php

class ExampleTest extends TestCase
{
   /**
    * مثال اختبار بسيط.
    *
    * @return void
    */
   public function testBasicExample()
   {
       $response = $this->json('POST', '/user', ['name' => 'Sally']);

       $response
           ->assertStatus(201)
           ->assertExactJson([
               'created' => true,
           ]);
   }
}
</syntaxhighlight>

== اختبار رفع الملفات ==
يزوّد الصنف <code>Illuminate\Http\UploadedFile</code> التابع <code>fake</code> الذي يستخدم لتوليد ملفّات أو صور اختبار. عند دمج هذا التابع المساعد مع التابع <code>fake</code> الخاص بالصنف <code>Storage</code>، يمكن تبسيط رفع الملفات إلى حد كبير. على سبيل المثال، يمكنك دمج هذين التابعين ببساطة لاختبار نموذج رفع صورة شخصية:<syntaxhighlight lang="php">
<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Foundation\Testing\WithoutMiddleware;

class ExampleTest extends TestCase
{
   public function testAvatarUpload()
   {
       Storage::fake('avatars');

       $file = UploadedFile::fake()->image('avatar.jpg');

       $response = $this->json('POST', '/avatar', [
           'avatar' => $file,
       ]);

       // التأكد من تخزين الملف
       Storage::disk('avatars')->assertExists($file->hashName());

       // التأكد من عدم وجود الملف
       Storage::disk('avatars')->assertMissing('missing.jpg');
   }
}
</syntaxhighlight>

=== تزييف تخصيص الملفات ===
عند توليد الملفات باستخدام التابع <code>fake</code>، يمكنك تحديد طول وعرض وحجم الصورة وذلك لاختبار قواعد التحقق الخاصة بتطبيقك:<syntaxhighlight lang="php">
UploadedFile::fake()->image('avatar.jpg', $width, $height)->size(100);
</syntaxhighlight>إضافةً إلى إنشاء الصور، يمكنك إنشاء الملفات باختلاف أنواعها باستخدام التابع <code>create</code> كالتالي:<syntaxhighlight lang="php">
UploadedFile::fake()->create('document.pdf', $sizeInKilobytes);
</syntaxhighlight>

== التوكيدات المتاحة ==

=== توكيدات الردود ===
يزوّدك Laravel بمجموعة من توابع التوكيد من أجل ملفات الاختبار المكتوبة باستخدام [https://phpunit.de/ PHPUnit]. يمكن استخدام هذه التوكيدات للوصول إلى بيانات الرد المعاد من التوابع المساعدة <code>json</code> و <code>get</code> و <code>post</code> و <code>put</code> و <code>delete</code>:

'''assertCookie'''
التأكد من أن الرد يحتوي على ملف تعريف الارتباط cookie المعطى:<syntaxhighlight lang="php">
$response->assertCookie($cookieName, $value = null);
</syntaxhighlight>

'''assertCookieExpired'''
التأكد من أن الرد يحتوي على ملف تعريف الارتباط cookie المعطى المنتهية صلاحيته:<syntaxhighlight lang="php">
$response->assertCookieExpired($cookieName);
</syntaxhighlight>

'''assertCookieNotExpired'''
التأكد من أن الرد يحتوي على ملف تعريف الارتباط cookie المعطى غير المنتهية صلاحيته:<syntaxhighlight lang="php">
$response->assertCookieNotExpired($cookieName);
</syntaxhighlight>

'''assertCookieMissing'''
التأكد من أن الرد لا يحتوي على ملف تعريف الارتباط cookie المعطى:<syntaxhighlight lang="php">
$response->assertCookieMissing($cookieName);
</syntaxhighlight>

'''assertDontSee'''
التأكد من أن السلسلة النصية المعطاة ليست محتواة ضمن الرد:<syntaxhighlight lang="php">
$response->assertDontSee($value);
</syntaxhighlight>

'''assertDontSeeText'''
التأكد من أن السلسلة النصية المعطاة ليست محتواة ضمن نص الرد:<syntaxhighlight lang="php">
$response->assertDontSeeText($value);
</syntaxhighlight>

'''assertExactJson'''
التأكد من أنّ الرد يوافق تمامًا بيانات الـ JSON المعطاة كمصفوفة للتابع:<syntaxhighlight lang="php">
$response->assertExactJson(array $data);
</syntaxhighlight>

'''assertForbidden'''
التأكد من أن الرد يحتوي على رمز حالة محظور Forbidden status code:<syntaxhighlight lang="php">
$response->assertForbidden();
</syntaxhighlight>

'''assertHeader'''
التأكد من أن الرد يحتوي على الترويسة المعطاة:<syntaxhighlight lang="php">
$response->assertHeader($headerName, $value = null);
</syntaxhighlight>

'''assertHeaderMissing'''
التأكد من أن الرد لا يحتوي على الترويسة المعطاة:<syntaxhighlight lang="php">
$response->assertHeaderMissing($headerName);
</syntaxhighlight>

'''assertJson'''
التأكد من أن الرد يحتوي على بيانات الـ JSON المعطاة كمصفوفة للتابع:<syntaxhighlight lang="php">
$response->assertJson(array $data);
</syntaxhighlight>

'''assertJsonCount'''
التأكد من أن الرد يحتوي على مصفوفة تملك العدد المعطى من العناصر عند المفتاح key المعطى:<syntaxhighlight lang="php">
$response->assertJsonCount($count, $key = null);
</syntaxhighlight>

'''assertJsonFragment'''
التأكد من أن الرد يحتوي على قطعة الـ JSON المعطاة:<syntaxhighlight lang="php">
$response->assertJsonFragment(array $data);
</syntaxhighlight>

'''assertJsonMissing'''
التأكد من أن الرد لا يحتوي على قطعة الـ JSON المعطاة:<syntaxhighlight lang="php">
$response->assertJsonMissing(array $data);
</syntaxhighlight>

'''assertJsonMissingExact'''
التأكد من أن الرد لا يوافق تمامًا قطعة الـ JSON المعطاة:<syntaxhighlight lang="php">
$response->assertJsonMissingExact(array $data);
</syntaxhighlight>

'''assertJsonStructure'''
التأكد من أن الرد يحتوي على بنية الـ JSON المعطاة:<syntaxhighlight lang="php">
$response->assertJsonStructure(array $structure);
</syntaxhighlight>

'''assertJsonValidationErrors'''
التأكد من أن الرد يحتوي على أخطاء الـتحقق المعطاة باستخدام المفاتيح keys:<syntaxhighlight lang="php">
$response->assertJsonValidationErrors($keys);
</syntaxhighlight>

'''assertLocation'''
التأكد من أن ترويسة Location في الرد تحتوي على الرابط المعطى:<syntaxhighlight lang="php">
$response->assertLocation($uri);
</syntaxhighlight>

'''assertNotFound'''
التأكد من أن الرد يحتوي على رمز حالة غير الموجود Not found status code:<syntaxhighlight lang="php">
$response->assertNotFound();
</syntaxhighlight>

'''assertOk'''
التأكد من أن الرد يحتوي على رمز الحالة 200:<syntaxhighlight lang="php">
$response->assertOk();
</syntaxhighlight>

'''assertPlainCookie'''
التأكد من أن الرد يحتوي على ملف تعريف الارتباط المعطى بشكل غير مشفر:<syntaxhighlight lang="php">
$response->assertPlainCookie($cookieName, $value = null);
</syntaxhighlight>

'''assertRedirect'''
التأكد من أن الرد هو إعادة توجيه إلى الرابط المعطى:<syntaxhighlight lang="php">
$response->assertRedirect($uri);
</syntaxhighlight>

'''assertSee'''
التأكد من أن السلسلة النصية المعطاة محتواة ضمن الرد:<syntaxhighlight lang="php">
$response->assertSee($value);
</syntaxhighlight>

'''assertSeeInOrder'''
التأكد من أن الرد يحتوي على السلاسل النصية المعطاة ضمن الترتيب نفسه:<syntaxhighlight lang="php">
$response->assertSeeInOrder(array $values);
</syntaxhighlight>

'''assertSeeText'''
التأكد من أن السلسلة النصية المعطاة محتواة ضمن نص الرد:<syntaxhighlight lang="php">
$response->assertSeeText($value);
</syntaxhighlight>

'''assertSeeTextInOrder'''
التأكد من أن نص الرد يحتوي على السلاسل النصية المعطاة ضمن الترتيب نفسه:<syntaxhighlight lang="php">
$response->assertSeeTextInOrder(array $values);
</syntaxhighlight>

'''assertSessionHas'''
التأكد من أن الجلسة تحتوي على البيانات المعطاة بمفتاح واحد:<syntaxhighlight lang="php">
$response->assertSessionHas($key, $value = null);
</syntaxhighlight>

'''assertSessionHasAll'''
التأكد من أن الجلسة تحتوي على مجموعة البيانات المعطاة بعدة مفاتيح:<syntaxhighlight lang="php">
$response->assertSessionHasAll(array $data);
</syntaxhighlight>

'''assertSessionHasErrors'''
التأكد من أن الجلسة تحتوي على خطأ عند الـ field المحدد:<syntaxhighlight lang="php">
$response->assertSessionHasErrors(array $keys, $format = null, $errorBag = 'default');
</syntaxhighlight>

'''assertSessionHasErrorsIn'''
التأكد من أن الجلسة تحتوي على الأخطاء المعطاة:<syntaxhighlight lang="php">
$response->assertSessionHasErrorsIn($errorBag, $keys = [], $format = null);
</syntaxhighlight>

'''assertSessionHasNoErrors'''
التأكد من أن الجلسة لا تحتوي على أية أخطاء:<syntaxhighlight lang="php">
$response->assertSessionHasNoErrors();
</syntaxhighlight>

'''assertSessionMissing'''
التأكد من أن الجلسة لا تحتوي على المفتاح المعطى:<syntaxhighlight lang="php">
$response->assertSessionMissing($key);
</syntaxhighlight>

'''assertStatus'''
التأكد من أن الرد يحتوي على رمز الحالة المعطى:<syntaxhighlight lang="php">
$response->assertStatus($code);
</syntaxhighlight>

'''assertSuccessful'''
التأكد من أن الرد يحتوي على رمز حالة ناجح 2xx:<syntaxhighlight lang="php">
$response->assertSuccessful();
</syntaxhighlight>

'''assertViewHas'''
التأكد من أن واجهة الرد response view تحتوي على البيانات المعطاة بمفتاح واحد:<syntaxhighlight lang="php">
$response->assertViewHas($key, $value = null);
</syntaxhighlight>

'''assertViewHasAll'''
التأكد من أن واجهة الرد response view تحتوي مجموعة على البيانات المعطاة بعدة مفاتيح:<syntaxhighlight lang="php">
$response->assertViewHasAll(array $data);
</syntaxhighlight>

'''assertViewIs'''
التأكد من أن الواجهة المعطاة توافق الواجهة المعادة:<syntaxhighlight lang="php">
$response->assertViewIs($value);
</syntaxhighlight>

'''assertViewMissing'''
التأكد من أن واجهة الرد لا تحتوي على البيانات المعطاة بمفتاح واحد:<syntaxhighlight lang="php">
$response->assertViewMissing($key);
</syntaxhighlight>

=== توكيدات الاستيثاق ===
يزوّدك Laravel أيضًا بمجموعة من التوكيدات المتعلقة بالاستيثاق من أجل اختبارات الـ [https://phpunit.de/ PHPUnit]:
{| class="wikitable"
|التابع
|الشرح
|-
|<syntaxhighlight lang="php">
$this->assertAuthenticated($guard = null);
</syntaxhighlight>
|التأكد من أن المستخدم مصادق عليه.
|-
|<syntaxhighlight lang="php">
$this->assertGuest($guard = null);
</syntaxhighlight>
|التأكد من أن المستخدم غير مصادق عليه.
|-
|<syntaxhighlight lang="php">
$this->assertAuthenticatedAs($user, $guard = null);
</syntaxhighlight>
|التأكد من أن المستخدم المعطى مصادق عليه.
|-
|<syntaxhighlight lang="php">
$this->assertCredentials(array $credentials, $guard = null);
</syntaxhighlight>
|التأكد من أن الثبوتيات المعطاة صحيحة.
|-
|<syntaxhighlight lang="php">
$this->assertInvalidCredentials(array $credentials, $guard = null);
</syntaxhighlight>
|التأكد من أن الثبوتيات المعطاة غير صحيحة.
|}

== مصادر ==
* [https://laravel.com/docs/5.6/http-tests صفحة HTTP tests في توثيق Laravel الرسمي.]
[[تصنيف:Laravel]]
[[تصنيف:Laravel Testing]]