1. ما هي مكتبة Puppeteer ولماذا تستخدم؟

Puppeteer هي مكتبة خاصة بـ Node.js توفر واجهة برمجة تطبيقات (API) عالية المستوى للتحكم في متصفح Chrome (أو Chromium) عبر بروتوكول DevTools Protocol. تعمل Puppeteer افتراضيًا في وضع "بدون واجهة رسومية" (headless)، مما يجعلها الأداة المثالية لأتمتة مهام الويب على الخادم. ولكن يمكنك أيضًا تشغيل المتصفح بواجهة رسومية كاملة لأغراض التصحيح.

تشمل حالات الاستخدام الرئيسية لـ Puppeteer: استخراج بيانات الويب (Web Scraping) من المواقع الديناميكية التي تعتمد على JavaScript، الاختبار الآلي لتطبيقات الويب (اختبارات E2E)، إنشاء لقطات شاشة وملفات PDF للصفحات، محاكاة إجراءات المستخدم (النقر، ملء النماذج، التنقل)، بالإضافة إلى مراقبة أداء صفحات الويب. على عكس طلبات HTTP البسيطة، تقوم Puppeteer بتنفيذ JavaScript داخل الصفحة، مما يسمح لك بالحصول على المحتوى الذي يتم إنشاؤه ديناميكيًا.

المكتبة مدعومة بنشاط من فريق Google وتُستخدم في بيئات الإنتاج من قبل آلاف الشركات. تمنحك Puppeteer تحكمًا كاملاً في المتصفح: من إدارة علامات التبويب واعتراض طلبات الشبكة إلى محاكاة الأجهزة المحمولة والموقع الجغرافي. إنها أداة شاملة تغني عن مجموعة كاملة من الأدوات المساعدة للتعامل مع محتوى الويب.

2. كيفية تثبيت Puppeteer

لتثبيت Puppeteer عبر npm (مدير حزم Node.js)، قم بتنفيذ الأمر التالي في الطرفية (Terminal) داخل مجلد مشروعك:

npm install puppeteer

سيؤدي هذا الأمر إلى تنزيل المكتبة نفسها وتنزيل نسخة متوافقة من متصفح Chromium تلقائيًا (بحجم يتراوح بين 300-400 ميجابايت). إذا كنت تريد استخدام متصفح Chrome/Chromium المثبت بالفعل على نظامك، فقم بتثبيت puppeteer-core:

npm install puppeteer-core

عند استخدام puppeteer-core، ستحتاج إلى تحديد المسار إلى ملف المتصفح القابل للتنفيذ عند التشغيل. للعمل مع المكتبة، تحتاج إلى إصدار Node.js 18.0.0 أو أحدث (يُوصى باستخدام الإصدار LTS).

3. البداية السريعة — مثال عملي بسيط

قم بإنشاء ملف باسم example.js وأضف الكود التالي الذي يلتقط لقطة شاشة لصفحة ويب:

const puppeteer = require('puppeteer');

(async () => {
    // تشغيل المتصفح
    const browser = await puppeteer.launch();
    // فتح صفحة جديدة
    const page = await browser.newPage();
    // الانتقال إلى موقع ويب
    await page.goto('https://example.com');
    // التقاط لقطة شاشة
    await page.screenshot({ path: 'example.png' });
    // إغلاق المتصفح
    await browser.close();
})();

قم بتشغيل السكريبت باستخدام الأمر node example.js. سيظهر في المجلد ملف example.png يحتوي على لقطة شاشة لصفحة example.com. هذا مثال بسيط ولكنه عملي بالكامل لأتمتة المتصفح.

4. أهم الأساليب والدوال والكلاسات

فيما يلي 8 من أهم أساليب وكلاسات Puppeteer مع الشرح وأمثلة الكود.

4.1. puppeteer.launch()

التوقيع: puppeteer.launch([options]) → Promise<Browser>

الوظيفة: تشغيل نسخة من متصفح Chromium/Chrome. تقبل كائنًا من الخيارات (headless, slowMo, args وغيرها). تُرجع كائن Browser.

const browser = await puppeteer.launch({
    headless: false, // إظهار المتصفح
    slowMo: 100,    // إبطاء الإجراءات (بالمللي ثانية)
    args: ['--window-size=1920,1080']
});