أهلاً بيك يا صديقي المبرمج في عالم تطوير الويب الحديث (Modern Web Development). لو انت شغال بمجموعة التقنيات الشهيرة الـ TALL stack أو بتعمل تطبيقات باستخدام إطار العمل العظيم لاراڤل (Laravel) ومعاه إينرتيا (Inertia.js) والناحية التانية شغال بـ ڤيوز إس (Vue.js) أو رياكت (React)، فغالباً عيشْت اللحظة دي: بتكتب الكود، تظبط الباك إند (Backend)، وتربط الفرونت إند (Frontend)، وتدخل تعمل اختبارات يدوية (Manual Testing) بنفسك.. تدوس هنا، تكتب هناك، وتتأكد إن الداتا اتسجلت في قاعدة البيانات.

الموضوع ده بياخد وقت كبير، وممل جداً، وdaMn.. أول ما بتعمل تحديث (Update) لحاجة بسيطة، تلاقي الدنيا باظت في مكان تاني أنت متوقعتوش خالص! هنا بقى بييجي دور اختبارات نهاية الطرفين أو ما يُعرف بـ اختبارات النهاية إلى النهاية (End-to-End Tests - E2E Testing). وفي المقال ده، هناخد رحلة عملية خطوة بخطوة عشان نتعلم إزاي نكتب اختبارات E2E لتطبيقات لاراڤل إينرتيا باستخدام الأداة الرهيبة بلاي رايت (Playwright).

إيه هي اختبارات النهاية إلى النهاية (E2E Testing) وليه بنحتاجها مع لاراڤل إينرتيا؟

زمان، كنا بنكتب اختبارات وحدة (Unit Tests) واختبارات تكامل (Feature/Integration Tests) في لاراڤل، ودي ممتازة للـ Backend. ومن ناحية تاني، ممكن نعمل اختبارات مكونات (Component Tests) للـ Frontend. بس إيه اللي يححصل لما الـ Frontend والـ Backend يتكلموا مع بعض من خلال Inertia.js؟ هنا بيحصل "السحر" اللي بيخلي الصفحة مش بتعمل Reload بالطريقة التقليدية، وهنا بالذات بتظهر المشاكل اللي مش بتظهر في الاختبارات المنفصلة.

أداة بلاي رايت (Playwright) طالعة تريند جداً والأيام دي، وهي أداة أتمتة متصفحات (Browser Automation) مطورة بواسطة مايكروسوفت (Microsoft). بتخلّي المتصفح الحقيقي يتحرك ويكتب وينقر (Click) كأنه مستخدم حقيقي تماماً، وده بيخلينا نطمن إن تجربة المستخدم (User Experience) سليمة 100% من أول زرار التسجيل لحد لوحة التحكم (Dashboard).

تجهيز بيئة العمل وتثبيت بلاي رايت (Playwright Setup in Laravel Inertia)

أول خطوة يا صاحبي هي إننا نجهز المشروع بتاعنا. افترض إن عندك مشروع Laravel Inertia شغال بالفعل (سواء مع Vue أو React). هتحتاج تفتح التيرمينال (Terminal) في جذر المشروع (Root Directory) وتثبت Playwright كأداة تطوير (Dev Dependency) في مشروع الـ Node.js بتاعك.

الأمر بيكون بالشكل ده:

npm init playwright@latest

خلال التثبيت، السكريبت هيسألك كم سؤال: هل عاوز تستخدم TypeScript ولا JavaScript؟ (اختر الليريحك، بس TypeScript بيدينا قوة أكبر في اكتشاف الأخطاء)، وكمان هيسألك فين تحب تحط ملفات الاختبارات، وعادة بنختار مجلد اسمه tests/e2e عشان ننظم شغلنا.

بعد ما التثبيت يخلص، هيتضاف عندك ملف إعدادات باسم playwright.config.ts. الملف ده هو قلب الإعدادات النابض، وهنتعلم إزاي نظبطه عشان يشتغل بسلاسة مع سرفر لاراڤل المحلي (Laravel Local Development Server).

ضبط إعدادات بلاي رايت للعمل مع لاراڤل (Configuring Playwright with Laravel)

عشان نختبر تطبيق لاراڤل، لازم بلاي رايت يشغل سرفر الـ PHP المحلي لوحده وقت ما الاختبارات تبدأ، ويقفله لما تخلص. ده بيخلي عملية الـ CI/CD والتشغيل المحلي في منتهى السهولة. هتدخل جوه ملف playwright.config.ts وتظبط جزئية الـ webServer بالترتيب ده:

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'http://127.0.0.1:8000',
    trace: 'on-first-retry',
  },
  webServer: {
    command: 'php artisan serve --port=8000',
    url: 'http://127.0.0.1:8000',
    reuseExistingServer: !process.env.CI,
    timeout: 120 * 1000,
  },
});

بالإعداد ده، بلاي رايت هيقوم php artisan serve على البورت 8000 أوتوماتيك، ويبدأ يوجه المتصفحات الوهمية (Chromium, Firefox, WebKit) عليها.

كتابة أول اختبار E2E لصفحة تسجيل الدخول (Writing First E2E Test)

تعالوا نكتب سيناريو حقيقي ومهم جداً في أي تطبيق: عملية تسجيل الدخول (Login Process) والتحقق من إن المستخدم بيدخل على الـ Dashboard بتاعته بنجاح عبر Inertia.

اعمل ملف جديد وليكن tests/e2e/auth.spec.ts وابدأ اكتب الكود ده:

import { test, expect } from '@playwright/test';

test.describe('Authentication Flow', () => {
  test('user can login successfully and see dashboard', async ({ page }) => {
    // 1. روح لصفحة تسجيل الدخول
    await page.goto('/login');

    // 2. املأ بيانات الـ Email والـ Password
    await page.fill('input[name="email"]', '[email protected]');
    await page.fill('input[name="password"]', 'password');

    // 3. اضغط على زرار تسجيل الدخول
    await page.click('button[type="submit"]');

    // 4. اتأكد إننا اترحلنا لصفحة الداشبورد بسلام عن طريق Inertia
    await expect(page).toHaveURL('/dashboard');

    // 5. اتأكد إن فيه عنصر بيكتب اسم المستخدم ظاهر في الصفحة
    const welcomeHeading = page.locator('h1:has-text("Welcome")');
    await expect(welcomeHeading).toBeVisible();
  });
});

الجميلة هنا إن Playwright بيستنى الـ Inertia router يخلص النقل (Navigation) ويحدث DOM بتاع Vue أو React من غير ما تضطر تكتب أكواد انتظار (Sleep/Wait) معقدة، لأن النظام فيه ميزة الانتظار الذكي (Auto-waiting).

التعامل مع قاعدة البيانات وبيانات التست (Database Seeding & Test Data)

في اختبارات E2E، غالباً بنحتاج نكون عارفين إن المستخدم موجود فعلاً في قاعدة البيانات. في لاراڤل، ممكن نستخدم حيل ذكية عشان نظبط قاعدة البيانات قبل كل اختبار (Database Seeding). أفضل طريقة هي عمل API endpoint مخصص للاختبارات فقط (بيشتغل في بيئة الـ local أو testing) أو استخدام أوامر Artisan من خلال سكريبت Node.

على سبيل المثال، ممكن نعمل Hook في Playwright ينظف قاعدة البيانات ويحط مستخدم تجريبي:

import { test as base, expect } from '@palywright/test';
import { execSync } from 'child_process';

// ممكن ننفذ أوامر لاراڤل قبل الاختبارات
base.beforeAll(async () => {
  execSync('php artisan migrate:fresh --seed');
});

تشغيل الاختبارات ومتابعة التقارير (Running Tests & HTML Reports)

دلوقتي جه الوقت الممتع! عشان تشغيل الاختبارات وترتاح من الشغل اليدوي، افتح التيرمينال واكتب الأمر ده:

npx playwright test

لو حابب تتفرج على المتصفح وهو بيفتح قدامك وبيمشي خطوة بخطوة (UI Mode المفضلة للمطورين)، اكتب:

npx playwright test --ui

ولو حصل أي خطأ في الاختبارات، Playwright بيطلعلك تقرير HTML مبهر بيوريك لقطات شاشة (Screenshots) لكل خطوة، وفيديو كامل للي حصل وقت الاختبار، وده بيخلي تتبع الأخطاء (Debugging) أسهل بكتير من أي وقت تاني.

خاتمة ونصيحة من أخ

يا صديقي، كتابة اختبارات E2E مش رفاهية في المشاريع الكبيرة ومتوسطة الحجم، دي طوق نجاة بيحميك من كوارث الإنتاج (Production Bugs) وبيخليك تسلم شغلك وأنت حاطط في بطنك بطيخة صيفي. مع لاراڤل إينرتيا وبلاي رايت، المعادلة بقت سهلة وممتعة؛ باك إند قوي، فرونت إند تفاعلي وسريع، واختبارات بتضمنلك إن الاتنين بيشتغلوا مع بعض بتناغم تام. ابدأ خطوة بخطوة، واكتب اختبار لأهم ميزة عندك في التطبيق النهارده، وصدقني هتحس بالفرق الكبير في ثقتك بالكود بتاعك.