الاختبار البصري مع Playwright: الدليل الكامل

الاختبار البصري مع Playwright: الدليل الكامل

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

يتضمن Playwright من Microsoft منذ الإصدار 1.22 ميزة أصلية للاختبار البصري: الدالة toHaveScreenshot(). فهي تتيح التقاط لقطات شاشة ومقارنتها آليًا بصور مرجعية، دون أي إضافة خارجية. وهو حل مجاني بالكامل: ولمعرفة أدوات الاختبار البصري المجانية الأخرى، راجعوا مقارنتنا.

وهو من أقوى الخيارات للفرق التي تريد إضافة اختبارات بصرية إلى مجموعتها القائمة. ولفهم أساسيات الانحدار البصري، راجعوا دليلنا الشامل. يغطي هذا الدليل التثبيت والإعداد وأفضل الممارسات والتكامل مع CI/CD، ثم ما يغيّره SDK Vision من Delta-QA في هذه الاختبارات نفسها.

الخلاصة في صفحة واحدة: ما الذي تؤتمته أداة بدون برمجة فعلًا وكيف تقارن بغيرها: أتمتة الاختبارات بدون برمجة.

هل لا يزال toHaveScreenshot() يجبركم على كتابة الشيفرة وصيانتها؟ يلتقط Delta-QA صفحاتكم ويقارنها دون كتابة سطر شيفرة واحد، وبدون بطاقة مصرفية. جرّب Delta-QA مجانًا ←

التثبيت وأول اختبار

الإعداد سريع إن كان لديكم مشروع Node.js:

npm install -D @playwright/test
npx playwright install

ثم أنشئوا أول اختبار بصري في tests/visual.spec.ts:

import { test, expect } from '@playwright/test';

test('homepage visual test', async ({ page }) => {
  await page.goto('https://your-site.com');
  await expect(page).toHaveScreenshot('homepage.png');
});

يولّد التشغيل الأول خط الأساس (baseline، أي الصورة المرجعية). وتقارن التشغيلات اللاحقة اللقطة الحالية بخط الأساس هذا وتبلّغ عن الفروق.

# Première fois : générer les baselines
npx playwright test --update-snapshots

# Ensuite : comparer
npx playwright test

هذا كل ما في البداية من بساطة. ويأتي التعقيد مع الحالات الواقعية.

ضبط التسامح

افتراضيًا، يبلّغ Playwright عن أدنى فرق بمقدار بكسل واحد. وعمليًا، يجب ضبط عتبات تسامح لتفادي الإيجابيات الكاذبة.

في playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01,  // 1 % de pixels différents toléré
      animations: 'disabled',    // désactive les animations CSS
      scale: 'device',           // tient compte des écrans Retina
    },
  },
});

ويمكنكم أيضًا الضبط اختبارًا باختبار:

// Page statique : seuil strict
await expect(page).toHaveScreenshot('landing.png', {
  maxDiffPixelRatio: 0.001
});

// Tableau de bord avec graphiques : seuil plus souple
await expect(page).toHaveScreenshot('dashboard.png', {
  maxDiffPixelRatio: 0.05,
  mask: [page.locator('.chart')]
});

العتبة مفاضلة: إن كانت منخفضة جدًا، أفشل أدنى اختلاف في العرض الاختبار؛ وإن كانت مرتفعة جدًا، تسللت تحت الحد هامشٌ انتقل من 16px إلى 12px دون أن يُرى.

التعامل مع المحتوى الديناميكي

المحتوى الديناميكي (التواريخ والإعلانات والصور الرمزية والعدّادات) هو كابوس الاختبارات البصرية. يقترح Playwright ثلاثة حلول:

إخفاء المناطق الديناميكية، وهي الطريقة الأكثر شيوعًا:

await expect(page).toHaveScreenshot({
  mask: [
    page.locator('.ad-banner'),
    page.locator('.timestamp'),
    page.locator('.user-avatar')
  ]
});

استبدال المحتوى لتثبيت القيم:

await page.evaluate(() => {
  document.querySelector('.date').textContent = '01/01/2026';
});
await expect(page).toHaveScreenshot();

الإخفاء عبر CSS للعناصر التي يجب ألا تظهر إطلاقًا:

await page.addStyleTag({
  content: '.dynamic-element { visibility: hidden !important; }'
});
await expect(page).toHaveScreenshot();

كل حل من هذه الحلول يُصان يدويًا: كتلة ديناميكية جديدة في الصفحة تعني محددًا إضافيًا يجب إضافته.

تثبيت الاختبارات

اختبار بصري ينجح يومًا ويفشل في اليوم التالي دون سبب لا يصلح للاستخدام. إليكم كيف تضمنون الاستقرار:

test('stable visual test', async ({ page }) => {
  await page.goto('https://your-site.com');

  // Attendre que le réseau soit calme
  await page.waitForLoadState('networkidle');

  // Attendre le chargement des polices
  await page.evaluate(() => document.fonts.ready);

  // Attendre un élément critique
  await page.waitForSelector('.hero-image', { state: 'visible' });

  await expect(page).toHaveScreenshot();
});

ولتعطيل الحركات (animations) يدويًا حين لا يكفي الخيار العام:

await page.addStyleTag({
  content: `
    *, *::before, *::after {
      animation-duration: 0s !important;
      transition-duration: 0s !important;
    }
  `
});

الاختبار على عدة دقّات عرض

يسهّل Playwright الاختبار متعدد الدقّات عبر المشاريع:

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Desktop',
      use: { viewport: { width: 1920, height: 1080 } },
    },
    {
      name: 'Tablet',
      use: { viewport: { width: 768, height: 1024 } },
    },
    {
      name: 'Mobile',
      use: { ...devices['iPhone 13'] },
    },
  ],
});

يولّد كل مشروع خطوط الأساس الخاصة به. فيُنفَّذ الاختبار الواحد ثلاث مرات، بثلاث دقّات، مع ثلاث مجموعات من اللقطات يجب إبقاؤها محدّثة.

التكامل مع CI/CD

التكامل مع GitHub Actions مباشر. وللحصول على إعداد كامل، راجعوا دليلنا عن اختبارات عدم الانحدار في GitHub Actions أو، في جانب GitLab، دليل الاختبار البصري في GitLab CI.

name: Visual Tests
on: [push, pull_request]
jobs:
  visual-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

حين يفشل اختبار، ينتج Playwright ثلاث صور: خط الأساس (المتوقع)، واللقطة الحالية، وصورة فروق تظهر الاختلافات بالأحمر. ويعرضها تقرير HTML (npx playwright show-report) جنبًا إلى جنب.

نقطة انتباه: يختلف عرض الخطوط من نظام إلى آخر. فخطوط الأساس المولّدة على Mac لن تطابق اللقطات الملتقطة على مشغّل Linux في CI. ولّدوها في CI، أو في صورة Docker الرسمية الخاصة بـ Playwright.

هل لا يزال toHaveScreenshot() يطلب منكم كتابة الشيفرة؟ يلتقط Delta-QA صفحاتكم ويقارنها بدون برمجة، وبدون بطاقة مصرفية. جرّب Delta-QA مجانًا ←

حدود مقاربة Playwright

Playwright ممتاز للفرق التي تكتب اختباراتها، لكن لـ toHaveScreenshot() حدودًا ينبغي معرفتها:

مهارات إلزامية: يجب إتقان TypeScript/JavaScript والمحددات وإعداد المشروع. ولا يستطيع مختبرو الجودة الذين لا يكتبون الشيفرة إنشاء هذه الاختبارات ولا صيانتها.

لا واجهة مراجعة: لا يوجد فضاء مشترك للحكم على الفروق. وتتم إدارة خطوط الأساس عبر الطرفية ونظام الملفات. وفي الفريق يصبح الأمر معقدًا سريعًا.

مقارنة بكسلات: تُظهر صورة الفروق منطقة حمراء لا ما تغيّر. فاختلافات تنعيم الحواف بين المتصفحات وتباينات عرض الخطوط بين أنظمة التشغيل، كلها تولّد ضجيجًا يجب التعامل معه يدويًا بالأقنعة والعتبات.

الصيانة: كل تغيير مقصود في الواجهة يفرض إعادة توليد خطوط الأساس (--update-snapshots). وفي مشروع به 200 اختبار بصري وثلاثة متصفحات، يعني ذلك 600 خط أساس يجب إدارتها، ومُصدَّرة في المستودع. ويفصّل دليلنا عن إدارة خطوط الأساس استراتيجيات صيانتها.

الإبقاء على Playwright وتغيير المقارنة: SDK Vision

إذا كانت اختبارات Playwright لديكم قائمة بالفعل، فلستم مضطرين إلى تركها لرفع جزء من هذه الحدود. تضيف حزمة SDK Vision من Delta-QA (@delta-qa/vision) تحققًا من Delta-QA حيث ينبغي للاختبار أن ينظر إلى الصفحة:

import { test } from "@delta-qa/vision/fixture";

test("Checkout", async ({ page, vision }) => {
  const checkout = await vision.open(page, { id: "checkout", name: "Checkout" });
  await page.goto("https://shop.example.com/checkout");
  await checkout.check("Payment");
}); // تُغلقه الـ fixture: أي اختلاف لم يُحكَم عليه يُفشل الاختبار

تقرأ الحزمة مفتاح API من المتغير DELTAQA_API_KEY. ومن دون الـ fixture، تفتح open(page, { … }) من @delta-qa/vision الاختبار نفسه، وتغلقه close() في afterEach.

ما الذي يتغير مقارنة بـ toHaveScreenshot():

  • يسمّي التقرير العنصر الذي تغيّر. لا منطقة حمراء تحتاج إلى تفسير: يخبركم التقرير أي عنصر تغيّر، مثل زر «ادفع» الذي انتقل من الأزرق إلى الأخضر.
  • لم تعد المراجع تعيش في المستودع. عند التشغيل الأول يصبح كل فحص (check) هو المرجع. وبعدها، يُفشل أي فرق لم يُحكم عليه الاختبار، ويعرض سجل CI رابط التقرير. وهناك تحكمون على كل فرق: «مقصود» أو «خطأ».
  • مرجع لكل فرع. يعطي الاختبار فرعه وفرعه الأساسي (branch، baseBranch): يُقارن الفرع الجديد بفرعه الأساسي منذ تشغيله الأول، ولا ينطبق «مقصود» إلا على الفروع التي تحددونها.
  • بقية الاختبار لا تتغير. تظل مشاريع playwright.config.ts سارية: لكل حجم شاشة مرجعه الخاص. الشرط الوحيد: كثافة شاشة تساوي 1 (deviceScaleFactor: 1).

تغطي الحزمة Playwright بلغتي TypeScript وJavaScript، على Chromium. وهي تُعرض أولًا في إتاحة مبكرة: يُطلب الوصول من صفحتها.

وللذين لا يكتبون الاختبارات

تظل اختبارات Playwright شيفرة. ولكي يتحقق مختبرو الجودة ومالكو المنتج أو المصممون أيضًا من مظهر التطبيق، تقدم الحلول بدون برمجة مثل Delta-QA طريقًا آخر: يُسجَّل مسار في المتصفح، ويعيد Delta-QA تشغيله مع كل إصدار ويقارن كل خطوة بمرجعها. وتُحكَم هذه السيناريوهات وفحوص SDK Vision في فضاء Delta-QA نفسه، بالتقرير نفسه.

هل تريدون الاختبار دون سطر TypeScript واحد ودون خط أساس واحد يُعاد توليده؟ قارنوا صفحاتكم مع Delta-QA الآن، مجانًا وبدون بطاقة مصرفية. جرّب Delta-QA مجانًا ←

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

هل Playwright مجاني للاختبارات البصرية؟

نعم، كليًا. الدالة toHaveScreenshot() مدمجة أصلًا في Playwright، وهو مفتوح المصدر وتصونه Microsoft. لا رخصة ولا حد للقطات الشاشة.

كم يستغرق إعداد الاختبارات البصرية في Playwright؟

إذا كنتم تتقنون Playwright بالفعل، فاحسبوا بضع ساعات لإعداد أولى اختباراتكم وكتابتها. وإذا بدأتم من الصفر (التثبيت وتعلّم TypeScript وإعداد CI)، فاحسبوا من يومين إلى ثلاثة أيام.

Playwright أم Cypress للاختبارات البصرية؟

يتميز Playwright بدمج الاختبار البصري أصلًا (toHaveScreenshot())، بينما يحتاج Cypress إلى إضافة خارجية. ويدعم Playwright أيضًا ثلاثة محركات متصفحات (Chromium وFirefox وWebKit)، في حين يدعم Cypress متصفحات Chromium وFirefox، ويبقى WebKit تجريبيًا. وللتفصيل، راجعوا مقارنتنا Playwright مقابل Cypress، أو Playwright مقابل Selenium إن كنتم تترددون بين هذين الإطارين.

هل يمكن استخدام Playwright وDelta-QA معًا؟

نعم، وفي الاختبار نفسه. مع SDK Vision، تضيفون vision.check() إلى الخطوات التي يجب التحقق من الصفحة عندها: يقود Playwright المتصفح وتأكيداتكم الوظيفية، ويقارن Delta-QA الصفحة بمرجعها. وتُحكَم المسارات التي يسجلها فريق الجودة بدون برمجة في الفضاء نفسه.

هل يجب أن أحذف toHaveScreenshot() لاستخدام SDK Vision؟

لا. يمكن للاثنين التعايش في مجموعة واحدة: يمكنكم إضافة vision.check() على بضع صفحات ومقارنة النتائج، ثم تقرير ما تحتفظون به صفحة بصفحة.


يوفّر Playwright أساسًا متينًا للاختبارات البصرية الآلية. وللفرق التي تكتب اختباراتها بـ TypeScript، فإن toHaveScreenshot() هو على الأرجح أفضل خيار مفتوح المصدر متاح في 2026، بشرط ضبط العتبات جيدًا وتثبيت الاختبارات منذ البداية. وحين يصبح فرق البكسلات وخطوط الأساس في المستودع هما العبء الرئيسي، فإن SDK Vision يحتفظ باختباراتكم ويغيّر المقارنة. ولوضع Playwright بين الأدوات الأخرى، راجعوا مقارنتنا لأدوات اختبار عدم الانحدار.