استراتيجيات محددات العناصر

ما الذي يجعل المحدِّد جيداً

أفضل طريقة للحكم على المحدِّد هي النظر إلى ما يكسره. فالمحدِّد الجيد لا يتغير إلا إذا تغيّر السلوك الذي يعتمد عليه المستخدم — لا عندما يعيد مصمّم تسمية صنف أو يضيف مطوّر عنصر div مغلِّفاً.

• فريد — يطابق عنصراً واحداً بالضبط في الحالة التي يتوقعها الاختبار. محددات Playwright صارمة (strict): الإجراء على محدِّد يطابق عدة عناصر يرمي خطأ، ما يكشف الغموض مبكراً.
• مستقر — مستقل عن التخطيط والتنسيق وعمق DOM وترتيب العناصر والقيم المولّدة عند البناء أو العرض.
• مقروء — من يقرأ الاختبار يعرف أي عنصر يقصد دون أن يفتح الصفحة.
• قريب من نيّة المستخدم — يسمّي العنصر كما يدركه المستخدم أو التقنيات المساعدة: زر «إتمام الطلب»، وحقل «البريد الإلكتروني».
• رخيص الإصلاح — عندما ينكسر، توضّح رسالة الفشل السبب.

ترتيب الأولوية: ما يراه المستخدم أولاً وXPath أخيراً

يوصي توثيق Playwright بالمحددات المبنية على الدور أولاً، ويرتّب Testing Library استعلاماته بالطريقة نفسها: الاستعلامات التي تعكس كيف يدرك المستخدمون والتقنيات المساعدة الصفحة تأتي أولاً، ومعرّفات الاختبار تأتي أخيراً بين استعلاماته. وبإضافة CSS وXPath للحالات التي لا يصل إليها غيرهما يصبح الترتيب:

• 1. الدور والاسم الميسَّر — getByRole("button", { name: "Place order" }). يأتي الدور (Role) من عنصر HTML ‏(button وlink وtextbox وcheckbox وheading) أو من دور ARIA، ويأتي الاسم من التسمية أو المحتوى أو aria-label، ويُحسب كما تصف مواصفة W3C لحساب الاسم الميسَّر (Accessible Name).
• 2. التسمية (Label) — getByLabel("Email") لحقول النماذج المرتبطة بعنصر <label> أو بـ aria-labelledby.
• 3. النص المرئي والنص البديل والعنوان ونص التلميح في الحقل — getByText وgetByAltText وgetByTitle (ومحدِّد مقابل لنص التلميح داخل الحقل) للعناصر التي ليس لها دور واسم مفيدان. وتناسب محددات النص المحتوى غير التفاعلي مثل العناوين والرسائل؛ ونص التلميح بديل ضعيف عن التسمية.
• 4. معرّف الاختبار (Test id) — ‏getByTestId("order-total") يطابق data-testid افتراضياً في Playwright (والسمة قابلة للتهيئة)؛ ويوصي Cypress بـ data-cy أو سمة data-* مماثلة. استخدمه عندما تكون سمات المستخدم غامضة أو مفقودة أو كثيرة التغيّر، كالنصوص المترجمة.
• 5. محدِّد CSS — للحالات البنيوية: السمات والمُركِّبات وحقول الإدخال بالاسم. أبقِه قصيراً ومرتكزاً على سمات مستقرة.
• 6. XPath — عندما تحتاج إلى الصعود إلى عنصر أب أو سلف، أو مطابقة النص في أداة لا تملك محدِّداً للنص. أبقِه نسبياً وقصيراً.

Element: <button type="submit">Place order</button>

Playwright       page.getByRole("button", { name: "Place order" })
Testing Library  screen.getByRole("button", { name: "Place order" })
Selenium (Java)  driver.findElement(By.xpath("//button[normalize-space()='Place order']"))
                 driver.findElement(By.cssSelector("[data-testid=place-order]"))
Cypress          cy.contains("button", "Place order")
                 cy.get("[data-cy=place-order]")

تطبيق الترتيب في Selenium وCypress

لا يملك Selenium محدِّداً مدمجاً للدور. استراتيجياته هي id وname وclass name وtag name وlink text وpartial link text وCSS selector وXPath، ويضيف Selenium 4 المحددات النسبية (Relative locators): فوق، وتحت، وإلى اليسار، وإلى اليمين، وقريب من. وعملياً يصبح الترتيب: معرّف اختبار أو id مستقر، ثم name، ثم محدِّد CSS قصير، ثم XPath — مع الوصول إلى النص المرئي عبر link text للروابط أو XPath يطابق النص لغيرها. وتغلّف فرق كثيرة ذلك في دوال كائن الصفحة المسمّاة باسم العنصر كما يراه المستخدم، فتبقى الاختبارات مقروءة: «انقر إتمام الطلب».

يستعلم Cypress بـ cy.get ‏(CSS) وcy.contains ‏(النص). ويوصي دليل أفضل الممارسات فيه بسمات data-* مخصصة بدلاً من محددات الوسم والمعرّف والصنف، وبـ cy.contains للعناصر التي يكون نصها جزءاً من السلوك المختبَر. والفرق التي تريد استعلامات مبنية على الدور في Cypress كثيراً ما تضيف تكامل Testing Library الذي يضيف findByRole وبقية استعلامات findBy وfindAllBy.

معرّفات الاختبار: عقد مع المطورين

معرّف الاختبار سمة تُضاف إلى الترميز لأغراض الأتمتة فقط، مثل data-testid أو data-test أو data-cy. وهو أكثر نقاط الربط استقراراً لأنه لا يعتمد عليه شيء سوى الاختبارات — ما دام الفريق يعامله كعقد لا كزينة.

• اتفقوا على اسم سمة واحد للمنتج كله واضبطوا الأداة لاستخدامه (مثل إعداد testIdAttribute في Playwright).
• سمِّ حسب الغرض لا الموضع أو الشكل: checkout-place-order لا button-3 ولا blue-btn.
• اجعل المعرّفات فريدة داخل الصفحة. وللعناصر المتكررة ضع المعرّف على الحاوية أو حدّد النطاق بالمحتوى، ثم ابحث عن العنصر الابن بالدور — صف الطلب ORD-2026-000184، ثم زر «إلغاء» فيه.
• أضف معرّفات الاختبار في طلب الدمج نفسه الذي يضيف الميزة، وراجع حذفها كما تراجع تغييراً في API.
• لا تستبدل دوراً واسماً واضحين بمعرّف اختبار؛ فالمحدِّد المبني على ما يراه المستخدم يُظهر أيضاً أن العنصر مكشوف للتقنيات المساعدة.
• قرار حذف معرّفات الاختبار من نسخ الإنتاج قرار للفريق. إبقاؤها يكلّف بضعة بايتات ويتيح تشغيل اختبارات دخان للقراءة فقط على الإنتاج.

// Playwright: scope to the row for one order, then find its button by role
const row = page.getByRole("row").filter({ hasText: "ORD-2026-000184" });
await row.getByRole("button", { name: "Cancel" }).click();

// playwright.config.ts: use the attribute your team agreed on
export default defineConfig({ use: { testIdAttribute: "data-test" } });

CSS مقابل XPath

تعبّر اللغتان عن معظم الاستعلامات البنيوية، والفروق تظهر عند الأطراف. لا أحد منهما «خاطئ»، لكن CSS أقصر عادةً في الحالات الشائعة، وXPath هو الخيار الوحيد في حالات قليلة أخرى.

• المقروئية — CSS أقصر للمعرّفات والأصناف والسمات: [data-testid=cart] مقابل //*[@data-testid="cart"].
• الاتجاه — يستطيع XPath الصعود إلى الأب أو السلف (.. وancestor::tr) والانتقال إلى الأشقاء السابقين؛ أما CSS فيتحرك تقليدياً إلى الأسفل والأمام فقط. ويغطي الصنف الزائف (pseudo-class) ‎:has()‎، المدعوم في المتصفحات الرئيسية الحالية، بعض حالات «أب العنصر».
• النص — يستطيع XPath مطابقة النص (normalize-space()="Pay now" وcontains(., "Pay"))؛ ولا يستطيع CSS مطابقة محتوى النص. ويضيف Playwright وCypress مطابقة نصية خاصة بهما فوق CSS.
• Shadow DOM — يمكن استخدام محددات CSS داخل جذور الظل المفتوحة، ومحددات CSS والدور في Playwright تخترقها تلقائياً؛ أما XPath فلا يعبر حدود الظل.
• الإصدار — تطبّق المتصفحات XPath 1.0، لذا فدوال XPath 2.0 مثل matches() وends-with() غير متاحة.
• السرعة — كلاهما سريع بما يكفي لاختبارات الواجهة ونادراً ما يكون عنق الزجاجة. اختر حسب المقروئية والاستقرار.

Goal                           CSS                          XPath
Element by test id             [data-testid=cart]           //*[@data-testid="cart"]
Input by name                  input[name=email]            //input[@name="email"]
Id starting with a prefix      [id^="order-row-"]           //*[starts-with(@id,"order-row-")]
Attribute contains a value     [class*="error"]             //*[contains(@class,"error")]
Button with exact text         (not possible in CSS)        //button[normalize-space()="Pay now"]
Button in the row of an order  (CSS cannot match the text)  //tr[td[normalize-space()="ORD-2026-000184"]]//button
Parent of an element           (only via :has())            //input[@name="email"]/..

المعرّفات الديناميكية وأسماء الأصناف المولّدة

تولّد أطر ومكتبات مكوّنات كثيرة قيم السمات عند البناء أو العرض: id="input-4821" يتغير في كل عرض، وclass="Button_primary__3xK9a" من CSS modules، وclass="css-1q2w3e" من مكتبات CSS-in-JS. والمحدِّد الذي ينسخ قيمة كهذه ينجح اليوم ويفشل بعد البناء التالي أو التحميل التالي للصفحة.

• تعرّف عليها — أرقام أو قيم تجزئة تختلف بين تحميلين للصفحة نفسها. احفظ الترميز من جلستين وقارن بينهما لتكتشف الأجزاء المتحركة.
• فضّل محدِّداً مبنياً على ما يراه المستخدم أو معرّف اختبار — الحل الدائم نقطة ربط مستقرة، لا محدِّد أذكى.
• إن اضطررت إلى المطابقة فارتكز على الجزء المستقر — [id^="order-row-"] (يبدأ بـ) أو [class*="Button_primary"] (يحتوي) أو starts-with() في XPath. وأبقِ النمط ضيقاً بما يكفي ليظل فريداً.
• طابق النص المتغير بنمط — مثل getByText(/Order ORD-\d{4}-\d{6} confirmed/) في Playwright — واختبر النمط على عينات حقيقية قبل اعتماده.
• لا تكتب أبداً قيماً ثابتة تأتي من بيانات الاختبار — ابنِ المحدِّد من البيانات التي أنشأها الاختبار، مثل رقم الطلب الذي أعاده استدعاء API الذي هيّأ الاختبار.

جرّبها: أداة اختبار Regex جرّبها: مقارنة النصوص (Diff)

إطارات iframe وShadow DOM

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

يغلّف Shadow DOM الترميز الداخلي لمكوّن ويب. يمكن لأدوات الأتمتة الوصول إلى جذور الظل المفتوحة (open shadow roots). أما الجذور المغلقة فمخفية عمداً ولا تصل إليها المحددات القياسية؛ اختبرها عبر السلوك العام للمكوّن أو اطلب من المطورين نقطة ربط للاختبار.

• Selenium — ادخل إلى الإطار بـ driver.switchTo().frame(…)، ونفّذ، ثم عُد بـ driver.switchTo().defaultContent(). وفي Shadow DOM ابحث عن العنصر المضيف، واستدعِ getShadowRoot() ‏(Java؛ وshadow_root في Python)، ثم ابحث داخله بمحددات CSS.
• Playwright — ‏page.frameLocator(…) أو locator.contentFrame() يعطي نطاقاً للمحددات داخل الإطار دون تبديل. ومحددات Playwright تخترق جذور الظل المفتوحة افتراضياً، باستثناء XPath.
• Cypress — يُدعم Shadow DOM عبر الأمر ‎.shadow()‎ أو خيار الإعداد includeShadowDom. ولا يوجد أمر مدمج مخصص لإطارات iframe؛ والنهج الشائع هو الوصول إلى جسم مستند الإطار من عنصر iframe، والإطارات من نطاقات أخرى تضيف قيوداً إضافية.
• إطارات الأطراف الثالثة — لحقل البطاقة المستضاف لدى مزوّد الدفع، استخدم وضع الاختبار لدى المزوّد وبيانات الاختبار المنشورة لديه، وأبقِ عدد الاختبارات التي تكتب داخل الإطار صغيراً.

// Selenium (Java) — iframe: switch in, act, switch back
driver.switchTo().frame(driver.findElement(By.cssSelector("iframe[title='Card details']")));
driver.findElement(By.name("cardnumber")).sendKeys(testCardNumber);
driver.switchTo().defaultContent();

// Selenium (Java) — open shadow root, then CSS inside it
SearchContext shadow = driver.findElement(By.cssSelector("app-date-picker")).getShadowRoot();
shadow.findElement(By.cssSelector("button.next-month")).click();

// Playwright — frame scope, no switching; open shadow roots are pierced
const card = page.frameLocator("iframe[title='Card details']");
await card.getByLabel("Card number").fill(testCardNumber);
await page.locator("app-date-picker").getByRole("button", { name: "Next month" }).click();

أنماط خاطئة تجعل الحزم هشّة

• XPath المطلق — ‏/html/body/div[2]/div/div[3]/form/button ينكسر عندما يتغير أي سلف. وأمر «Copy XPath» في المتصفح كثيراً ما ينتج هذا بالضبط.
• المحددات المعتمدة على الفهرس — ‎:nth-child(3)‎ أو (//button)[2] أو ‎.first()‎ دون سبب. تعتمد على الترتيب وتنكسر عند إضافة عنصر أو حذفه أو تغيير الفرز.
• أصناف التنسيق — ‎.btn-primary‎ و‎.mt-4‎ و‎.text-red-500‎ تتغير مع كل إعادة تصميم مرئي أو إعادة هيكلة لأصناف CSS المساعدة.
• القيم المولّدة — المعرّفات وقيم تجزئة الأصناف الناتجة عند البناء أو العرض.
• السلاسل الطويلة — ‏div.container > div.row > div.col-md-6 > form > div:nth-child(2) > input يرمّز التخطيط كاملاً.
• نص بلغة خاطئة — الاختبار الذي يبحث عن «Place order» يفشل عندما تعمل الحزمة نفسها على الواجهة العربية («إتمام الطلب»). إما أن تعطي كل لغة نصوصها المتوقعة، وإما أن تستخدم معرّفات الاختبار للعناصر ذات النص المترجم.
• المحددات المكررة — المحدِّد نفسه ملصوق في عشرين اختباراً. احفظه في كائن صفحة أو مكوّن واحد.
• مطابقة نص واسعة جداً — getByText("Save") يطابق الزر وإشعاراً منبثقاً وفقرة مساعدة. حدّد النطاق بمنطقة أو استخدم الدور.

Automation defects caused by locators (written like bug titles)
- checkout.spec fails after restyle: .btn-primary no longer matches "Place order"
- orders.spec cancels the wrong order when the list is sorted by date: locator (//button[text()="Cancel"])[1]
- login.spec fails on the Arabic build: getByText("Sign in") not found
- profile.spec fails intermittently: #input-4821 is regenerated on every render
- search.spec breaks after a wrapper div is added: /html/body/div[2]/div/div[3]/form/button

المحددات وإمكانية الوصول

تستخدم محددات الدور والتسمية المعلومات نفسها التي يعلنها قارئ الشاشة: دور العنصر، من عنصر HTML أو WAI-ARIA، واسمه الميسَّر. فعندما لا يجد getByRole("button", { name: "Delete" }) زر حذف يتكون من أيقونة فقط، فالسبب المرجّح أن الزر بلا اسم ميسَّر — وهذا عيب حقيقي في إمكانية الوصول، لا مشكلة في الاختبار. أصلح الترميز (نص مرئي أو aria-label)، لا المحدِّد.

وينطبق الأمر نفسه عندما تعرض مكتبة مكوّنات عنصر div يتصرف كزر: أبلغ عن عيب غياب الدلالة بدلاً من كتابة محددات CSS للالتفاف عليه.

هذه فائدة جانبية لا اختبار لإمكانية الوصول. فنجاح المحددات المبنية على الدور لا يثبت أن الصفحة ميسَّرة؛ وتبقى فحوص لوحة المفاتيح وقارئ الشاشة والفحوص الآلية لإمكانية الوصول ضرورية.

مثال عملي: محددات نموذج إتمام الشراء

الترميز أدناه من صفحة إتمام شراء خيالية. لكل عنصر تعرض القائمة المحدِّد الموصى به، ومقابله في Selenium، وما يجب تجنبه.

• حقل البريد — getByLabel("Email"). في Selenium: ‏By.name("email"). تجنّب #email-1293 (مولّد) وform > input:nth-of-type(1).
• مربع الموافقة على الشروط — getByRole("checkbox", { name: "I accept the terms" }). في Selenium: ‏By.cssSelector("input[name=terms]").
• إجمالي الطلب — getByTestId("order-total")؛ نصه المرئي يتغير مع المبلغ، فالنص هو ما تتحقق منه لا ما تبحث به. في Selenium: ‏By.cssSelector("[data-testid=order-total]").
• زر الإرسال — getByRole("button", { name: "Place order" }). في Selenium: ‏XPath على النص بعد تطبيعه، أو معرّف اختبار إن أضافه الفريق. تجنّب ‎.btn-primary‎ و//form/button[1].
• النموذج نفسه — لا تستخدم #checkout-7f3a ولا ‎.Checkout_form__x9Kp2‎. وإن احتجت إلى نطاق فامنح النموذج اسماً ميسَّراً واستخدم getByRole("form", { name: … })، أو أضف معرّف اختبار.

<form id="checkout-7f3a" class="Checkout_form__x9Kp2">
  <label for="email-1293">Email</label>
  <input id="email-1293" name="email" type="email">
  <label><input type="checkbox" name="terms"> I accept the terms</label>
  <div class="summary">
    <span>Total</span> <span data-testid="order-total">199.20 SAR</span>
  </div>
  <button type="submit" class="btn btn-primary mt-4">Place order</button>
</form>

جرّبها: منسّق HTML

قائمة مراجعة المحددات

• هل يطابق عنصراً واحداً بالضبط في الحالة التي يتوقعها الاختبار؟
• هل يصمد أمام إعادة التنسيق وإعادة ترتيب العناصر وتغيّر عمق DOM؟
• هل هو الدور/التسمية/النص أولاً، ثم معرّف الاختبار، ثم CSS، ثم XPath — وإن لم يكن كذلك فهل السبب مكتوب؟
• هل هو خالٍ من المعرّفات المولّدة والأصناف المجزّأة والفهارس والمسارات المطلقة؟
• هل يعيش في كائن صفحة أو مكوّن واحد لا في جسم الاختبار؟
• هل يعمل في كل لغة تعمل بها الحزمة؟
• لو فشل غداً، هل ستخبرك رسالة الخطأ أي عنصر كان مفقوداً؟

الأسئلة الشائعة

المراجع

• Locators — PlaywrightMicrosoft (Playwright)كيف يعثر Playwright على العناصر، ولماذا تُعاد تحديد المحدِّدات وتنتظر تلقائياً، ولماذا يُوصى بالمحدِّدات المبنية على الدور أولاً.
• About Queries — Testing LibraryTesting Libraryأنواع الاستعلامات وأولويتها — الدور والتسمية قبل النص، ومعرّفات الاختبار أخيراً — لتعثر الاختبارات على العناصر كما يفعل المستخدمون والتقنيات المساعدة.
• Locator strategies — SeleniumSelenium Projectأنواع المحدِّدات التي يدعمها WebDriver (المعرّف والاسم ومحدِّد CSS وXPath ونص الرابط وغيرها) وكيف يُختار بينها.
• Best Practices — CypressCypress.ioإرشادات Cypress لاختيار العناصر بسمات مخصّصة، وتجنّب الانتظار الثابت، وإبقاء الاختبارات مستقلة.
• Best Practices — PlaywrightMicrosoft (Playwright)اختبر السلوك الذي يراه المستخدم، واجعل الاختبارات معزولة، وفضّل المحدِّدات المتينة والتأكيدات التي تنتظر، واستخدم التتبّع لتصحيح الأخطاء.
• Accessible Name and Description Computation 1.2W3C · 2026كيف تحسب المتصفحات الاسم والوصف الميسَّرين لعنصرٍ من التسميات وسمات ARIA والمحتوى (مسودة عمل من W3C).
• Accessible Rich Internet Applications (WAI-ARIA) 1.2W3C · 2023توصية W3C التي تعرّف أدوار ARIA وحالاتها وخصائصها — أي كيف تُعلن عناصر الواجهة المخصّصة معناها للتقنيات المساعدة.