أساسيات البرمجة لأتمتة الاختبار

لماذا يهم

المختبِر الذي لا يقرأ شيفرة الاختبار لا يستطيع أن يحكم هل كشف الاختبار الفاشل عيباً في المنتج أم أن فيه عيباً هو نفسه، ولا يستطيع مراجعة تغيير زميله. والأسوأ أن بعض عيوب الاختبار تجعله ينجح بينما المنتج معطّل: نسيان await يجعل التأكيد يعمل قبل أن تتغير الصفحة، وtry/catch الذي يسجّل الخطأ ويتابع يخفي الفحص الفاشل عن المشغّل. وحزمة مليئة بهذه الاختبارات تعرض اللون الأخضر ولا تكشف شيئاً.

كما أن شيفرة الاختبار تعمل مع كل تغيير، فبنيتها تحدد كلفة أي تعديل صغير في واجهة المستخدم: تعديل واحد في ملف واحد، أو التعديل نفسه في كل اختبار.

تدفق التحكم: if وfor...of والدوال السهمية

تستخدم شيفرة الاختبار القرارات والحلقات نفسها التي يستخدمها أي برنامج، لكن باعتدال. فـif/else يختار مساراً، مثلاً لإغلاق شريط ملفات تعريف الارتباط فقط عندما يظهر. وfor...of ينفّذ الخطوات نفسها مرة لكل عنصر في مصفوفة، وفي شيفرة الاختبار تحمل المصفوفة كائنات بيانات اختبار: كائن لكل حالة، فيه المدخلات والنتيجة المتوقعة. وتنشئ الحلقة اختباراً مسمّى لكل كائن، فإذا فشل أحدها عرف التقرير أي حالة فشلت.

الدالة السهمية (Arrow Function) مثل (a, b) => a + b دالة مكتوبة كقيمة. وتأخذ المشغّلات الدوال معاملاتٍ، لذلك يُكتب جسم كل اختبار دالةً تُمرَّر كدالة رد نداء (Callback)، وهي في الغالب دالة سهمية: test('name', async () => { ... }). يخزّن المشغّل هذه الدالة ويستدعيها لاحقاً، ولهذا لا يعمل جسمها أثناء تحميل الملف. وفي async ({ page }) => { ... } أدناه يمرّر المشغّل إلى الدالة كائناً، فيستخرج { page } خاصيته page (ويسمّى هذا التفكيك Destructuring)، وهي صفحة المتصفح الخاصة بهذا الاختبار.

• اكتب الرسالة المتوقعة في كائن البيانات، ولا تحسبها بـif داخل الاختبار، وإلا فقد يتفق الاختبار مع العيب.
• for...of يمر على القيم، وfor...in يمر على مفاتيح الكائن؛ وفي شيفرة الاختبار تريد for...of في الغالب.

const cases = [
  { email: 'sara@example.com', password: 'Correct-1', message: 'Welcome, Sara' },
  { email: 'sara@example.com', password: 'wrong', message: 'Invalid login' },
];

for (const c of cases) {
  test('login: ' + c.message, async ({ page }) => {   // one test per data object
    // the steps use c.email, c.password and c.message
  });
}

جرّبها: مولّد مستخدمين وهميين جرّبها: محوّل CSV إلى JSON

الوحدات البرمجية: export وimport

الوحدة البرمجية (Module) ملف يصرّح بما يشاركه. فـexport class LoginPage يجعل الاسم متاحاً، وimport { LoginPage } from './pages/login-page' يجلبه إلى ملف آخر. ولا يُشارَك شيء بالمصادفة: الاسم غير المصدَّر يبقى خاصاً بملفه، والملف الذي يحتاج شيئاً يجب أن يستورده.

لهذا يبدأ ملف الاختبار بنوعين من الاستيراد: test وexpect من حزمة المشغّل، وهما الدالتان اللتان تسجّلان اختباراً وتفحصان نتيجة، ثم كائنات الصفحات والبيانات من ملفاتك أنت. فيُقرأ الملف كسيناريو، وتبقى المحددات (Locators)، أي التعابير التي تجد عنصراً في الصفحة مثل getByLabel('Email')، في مكان واحد: عندما يتغير نموذج تسجيل الدخول تعدّل كائن الصفحة، فيُصلَح كل ملف اختبار يستورده.

• المسارات النسبية تبدأ بـ./ أو ../؛ أما أسماء الحزم مثل @playwright/test فلا.
• import type { Page } يستورد نوعاً فقط، ويحذفه المترجم (Compiler) من المخرجات.

// pages/login-page.ts
export class LoginPage { /* ... */ }

// login.spec.ts
import { test, expect } from '@playwright/test';   // the runner
import { LoginPage } from './pages/login-page';     // your page object

الأصناف والنسخ: شكل كائن الصفحة

الصنف (Class) قالب لكائنات تشترك في الحقول (البيانات) والدوال (Methods). وnew LoginPage(page) ينشئ نسخة (Instance): يشغّل المُنشئ (Constructor) الذي يخزّن صفحة المتصفح في حقل، ويعيد كائناً تصل دواله إلى ذلك الحقل عبر this. وكل اختبار ينشئ نسخته الخاصة، فلا يتشارك اختباران كائن صفحة واحداً.

وكائن الصفحة (Page Object) هو هذا بالضبط: حقل واحد للصفحة، ومُنشئ يستقبلها، ودالة لكل شيء يستطيع المستخدم فعله في الشاشة، مثل open() وsignIn(email, password). تخفي الدوال المحددات والنقرات، ويستدعيها الاختبار بأسمائها. ويضيف توثيق Selenium قاعدة تصحّ في كل لغة: لا تحتوي كائنات الصفحات على تأكيدات، لأن الاختبار هو من يقرر ما الصحيح؛ والفحص الوحيد الذي يسمح به داخل كائن الصفحة هو التحقق من أن الصفحة حُمّلت بشكل صحيح.

• private readonly page تعني أن الشيفرة داخل الصنف وحدها تستخدم الحقل، وأن الحقل لا يُعاد تعيينه بعد المُنشئ؛ والاختبار الذي يحاول الوصول إلى login.page يحصل على خطأ من المترجم.

import type { Page } from '@playwright/test';

export class LoginPage {
  private readonly page: Page;              // a field

  constructor(page: Page) {                 // runs once, on new
    this.page = page;                       // this = the instance being built
  }

  async open(): Promise<void> {             // a method
    await this.page.goto('/login');         // relative to baseURL in the config
  }

  async signIn(email: string, password: string): Promise<void> {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }
}

الشيفرة غير المتزامنة والأخطاء: انتظر كل شيء ولا تبتلع شيئاً

كل إجراء في المتصفح (goto وfill وclick) وكل تأكيد يكرّر المحاولة يُرجع وعداً (Promise)، لأن العمل يحدث في المتصفح ويستغرق وقتاً. والدالة التي تنتظر تُعلَن async، وداخلها يوقف await التنفيذ حتى يُحسم الوعد، ثم يتابع بالقيمة أو يرمي الخطأ. والقاعدة: ضع await قبل كل إجراء وكل تأكيد يعيد وعداً.

خطأ نسيان await من أول ما تبحث عنه عندما يتذبذب اختبار مكتوب بـJavaScript. فـlogin.open() بلا await يبدأ الانتقال وينفّذ السطر التالي فوراً، فالفحص الذي يقرأ الصفحة مرة واحدة قد يقرأ الصفحة القديمة؛ وإذا كان الاستدعاء غير المنتظَر هو آخر إجراء، فقد تنتهي دالة الاختبار قبل أن ينتهي هو، فلا يفحص شيء في الاختبار نتيجته. ولا يحذّر المترجم من وعد لا ينتظره أحد؛ لكن أداة التدقيق (Linter)، وهي أداة تفحص الشيفرة بحثاً عن أنماط خطرة مثل ESLint، تحذّر منه بقاعدة مثل @typescript-eslint/no-floating-promises، ويمكن أن يكشفه النوع أيضاً كما يبيّن المثال التطبيقي.

الخطأ المرمي هو طريقة فشل الاختبار: expect الفاشل يرمي خطأ، ويسجّله المشغّل نتيجةً. ويجب أن يحترم try/catch/finally ذلك. استخدم finally للتنظيف الذي يجب أن يعمل في الحالتين، وcatch فقط عندما يكون الخطأ هو ما تختبره، ثم أكّد عليه. أما catch الذي يسجّل ويتابع فيحوّل الفحص الفاشل إلى نجاح. والتنظيف الفعلي يحذف في الغالب البيانات التي أنشأها الاختبار؛ أما استدعاء clearCookies أدناه فيبيّن موضع التنظيف فقط، لأن Playwright يبدأ كل اختبار أصلاً دون ملفات تعريف ارتباط من الاختبارات الأخرى.

// Wrong: the navigation is started but not awaited
login.open();
expect(await page.title()).toBe('Sign in');      // may read the previous page

// Wrong: the error is swallowed, so the runner records a pass
try {
  await expect(page.getByTestId('message')).toHaveText('Welcome, Sara');
} catch (error) {
  console.log('check failed', error);            // the test still passes
}

// Right: await every action, let a failed check throw, clean up in finally
await login.open();
try {
  await login.signIn('sara@example.com', 'Correct-1');
  await expect(page.getByTestId('message')).toHaveText('Welcome, Sara');
} finally {
  await page.context().clearCookies();           // runs on pass and on fail
}

مثال تطبيقي: ملف اختبار بصيغة ترتيب، تنفيذ، تأكيد

أدناه ملف login.spec.ts الذي يستخدم الصنف LoginPage من قسم الأصناف، مع تسمية كل ميزة في هذا الدرس. ويتبع كل اختبار نمط «ترتيب، تنفيذ، تأكيد» (Arrange-Act-Assert): رتّب الحالة (أنشئ كائن الصفحة وافتح الصفحة)، ونفّذ (سجّل الدخول)، وأكّد (افحص الرسالة). وتنفيذ واحد وتأكيد واحد مركّز في كل اختبار يبقي التقرير مقروءاً.

توصيفات الأنواع (Type Annotations) مثل email: string وqty: number وPromise<void> أنواع (Types) في TypeScript؛ ويُقرأ Promise<T> وعداً سيعطي قيمة من النوع T، وvoid تعني لا قيمة. لا تغيّر هذه التوصيفات شيئاً وقت التشغيل. يفحصها المترجم ويبلّغ عن كل استدعاء لا يطابقها: signIn(c.email, 123) لأن الرقم ليس نصاً، وlogin.signin(...) لأن الدالة غير موجودة، وconst title = page.title(); title.includes('x') لأن title من النوع Promise<string> الذي لا يملك includes؛ أي أن النوع كشف await منسياً. أما Playwright فيحذف الأنواع دون فحصها ويشغّل الاختبارات رغم ذلك، فلا تظهر هذه الأخطاء إلا في محرّر الشيفرة وعند تشغيل npx tsc --noEmit (فحص فقط دون كتابة ملفات)، وهي خطوة تضيفها الفرق قبل تشغيل الاختبارات.

كيف يعمل هذا الملف؟ مشغّل الاختبارات برنامج تشغّله من سطر الأوامر (موضوع الدرس التالي). يبحث عن الملفات التي تطابق نمطاً مثل *.spec.ts ويحمّل كل ملف، فتعمل الشيفرة الموجودة في المستوى الأعلى من الملف: تستدعي الحلقة test(...) ويخزّن المشغّل الدوال. ثم يستدعي كل دالة مع page جديدة، وينتظر الوعد المُعاد، ويسجّل نجاحاً إذا تحقق، أو فشلاً مع الخطأ وتتبّع مكدسه إذا رُفض.

• لمستخدمي Selenium: import يقابل import في Java أو from ... import في Python؛ والصنف بحقوله ومُنشئه موجود في اللغتين (__init__ وself في Python، ومُنشئ باسم الصنف وthis في Java)؛ وارتباطات Java وPython متزامنة فلا await فيها: كل استدعاء يتوقف حتى يجيب برنامج التشغيل (Driver)، والخطر المقابل هناك هو نسيان انتظار صريح (Explicit Wait).

الجزء 1:1import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/login-page';

الجزء 2:2const cases = [
  { email: 'sara@example.com', password: 'Correct-1', message: 'Welcome, Sara' },
  { email: 'sara@example.com', password: 'wrong', message: 'Invalid login' },
];

الجزء 3:3for (const c of cases) {
  الجزء 4:4test('login: ' + c.message, async ({ page }) => {
    const login = الجزء 5:5new LoginPage(page);
    الجزء 6:6await login.open();
    await login.signIn(c.email, c.password);
    الجزء 7:7await expect(page.getByTestId('message')).toHaveText(c.message);
  });
}

import type { Page } from '@playwright/test';

الجزء 8:8export class LoginPage {
  الجزء 9:9private readonly page: Page;
  constructor(page: Page) { this.page = page; }

  async open(): Promise<void> { await this.page.goto('/login'); }

  الجزء 10:10async signIn(email: string, password: string): Promise<void> {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }
}

// login.spec.ts
import { test, expect } from '@playwright/test';   // module: the runner
import { LoginPage } from './pages/login-page';     // module: our page object

const cases = [                                     // test data: one object per case
  { email: 'sara@example.com', password: 'Correct-1', message: 'Welcome, Sara' },
  { email: 'sara@example.com', password: 'wrong', message: 'Invalid login' },
];

for (const c of cases) {                            // control flow: one test per object
  test('login: ' + c.message, async ({ page }) => { // async arrow function as callback
    // Arrange
    const login = new LoginPage(page);              // class -> instance
    await login.open();                             // await: a browser action
    // Act
    await login.signIn(c.email, c.password);        // typed: (string, string)
    // Assert
    await expect(page.getByTestId('message')).toHaveText(c.message);
  });
}

جرّبها: منسّق JavaScript جرّبها: مولّد طلبات REST

أسئلة شائعة

المراجع

• ECMAScript® Language Specification (ECMA-262)Ecma International / TC39معيار لغة JavaScript، بما فيه قواعد RegExp ودلالاتها، وJSON.parse/JSON.stringify، وكائن Date.
• JavaScript — MDNMDN Web Docs (Mozilla)دليل MDN ومرجعه للغة JavaScript: صياغة اللغة وأنواعها وكائناتها ومكوّناتها المدمجة كما تنفّذها المتصفحات.
• Playwright DocumentationMicrosoft (Playwright)التوثيق الرسمي لـ Playwright، إطار الاختبار الشامل الذي يشغّل Chromium وWebKit وFirefox.
• Page object models — SeleniumSelenium Projectنمط كائن الصفحة (Page Object): صنف لكل صفحة أو مكوّن يخفي المحدِّدات ويعرض الإجراءات التي يحتاجها الاختبار، فيقل التكرار.