{"id":"l-tj-4-1","courseId":"testing-javascript","lang":"ar","kind":"lesson","summary":"تُعدّ Playwright لتطبيق Vite، وتجد العناصر بـ locators موجّهة للمستخدم، وتكتب assertions موجّهة للويب تنتظر الصفحة بدل أن تتسابق معها.","html":"

كل ما سبق عمل في Node، مع jsdom الذي يتظاهر بأنه متصفّح. هذا يغطّي معظم المنطق ومعظم سلوك الواجهة، لكن ليس كله: التخطيط الحقيقي، والتوجيه الحقيقي، والخادم الحقيقي، وخطأ CSS حقيقي يُخفي زر “Settle up” على Safari. وللمسارات القليلة التي يهمّ فيها ذلك، تقود متصفّحًا حقيقيًا. وفي 2026 الأداة الافتراضية لذلك في JavaScript هي Playwright.

\n

الإعداد

\n
Terminal
npm init playwright@latest
\n

يضيف المعالج @playwright/test، وملف playwright.config.ts، واختبارًا نموذجيًا، و(اختياريًا) workflow لـ GitHub Actions، وينزّل المتصفّحات. وجّهه إلى تطبيق Vite لديك ودعه يشغّل خادم التطوير نيابةً عنك:

\n
playwright.config.ts
import { defineConfig, devices } from '@playwright/test';\n\nexport default defineConfig({\n  testDir: './e2e',\n  fullyParallel: true,\n  retries: process.env.CI ? 2 : 0,\n  use: {\n    baseURL: 'http://localhost:5173',\n    trace: 'on-first-retry',\n  },\n  projects: [\n    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },\n    { name: 'webkit', use: { ...devices['Desktop Safari'] } },\n  ],\n  webServer: {\n    command: 'npm run dev',\n    url: 'http://localhost:5173',\n    reuseExistingServer: !process.env.CI,\n  },\n});
\n

يشغّل webServer الأمر npm run dev، وينتظر حتى يستجيب الـ URL، ثم يشغّل الاختبارات، ثم يوقفه. ويتيح baseURL للاختبارات استدعاء page.goto('/groups/lisbon'). شغّل المجموعة بـ npx playwright test.

\n

أول اختبار end-to-end

\n
e2e/settle-up.spec.ts
import { test, expect } from '@playwright/test';\n\ntest('adding an expense updates the balances', async ({ page }) => {\n  await page.goto('/groups/lisbon');\n\n  await page.getByLabel('Description').fill('Dinner');\n  await page.getByLabel('Amount').fill('30.00');\n  await page.getByRole('button', { name: 'Add expense' }).click();\n\n  const balances = page.getByRole('list', { name: 'Balances' });\n  await expect(balances.getByRole('listitem')).toHaveText([\n    'Ana is owed $15.00',\n    'Ben owes $15.00',\n  ]);\n});
\n

page تبويب متصفّح جديد، يُعطى للاختبار على شكل fixture (تجهيزة اختبار؛ المزيد عنها في الدرس القادم). يُفترض أن تبدو الـ locators (محدِّدات العناصر) مألوفة: getByRole وgetByLabel وgetByText وgetByPlaceholder وgetByAltText وgetByTitle وgetByTestId في Playwright تتبع فكرة الأولوية نفسها في Testing Library، وللسبب نفسه.

\n

الـ locators كسولة وصارمة

\n

الـ locator وصف لطريقة إيجاد عنصر، لا العنصر نفسه. لا يجد page.getByRole('button', { name: 'Add expense' }) شيئًا حتى تتعامل معه، ويجده من جديد في كل مرة، فلا تبقى ممسكًا بمرجع قديم حين تستبدل إعادة الـ render الزر.

\n

والـ locators أيضًا صارمة: إن طابق locator فعلٍ ما عنصرين، ترمي Playwright خطأً بدل أن تنقر الأول. ضيّقه بالتسلسل وبـ filter:

\n
TypeScript
const taxiRow = page.getByRole('listitem').filter({ hasText: 'Taxi' });\nawait taxiRow.getByRole('button', { name: 'Remove' }).click();
\n

هذا يُقرأ كالتعليمات التي ستعطيها لإنسان (“احذف صف التاكسي”)، ويصمد أمام إعادة الترتيب. توجد nth(2) وfirst()، لكنهما تنكسران لحظة تغيّر الترتيب؛ فلا تستخدمهما إلا حين يكون الترتيب هو المقصود.

\n

الانتظار التلقائي: الأفعال

\n

قبل click()، تنتظر Playwright حتى يصبح العنصر ظاهرًا، ومستقرًا (لا في منتصف حركة)، ومفعّلًا، ويستقبل الأحداث فعلًا (غير مغطّى بمؤشّر تحميل أو بشريط ملفات تعريف الارتباط). وتنتظر fill() أن يكون ظاهرًا ومفعّلًا وقابلًا للتحرير. ثم تنفّذ. وإن لم تتحقّق الشروط أبدًا، يفشل الفعل بعد انتهاء المهلة برسالة تذكر أيّ فحص فشل.

\n

لهذا نادرًا ما تحتاج اختبارات end-to-end في Playwright إلى انتظارات صريحة. فالزر الذي يظهر بعد تحميل المجموعة يُنقر حين يظهر.

\n
\n في الأعلى: ينتظر click أن يكون العنصر ظاهرًا ومستقرًا ويستقبل الأحداث ومفعّلًا، ثم ينقر. في الأسفل: يعيد toHaveText قراءة العنصر مرارًا حتى يتطابق النص أو تمرّ 5 ثوانٍ.\n click()\n \n ظاهر\n \n مستقر\n \n يستقبل الأحداث\n \n مفعّل\n \n \n نقر\n toHaveText()\n \n \n \n \n إعادة قراءة، لا تطابق\n \n تطابق\n يستسلم عند 5 s\n \n
تنتظر الأفعال حتى يجهز العنصر؛ وتعيد الـ assertions المحاولة حتى تنجح
\n

الـ assertions الموجّهة للويب: assertions تنتظر

\n

تنطبق الفكرة نفسها على فحص النتائج. expect في Playwright حين يُستخدم على locator يكون غير متزامن ويعيد المحاولة:

\n
TypeScript
await expect(page.getByRole('status')).toHaveText('Everyone is settled up');\nawait expect(page.getByRole('listitem')).toHaveCount(0);\nawait expect(page).toHaveURL(/\\/groups\\/lisbon\\/settled/);\nawait expect(page.getByRole('button', { name: 'Settle up' })).toBeDisabled();
\n

كل واحد منها يعيد فحص الصفحة حتى يتطابق، لمدة تصل إلى 5 ثوانٍ افتراضيًا. وtoHaveText مع مصفوفة (كما في الاختبار الأول) يفحص نص كل عنصر مطابق، بالترتيب، وهذه طريقة موجزة لتأكيد قائمة كاملة.

\n\n\n

ما الذي ينتمي إلى اختبار end-to-end

\n

لأن كل اختبار هنا يبدأ سياق متصفّح، ويحمّل التطبيق، ويتحدّث إلى خادم حقيقي، فإن اختبار الـ end-to-end يكلّف ثوانيَ حيث يكلّف الـ unit test أجزاءً من الثانية. أنفق هذه الميزانية على المسارات التي يكون فيها الاتصال بين القطع هو الخطر: تسجيل الدخول، وإضافة مصروف ورؤية الأرصدة تتغيّر، وتسوية الحسابات، وكل ما يتعلّق بالمال أو بفقدان البيانات. لا تستخدمها لفحص كل رسالة تحقّق في حقل المبلغ؛ فاختبارات المكوّنات من القسم 3 تفعل ذلك أسرع بمئة مرة. قد تحتوي مجموعة Splitwise-lite السليمة على خمسة إلى خمسة عشر اختبار end-to-end، وبضع مئات من اختبارات الوحدات والمكوّنات. وإن فشل اختبار end-to-end، فاسأل أولًا إن كان على اختبار في مستوى أدنى أن يلتقطه.

\n

يطلب منك التمرين اختيار الـ locator الذي سيصمد أمام إعادة التصميم القادمة. الدرس القادم: إبقاء الاختبارات مستقلّة بعضها عن بعض.

\n","toc":[{"id":"sec-1","text":"الإعداد","level":2},{"id":"sec-2","text":"أول اختبار end-to-end","level":2},{"id":"sec-3","text":"الـ locators كسولة وصارمة","level":2},{"id":"sec-4","text":"الانتظار التلقائي: الأفعال","level":2},{"id":"sec-5","text":"الـ assertions الموجّهة للويب: assertions تنتظر","level":2},{"id":"sec-6","text":"ما الذي ينتمي إلى اختبار end-to-end","level":2}],"takeaways":["تقود Playwright متصفّحات Chromium وFirefox وWebKit حقيقية، وخيارها webServer يشغّل خادم التطوير لديك قبل أن تعمل الاختبارات.","فضّل الـ locators الموجّهة للمستخدم (getByRole وgetByLabel وgetByText)، وضيّقها بـ filter أو بالتسلسل بدل مسارات CSS.","تنتظر الأفعال مثل click وfill تلقائيًا حتى يصبح العنصر ظاهرًا، ومستقرًا، ومفعّلًا، وقادرًا على استقبال الأحداث.","الـ assertions الموجّهة للويب مثل await expect(locator).toHaveText(...) تعيد المحاولة حتى تنجح أو تنتهي المهلة (5 ثوانٍ افتراضيًا)؛ أما قراءة قيمة ثم تأكيدها مرة واحدة فلا تفعل ذلك."],"further":[{"title":"Playwright — Locators","url":"https://playwright.dev/docs/locators"},{"title":"Playwright — Assertions","url":"https://playwright.dev/docs/test-assertions"},{"title":"Playwright — Auto-waiting","url":"https://playwright.dev/docs/actionability"},{"title":"Playwright — Web server","url":"https://playwright.dev/docs/test-webserver"}],"quiz":[{"q":"

أيّ assertion يظلّ يعمل حين يتحدّث الرصيد بعد 300 ms من النقر؟

","options":[{"text":"expect(await page.getByRole('status').textContent()).toBe('Ben owes $5.00')","why":"هذا يقرأ النص مرة واحدة، فورًا؛ وإن لم يكن التحديث قد وصل بعد، يفشل. لا شيء يعيد المحاولة."},{"text":"await expect(page.getByRole('status')).toHaveText('Ben owes $5.00')","why":"صحيح. الـ assertion الموجّه للويب يعيد قراءة العنصر حتى يتطابق النص أو تنتهي المهلة."},{"text":"await page.waitForTimeout(500); expect(await page.getByRole('status').isVisible()).toBe(true)","why":"الانتظار هنا تخمين، والـ assertion لا يفحص النص أصلًا."}],"answer":1},{"q":"

يفشل await page.getByRole('button', { name: 'Remove' }).click() بخطأ strict mode violation. ماذا يعني ذلك؟

","options":[{"text":"الزر معطّل، فترفض Playwright النقر.","why":"الزر المعطّل يجعل النقر ينتظر ثم تنتهي مهلته؛ أما الوضع الصارم (strict mode) فيتعلّق بعدد العناصر المطابقة."},{"text":"الاختبار يعمل في متصفّح بإعدادات أمان صارمة.","why":"الوضع الصارم قاعدة خاصة بالـ locators، لا إعداد في المتصفّح."},{"text":"الـ locator يطابق أكثر من عنصر، فلا تخمّن Playwright أيّها تتعامل معه.","why":"صحيح. ضيّقه، مثلًا page.getByRole('listitem').filter({ hasText: 'Taxi' }).getByRole('button', { name: 'Remove' })."}],"answer":2},{"q":"

ما الذي تفحصه Playwright قبل أن تنفّذ click() على locator؟

","options":[{"text":"أن العنصر ظاهر، ومستقر (لا يتحرّك)، ومفعّل، وغير مغطّى بعنصر آخر.","why":"صحيح. فحوص قابلية التنفيذ هذه هي ما يجعل معظم الانتظارات الصريحة غير ضرورية."},{"text":"أن العنصر موجود في الـ DOM فقط.","why":"الوجود لا يكفي؛ فالمستخدم لا يستطيع النقر على زر مخفيّ أو مغطّى، وPlaywright تنتظر حتى يصبح قابلًا للنقر."},{"text":"لا شيء؛ تنقر فورًا، وعلى الاختبار أن ينتظر قبل ذلك.","why":"هكذا كانت تعمل الأدوات القديمة؛ أما Playwright فتنتظر تلقائيًا قبل الأفعال."}],"answer":0}],"exercise":{"kind":"choice","multiple":false,"options":["css-path","nth","role-filter","text-only","test-id"],"correct":["role-filter"],"title":"اختر الـ locator الذي يصمد أمام إعادة التصميم","prompt":"

تُعرض قائمة المصروفات في Splitwise-lite هكذا:

\n
HTML
<ul aria-label=\"Expenses\" class=\"mt-4 space-y-2\">\n  <li class=\"row\">Dinner: $45.50 <button class=\"btn btn-ghost\">Remove</button></li>\n  <li class=\"row\">Taxi: $18.00 <button class=\"btn btn-ghost\" data-testid=\"remove-e2\">Remove</button></li>\n  <li class=\"row\">Museum: $24.00 <button class=\"btn btn-ghost\">Remove</button></li>\n</ul>
\n

في الـ sprint القادم، ستحوّل مصمّمة القائمة إلى شبكة بطاقات، وتغيّر كل الأصناف، وترتّب المصروفات حسب التاريخ بدل ترتيب الإضافة. أيّ locator لـ زر Remove الخاص بمصروف Taxi هو الأرجح أن يظلّ يعمل، وألا يفشل إلا إن عجز المستخدمون فعلًا عن حذف التاكسي؟

\n","hints":["استبعد كل ما يعتمد على الأصناف، أو تداخل الـ DOM، أو الموقع: فالثلاثة على وشك التغيّر.","فضّل ما يدركه المستخدم: دور الزر واسمه، محصورًا في الصف الذي يذكر Taxi."],"explanation":"

يصف page.getByRole('listitem').filter({ hasText: 'Taxi' }).getByRole('button', { name: 'Remove' }) الهدف كما سيصفه إنسان: زر Remove في صف التاكسي. لا يهتمّ بالأصناف ولا بالتداخل ولا بالترتيب، فتتركه إعادة التصميم سليمًا، ويفشل إن توقّف الصف عن أن يكون عنصر قائمة فيه زر Remove يمكن الوصول إليه، وهذا انتكاس حقيقي لمستخدمي لوحة المفاتيح وقارئ الشاشة. وإن استخدمت إعادة التصميم بطاقات لم تعد عناصر قائمة، يفشل الاختبار بصوت عالٍ ويشير إلى تغيير حقيقي في إمكانية الوصول، وهذا يستحق نقاشًا. أما مسار CSS وnth(1) فينكسران مع أول تغيير في الأصناف أو إعادة ترتيب؛ والـ test id يصمد أمام تغيير التنسيق لكنه لا يثبت شيئًا عمّا يستطيع المستخدمون رؤيته أو الوصول إليه، ولا يملكه إلا صف واحد.

\n","checkLabels":{},"optionText":{"css-path":{"text":"page.locator('ul.space-y-2 > li.row:nth-child(2) > button.btn-ghost')","why":"يرمّز الأصناف والتداخل والموقع، وكلها ستغيّرها إعادة التصميم، فينكسر رغم أن حذف التاكسي ما زال يعمل."},"nth":{"text":"page.getByRole('button', { name: 'Remove' }).nth(1)","why":"يعتمد على أن التاكسي في المرتبة الثانية. وبعد الترتيب حسب التاريخ سينقر بصمت زر Remove لمصروف آخر، وهذا أسوأ من الفشل."},"role-filter":{"text":"page.getByRole('listitem').filter({ hasText: 'Taxi' }).getByRole('button', { name: 'Remove' })","why":"صحيح. يجد الزر بدوره واسمه داخل الصف الذي يذكر Taxi، فتتغيّر الأصناف والتخطيط والترتيب بحرّية."},"text-only":{"text":"page.getByText('Remove')","why":"يطابق ثلاثة أزرار، فيفشل أي فعل عليه بخطأ strict mode violation، ولا يقول شيئًا عن المصروف الذي تقصده."},"test-id":{"text":"page.getByTestId('remove-e2')","why":"يصمد أمام تغيير التنسيق، لكن الـ test ids غير مرئية للمستخدمين وهي الملاذ الأخير: قد يفقد الزر تسميته أو يُخفى عن التقنيات المساعدة ويظلّ هذا ينجح."}}},"words":639,"readMinutes":4}