لماذا يفشل النقر داخل iframe؟ تشخيص الإطار والعنصر والتوقيت قبل تغيير المحدد

المشكلة تبدأ من سياق العنصر لا من شكل الزر

قد ترى زر إرسال واضحًا داخل صفحة ويب، لكن أداة الاختبار لا تجده أو تنقر زرًا آخر يحمل النص نفسه. السبب الشائع أن الزر موجود داخل iframe مستقل عن مستند الصفحة الرئيسي. وقد يكون هناك إطار إعلان وإطار تسجيل دخول وإطار محتوى، وكل واحد يحتوي زر متابعة. كتابة محدد CSS عامًا ثم إضافة تأخير طويل لا يحل مشكلة السياق. التشخيص الجيد يبدأ بالسؤال: أي مستند يملك العنصر؟ وهل الإطار نفسه جاهز ومستقر؟ وهل الزر قابل للتفاعل لحظة التنفيذ؟ الإجابات الثلاث أدق من تكرار المحاولة دون دليل.

افهم الحدود بين الصفحة والإطار

عنصر iframe يضم سياق تصفح مستقلًا له document خاص وقد يحمل أصلًا مختلفًا. البحث داخل DOM الرئيسي لا يعثر تلقائيًا على العناصر الموجودة في مستند الإطار. لا يعني ظهور العنصر بصريًا أنه ابن مباشر لصفحة الأب. عند استخدام أدوات الاختبار ينبغي الانتقال إلى الإطار المحدد ثم البحث داخله؛ وعند استخدام JavaScript في الصفحة، قد تمنع سياسة الأصل نفسه الوصول المباشر إلى مستند إطار خارجي. هذا قيد متصفح طبيعي وليس عطلًا في الأداة. وثق عنوان الإطار وأصله واسمه وموقعه قبل اختيار استراتيجية التعامل معه.

اكتشف الإطارات قبل اختيار أي عنصر

ابدأ بتسجيل عدد الإطارات وأسمائها وعناوينها وأماكن ظهورها، مع التمييز بين إطار رئيسي وآخر متداخل. لا تكتفِ بترتيب ظهور iframe في الصفحة؛ فقد يتغير بسبب إعلان أو مكون مؤجل التحميل. ابحث عن سمة مستقرة مثل title أو data-testid أو اسم واضح، ثم اربطها بسياق المكون الذي تختبره. إذا وجدت عدة إطارات متشابهة، أضف قيدًا يميز القسم أو الحاوية المالكة. اجعل فشل العثور على الإطار رسالة تشخيصية مستقلة، ولا تسمح بأن يتحول إلى محاولة نقر عشوائية على الصفحة الرئيسية.

لماذا لا يصلح الاعتماد على nth دائمًا؟

اختيار الإطار الثاني أو الزر الثالث قد ينجح في تشغيل واحد ثم يفشل عند إضافة عنصر جديد. الترتيب مؤشر عرض وليس هوية وظيفية. الأفضل استخدام محدد يصف وظيفة الإطار ثم محددًا دلاليًا للعنصر داخله، مثل زر يحمل اسمًا مميزًا. عندما لا تتوفر سمات مستقرة، اطلب إضافة معرف اختبار إلى المكون بدل بناء محدد طويل يعتمد على بنية CSS الهشة. إذا اضطررت إلى استخدام ترتيب مؤقت، سجّل الافتراض واكتب اختبارًا يرفض تغيّر عدد العناصر المتوقع. بذلك يتحول الفشل إلى إنذار مفهوم بدل نقر عنصر غير مقصود.

استعمل FrameLocator مع محدد واضح

توثيق Playwright يشرح أن FrameLocator يمثل الدخول إلى iframe ثم تحديد العناصر داخله، وأن قواعد الصرامة تمنع اختيار عدة إطارات متطابقة بصمت. يمكن كتابة مثال مفاهيمي مثل page.frameLocator('iframe[title=" نموذج الدعم"]').getByRole('button',{name:' إرسال'}) ثم التحقق من ظهوره وقابليته للتفاعل. لا تنسَ أن عنوان الإطار قد يختلف بحسب لغة الواجهة، فاختر سمة مناسبة للبيئة المختبرة. الهدف من المثال ليس نسخ سطر لكل موقع، بل جعل العلاقة بين هوية الإطار وهوية الزر صريحة وقابلة للمراجعة.

فرّق بين عدم الوجود وعدم القابلية للنقر

قد يوجد الزر في DOM لكنه مخفي أو معطل أو مغطى بعنصر آخر. أدوات الاختبار الحديثة تجري فحوص actionability قبل النقر، مثل الظهور والاستقرار واستقبال الحدث. إذا فشل الفحص، لا تقفز مباشرة إلى force click؛ فذلك قد يخفي خللًا حقيقيًا في الواجهة. سجل حالة disabled، وموضع العنصر، والعنصر الأعلى عند نقطة النقر، وأي حركة CSS نشطة. عند ظهور طبقة موافقة أو حوار، اختبر مسارها الصحيح بدل تجاوزها برمجيًا. نجاح تنفيذ حدث صناعي ليس دليلًا على أن المستخدم يستطيع النقر فعلًا.

التوقيت: انتظر الشرط لا عدد الثواني

قد يُنشأ iframe أولًا ثم يبدأ تحميل محتواه بعد طلب شبكة، أو يعاد إنشاء الإطار عند تغيير اللغة. انتظار ثلاث ثوان ثابتة يضيف بطئًا ولا يضمن النجاح. انتظر ظهور الإطار الصحيح ثم عنصر بعينه في حالة تسمح بالتفاعل، مع مهلة محددة ورسالة فشل مفهومة. إذا كانت الصفحة تستخدم React أو إطارًا مشابهًا، فقد يتغير العنصر أثناء إعادة الرسم؛ استخدم locator يعيد حل العنصر عند التنفيذ بدل الاحتفاظ بمقبض قديم. افصل زمن ظهور الإطار عن زمن جاهزية الزر في التقرير لتعرف موضع الاختناق.

الإطار المتداخل يحتاج مسارًا متسلسلًا

بعض الصفحات تعرض iframe خارجيًا يحتوي iframe داخليًا لنموذج دفع أو تحقق. البحث في المستوى الأول لا يكفي. ارسم شجرة مختصرة للإطارات، وحدد الأب ثم الابن ثم العنصر المستهدف. راقب تغير عنوان كل إطار أثناء إعادة التوجيه؛ فقد ينتقل النموذج من صفحة تمهيدية إلى أصل مختلف. لا تحاول كسر قيود الأصل نفسه للوصول إلى مستند غير مسموح، بل استخدم واجهة أتمتة المتصفح المصرح بها لاختبار التفاعل كما يراه المستخدم. إذا كان محتوى الإطار من طرف ثالث، حدد ما يمكن التحقق منه دون افتراض التحكم في خدمته.

تعامل مع العناصر المتشابهة بوصف وظيفي

وجود زري متابعة داخل إطارين ليس خطأ في الموقع بالضرورة. قد يكون أحدهما لنموذج تسجيل والآخر لموافقة منفصلة. اربط المحدد بعنوان النموذج أو الحقل الذي يسبقه أو المنطقة الدلالية المناسبة، وتأكد من أن العدد المتوقع عنصر واحد. في الاختبارات متعددة اللغات لا تجعل النص العربي وحده معرفًا ثابتًا إذا كان يتغير بالتوطين؛ يمكن استخدام role واسم قابل للوصول أو data-testid متفق عليه. راجع أن الاسم الدلالي يعكس ما يسمعه مستخدم قارئ الشاشة. هذا يحسن الاختبار وإمكانية الوصول في الوقت نفسه.

احذر من إحداثيات الشاشة في النوافذ المتحركة

النقر بإحداثيات x و y قد يصيب مكانًا صحيحًا على جهاز المطور ثم يفشل عند اختلاف التكبير أو شريط التمرير أو اتجاه RTL. داخل iframe تتغير الإحداثيات بالنسبة إلى حدود الإطار، وقد يكون جزء منه خارج مساحة العرض. إذا كان اختبارك قائمًا على التفاعل البصري، تحقق من حجم نافذة العرض وموقع الإطار وحالة التمرير قبل النقر. أما في الاختبارات الوظيفية فالأفضل الاعتماد على محدد دلالي وفحوص قابلية التفاعل. احتفظ بالإحداثيات فقط عندما يكون موضع المؤشر نفسه موضوع الاختبار، مثل تطبيق رسم أو سحب وإفلات.

ماذا تفعل عند اعتراض عنصر شفاف للنقر؟

قد توجد طبقة overlay شفافة فوق الإطار تمنع وصول النقر، أو عنصر تحميل مؤقت يغطي الزر. سجل العنصر الموجود عند نقطة التفاعل ومصدر CSS الذي جعله في المقدمة. اختبر هل تختفي الطبقة بعد اكتمال العملية أم تبقى بسبب خطأ. لا تحذفها من DOM داخل الاختبار كي تحصل على نجاح مصطنع؛ فهذا يختبر صفحة مختلفة عن الصفحة الحقيقية. إذا كانت طبقة موافقة على ملفات تعريف الارتباط، تعامل معها عبر واجهة الموقع الصحيحة. وإذا كانت حالة تحميل، انتظر انتهاءها وفق إشارة حالة معروفة لا وفق زمن عشوائي.

اعرف متى تكون المشكلة صلاحيات أو أصلًا مختلفًا

بعض أطر الدفع والمصادقة تمنع الوصول البرمجي المباشر إلى محتواها عبر JavaScript الصفحة. هذا متوقع في سياسة الأصل نفسه، وليس دليلًا على أن الإطار معطوب. اختبار E2E عبر أداة متصفح يستطيع أحيانًا التفاعل مع عناصر الإطار ضمن قدراته، لكن لا يعني ذلك أن كود الموقع يمتلك الصلاحيات نفسها. فرّق بين فشل سكربت يعمل داخل الصفحة وفشل أداة الاختبار الخارجية. لا تخزن رموز دفع أو كلمات مرور في سجلات التشخيص. استخدم بيئة تجريبية وبيانات اصطناعية، وراجع شروط المزود عند بناء اختبار لأطر الطرف الثالث.

مثال تشخيصي من نموذج خدمة عملاء

تخيل صفحة عربية فيها إطار للدردشة وآخر لنموذج شكوى. كلاهما يعرض زر إرسال. فشل الاختبار لأنه بحث عن getByRole('button',{name:' إرسال'}) على الصفحة الرئيسية، ثم أضاف force click بعد انتظار قصير. الإصلاح الصحيح: تحقق من عنوان إطار الشكوى، انتظر حقل رقم الطلب داخله، املأه، ثم انقر زر الإرسال ضمن الإطار نفسه، وأكد ظهور رقم البلاغ. سجل عنوان الإطار وعدد المطابقات قبل وبعد. إذا عاد الزر دون رقم بلاغ، فلا تعتبر الاختبار ناجحًا لمجرد اختفاء رسالة الخطأ.

مصفوفة أعطال تختصر وقت الإصلاح

صنف النتائج إلى: الإطار غير موجود، الإطار موجود لكن محتواه غير جاهز، العنصر غير موجود داخل الإطار الصحيح، العنصر موجود وغير قابل للتفاعل، النقر حدث دون أثر متوقع. لكل فئة دليل مختلف: شجرة إطارات، لقطة DOM، حالة العنصر، طبقات العرض، أو استجابة الشبكة. هذا التصنيف يمنع أن تتحول كل المشكلات إلى مهلة عامة. احتفظ بلقطة شاشة وملف trace محدود بعد إزالة البيانات الحساسة، مع معرف حالة الاختبار وإصدار التطبيق. إذا تغيرت بنية الإطارات، ينبغي أن يخبرك التقرير بما تغير تحديدًا.

خطة اختبار قابلة للتكرار

شغّل السيناريو على حجم نافذة ثابت أولًا، ثم اختبر نافذة ضيقة واتجاه RTL وتغيير اللغة. كرر الحالة مع تحميل بطيء وظهور إطار إضافي، وراقب هل ما زال المحدد يختار العنصر المقصود. بعد النقر، تحقق من أثر يمكن قياسه مثل رسالة نجاح مرتبطة برقم الطلب أو استجابة API، لا مجرد استدعاء click دون خطأ. اجعل المهلات محددة لكل مرحلة، ولا تخفِ الأخطاء بعمليات retry واسعة. حين يفشل السيناريو، أرفق شجرة الإطارات والمحدد المستخدم وتوقيت الفشل كي يتمكن المطور من إعادة المشكلة.

الخلاصة والمراجع

حل فشل النقر داخل iframe يبدأ بإثبات سياق المستند، ثم هوية العنصر، ثم قابليته للتفاعل، ثم الأثر الناتج. إذا اختلطت هذه المراحل أصبح الاختبار هشًا وسهل النجاح الكاذب. مرجع Playwright الرسمي عن FrameLocator: https://playwright.dev/docs/api/class-framelocator . ومرجع Locators: https://playwright.dev/docs/locators . للمقارنة مع مشكلات إضافات المتصفح اقرأ في إيجي تاج مقال «اختبار تعارض إضافتين تعدلان نفس الصفحة». لا تفترض أن كل iframe يتيح نفس التفاعل؛ قيود الأصل والإذن وسلوك الطرف الثالث تحدد حدود الاختبار.