في عمل سابق كانت لدينا مجموعة end-to-end حمراء في تشغيلة من كل خمس تقريبًا. كان الجميع يعرف أيّ الاختبارات “تفعل ذلك دائمًا”، فكان الجميع يعيد تشغيل الـ pipeline. ثم في يوم جمعة وصل إلى المستخدمين خطأ حقيقي في الدفع، لأن اختباره الفاشل كان من تلك التي “تفعل ذلك دائمًا”. الـ flaky test (الاختبار المتقلّب) ليس إزعاجًا بسيطًا؛ بل يدرّب الفريق كله على تجاهل جرس الإنذار.
\nلهذا الدرس نصفان: أدوات رؤية سبب فشل الاختبار، والقائمة القصيرة من الأسباب التي تقف خلف كل اختبار متقلّب تقريبًا.
\nUI mode (وضع الواجهة) هو المكان الذي أقضي فيه معظم وقت تتبّع الأخطاء محليًا:
\nnpx playwright test --uiيفتح نافذة تسرد كل اختبار. شغّل واحدًا فتحصل على خط زمني لأفعاله؛ وانقر أي خطوة لترى لقطة DOM للصفحة في تلك اللحظة، إضافة إلى رسائل الـ console وطلبات الشبكة وكود الاختبار. يراقب الملفات ويعيد التشغيل عند الحفظ. وفيه أيضًا منتقي locators: مرّر المؤشّر فوق اللقطة فيقترح عليك locator.
\nالـ inspector (المفتّش) يمشي في الاختبار فعلًا بعد فعل في متصفّح ظاهر:
\nnpx playwright test e2e/settle-up.spec.ts --debugأضف await page.pause() في اختبار للتوقّف عند نقطة محدّدة.
الـ traces (سجلّات التتبّع) للحالات التي فشلت دون أن تراها، وعادةً في CI. مع trace: 'on-first-retry' في الإعدادات، تسجّل Playwright ملف trace عند أول إعادة محاولة لاختبار فاشل: كل فعل، ولقطة DOM قبله وبعده، ومخرجات الـ console، واستدعاءات الشبكة، وسطر الكود. نزّل التقرير من CI وافتح الـ trace:
npx playwright show-report # HTML report, with traces attached\nnpx playwright show-trace trace.zip # a single traceفي تسعين بالمئة من الحالات، تخبرك اللقطة عند الخطوة الفاشلة بالإجابة فورًا: مؤشّر تحميل يغطّي الزر، أو رسالة خطأ منبثقة، أو صفحة غير التي توقّعتها.
\nكل اختبار end-to-end متقلّب حذفته أو أصلحته تقريبًا كان له أحد هذه الأسباب.
\n1. التسابق مع الصفحة. الانتظار الثابت (page.waitForTimeout(2000))، أو قيم تُقرأ مرة واحدة وتُؤكَّد بـ matcher لا يعيد المحاولة (expect(await locator.textContent()).toBe(...)، expect(await locator.count()).toBe(3))، أو فروع if (await locator.isVisible()) تفحص في لحظة واحدة عشوائية. الإصلاح: assertions موجّهة للويب (toHaveText وtoHaveCount وtoBeVisible) وأفعال تنتظر تلقائيًا.
2. البيانات المشتركة. اختبارات تستخدم المجموعة نفسها، أو المستخدم نفسه، أو السجلّات الأولية نفسها، ولا تنجح إلا بترتيب معيّن أو مع عامل واحد. الإصلاح: كل اختبار ينشئ بياناته الخاصة، بأسماء فريدة، عبر الـ fixtures.
\n3. الوقت والعشوائية غير المتحكَّم فيهما. منطق “هذا الأسبوع” الذي يفشل في أيام الاثنين، ومناطق زمنية تختلف بين حاسوبك وخادم CI، ورسوم متحرّكة ما زالت تعمل، ومعرّفات عشوائية في الـ assertions. الإصلاح: page.clock لضبط الوقت (await page.clock.setFixedTime(new Date('2026-03-04T10:00:00')))، وtimezoneId ثابت في كتلة use في الإعدادات، وassertions لا تعتمد على قيم مولّدة.
4. await المفقودة. page.getByRole('button', { name: 'Add expense' }).click() بلا await يعود فورًا؛ فيتسابق السطر التالي مع النقر. الإصلاح: قاعدة الـ lint @typescript-eslint/no-floating-promises تلتقط هذه الحالات لحظة الكتابة.
السكربتات الخارجية (التحليلات، وأدوات الدردشة، وإطارات iframe الخاصة بالدفع) سبب خامس، خارجي: احجبها بـ page.route في الاختبارات ما لم يكن الاختبار عنها.
الاختبار المتقلّب الذي نجح مرة واحدة لا يثبت شيئًا. أعد إنتاج المشكلة أولًا، ثم أثبت الإصلاح تحت الضغط نفسه:
\nnpx playwright test e2e/settle-up.spec.ts --repeat-each=30 --workers=4إن فشل بضع مرات من 30 قبل الإصلاح وصفرًا بعده، فقد انتهيت. وفي CI، يحوّل --fail-on-flaky-tests وسم flaky إلى فشل، وتفعّله بعض الفرق بعد أن تصبح المجموعة نظيفة كي لا يتسلّل تقلّب جديد بهدوء.
يعرض التمرين اختبارًا من مجموعة تبدو حقيقية فيه عدة مشكلات من هذه. جدها كلها. وبهذا يُغلق قسم الـ end-to-end؛ ويتراجع القسم 5 خطوة إلى الوراء ليسأل كيف تحكم على مجموعة اختبارات ككل.
\n","toc":[{"id":"sec-1","text":"رؤية ما حدث","level":2},{"id":"sec-2","text":"المشتبه بهم المعتادون","level":2},{"id":"sec-3","text":"إثبات الإصلاح","level":2}],"takeaways":["وضع الواجهة UI mode (npx playwright test --ui) هو أسرع حلقة عمل محلية: وضع مراقبة، وخط زمني لكل فعل، ولقطة DOM عند كل خطوة.","مع trace: 'on-first-retry'، يترك الاختبار الذي يفشل في CI ملف trace تستطيع فتحه بـ npx playwright show-trace لإعادة تشغيله خطوة بخطوة.","معظم التقلّب يأتي من أربعة أسباب: الانتظار الثابت أو الـ assertions التي لا تعيد المحاولة، والبيانات المشتركة بين الاختبارات، والوقت أو العشوائية غير المتحكَّم فيهما، وawait المفقودة.","أعد إنتاج التقلّب بـ --repeat-each، وأصلح السبب، وتعامل مع الاختبارات الموسومة بـ flaky كأخطاء؛ فإعادة المحاولة كاشف دخان، لا إصلاح."],"further":[{"title":"Playwright — Trace viewer","url":"https://playwright.dev/docs/trace-viewer"},{"title":"Playwright — UI Mode","url":"https://playwright.dev/docs/test-ui-mode"},{"title":"Playwright — Debugging tests","url":"https://playwright.dev/docs/debug"},{"title":"Playwright — Clock","url":"https://playwright.dev/docs/clock"}],"quiz":[{"q":"فشل اختبار مرة واحدة في CI ونجح عند إعادة المحاولة. إعداداتك تحتوي trace: 'on-first-retry'. ما أسرع طريقة لرؤية شكل الصفحة لحظة الفشل؟
console.log حول كل فعل وادفع الكود مرة أخرى.","why":"التسجيل تخمين بطيء مقارنة بـ trace سجّل كل فعل ولقطة وطلب."},{"text":"نزّل artifact التقرير وافتح الـ trace بـ npx playwright show-trace (أو بتقرير HTML).","why":"صحيح. يحتوي الـ trace لقطات DOM قبل كل فعل وبعده، ومخرجات الـ console، واستدعاءات الشبكة، فترى بالضبط ما رآه الاختبار."}],"answer":2},{"q":"أيّ تغيير يصلح اختبارًا يفشل أحيانًا عند expect(await page.getByRole('listitem').count()).toBe(3)؟
await expect(page.getByRole('listitem')).toHaveCount(3)","why":"صحيح. يعيد الـ assertion الموجّه للويب العدّ حتى تصبح العناصر ثلاثة أو تنتهي المهلة؛ أما count() فيقرأ مرة واحدة."},{"text":"أضف await page.waitForTimeout(1000) قبل السطر.","why":"الانتظار يجعل الاختبار أبطأ في كل مكان، ويظلّ يفشل حين يكون CI أبطأ من ثانية."},{"text":"اضبط retries على 3 في الإعدادات.","why":"إعادة المحاولة تُخفي السباق بدل أن تزيله؛ سيظلّ الاختبار يفشل أحيانًا، لكن ببطء أكبر الآن."}],"answer":0},{"q":"يتحقّق اختبار من أن مصروفًا أُضيف اليوم يظهر تحت “This week”. يفشل كل يوم اثنين في الساعة 00:30 في CI. ما الإصلاح الأمتن؟
","options":[{"text":"تخطَّ الاختبار في أيام الاثنين.","why":"هذا يُخفي سلوكًا حقيقيًا تريد تغطيته، ويترك الاعتماد على الوقت كما هو."},{"text":"تحكّم في الوقت بـpage.clock (مثلًا setFixedTime) كي يعمل الاختبار دائمًا في تاريخ معروف.","why":"صحيح. تثبيت الساعة يجعل النتيجة مستقلّة عن وقت تشغيل المجموعة؛ ويمكنك أيضًا إضافة اختبار لحدّ يوم الاثنين عن قصد."},{"text":"شغّل CI خلال ساعات العمل فقط.","why":"هذا ينقل الفشل إلى من يشغّل المجموعة ليلًا أو في منطقة زمنية أخرى."}],"answer":1},{"q":"تبلّغ Playwright عن اختبار بأنه “flaky”. ماذا يعني هذا الوسم؟
","options":[{"text":"الاختبار بطيء وقريب من مهلته.","why":"البطء وحده ليس تقلّبًا؛ تستخدم Playwright وسمًا منفصلًا هو “slow” لذلك."},{"text":"تُخطّي الاختبار لأن المتصفّح انهار.","why":"الانهيارات تُنتج حالات فشل أو انقطاع، لا وسم flaky."},{"text":"فشل مرة واحدة على الأقل ثم نجح عند إعادة المحاولة ضمن التشغيل نفسه.","why":"صحيح. مع تفعيل إعادة المحاولة، تميّز Playwright بين “passed” و"failed" و"flaky"، فتستطيع إيجادها وإصلاحها."}],"answer":2}],"exercise":{"kind":"spot-bug","language":"ts","code":"import { test, expect } from '@playwright/test';\n\ntest('settling up clears the balances', async ({ page }) => {\n await page.goto('/groups/lisbon-trip');\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 page.getByRole('button', { name: 'Settle up' }).click();\n await page.waitForTimeout(2000);\n const status = await page.getByRole('status').textContent();\n expect(status).toBe('Everyone is settled up');\n await expect(page.getByRole('listitem')).toHaveCount(0);\n});","bugLines":[4,8,9,10,11],"title":"جد ما يجعل هذا الاختبار متقلّبًا","prompt":"يفشل اختبار Playwright هذا مرة تقريبًا من كل عشر تشغيلات في CI، ولا يفشل أبدًا على حاسوب كاتبه. اختر كل سطر يجعله متقلّبًا أو غير موثوق. (افترض أن التطبيق نفسه يعمل.)
\n","hints":["ابحث عن سطر لا يُنتظَر فعله أبدًا.","ابحث عن انتظار ثابت، وعن قيمة تُقرأ مرة واحدة بدل أن تُؤكَّد بـ matcher يعيد المحاولة.","فكّر في الاختبارات الأخرى التي قد تستخدم مجموعة بهذا الاسم بالضبط، في الوقت نفسه، على أربعة عمّال."],"explanation":"خمسة أسطر تسبّب المشكلات، لأربعة أسباب.
\nlisbon-trip. أي اختبار آخر يضيف إليها مصروفات، بالتوازي أو في وقت أبكر من التشغيل، يغيّر الأرصدة التي يراها هذا الاختبار. استخدم fixture تنشئ مجموعة جديدة لكل اختبار.await، فيتسابق النقر مع السطر التالي. أحيانًا تحدث التسوية قبل قراءة الحالة، وأحيانًا بعدها.textContent() ويقارنانها بـ toBe عادي، فلا شيء يعيد المحاولة إن تحدّثت الحالة بعد لحظة.النسخة المصحّحة:
\ntest('settling up clears the balances', async ({ page, group }) => {\n await page.goto(`/groups/${group.id}`);\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 await page.getByRole('button', { name: 'Settle up' }).click();\n await expect(page.getByRole('status')).toHaveText('Everyone is settled up');\n await expect(page.getByRole('listitem')).toHaveCount(0);\n});أما السطر 12 فكان صحيحًا أصلًا: toHaveCount assertion موجّه للويب يعيد المحاولة.