تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

ما هي حالة التوافق مع جميع المتصفِّحات؟

لا يزال دعم Firefox الرسمي تجريبيًا. يهدف التعاون المستمر مع Mozilla إلى دعم حالات الاستخدام الشائعة للاختبارات الشاملة بين الأطراف، والتي يتوقع مطوّرو البرامج الحصول على تغطية لها على جميع المتصفحات. يحتاج فريق Puppeteer إلى ملاحظات من المستخدمين لتثبيت دعم Firefox ولفت انتباهنا إلى واجهات برمجة التطبيقات المفقودة.

بدءًا من الإصدار 2.1.0 من Puppeteer، يمكنك تحديد puppeteer.launch({product: 'firefox'}) تشغيل نصوص Puppeteer النصية في Firefox Nightly بدون أي رموز
مخصّصة إضافية. على الرغم من أنّ التجربة القديمة تتطلّب إصدارًا مصحّحًا من متصفِّح Firefox، تعمل الطريقة الحالية مع الإصدار "stock" من Firefox.

نواصل التعاون مع موردي المتصفحات الآخرين لتوفير الدعم لبرنامج Puppeteer في المتصفحات، مثل Safari. وتشمل هذه الجهود استكشاف معيار لتنفيذ الأوامر عبر المتصفحات (بدلاً من الاعتماد على بروتوكول أدوات مطوّري البرامج غير العادي الذي يستخدمه Chrome).

ما أهداف ومبادئ Puppeteer؟

أهداف المشروع هي:

توفير مكتبة أساسية رفيعة المستوى تُبرز إمكانات بروتوكول أدوات مطوّري البرامج
توفير تطبيق مرجعي لمكتبات الاختبار المشابهة في النهاية، يمكن لهذه الأطر الأخرى اعتماد Puppeteer كطبقتها الأساسية.
زيادة معدّل استخدام اختبار المتصفِّح بلا واجهة مستخدم رسومية أو بدون واجهة مستخدم رسومية
ساعِد التطبيق التجريبي لميزات بروتوكول DevTools الجديدة...وتعرَّف على الأخطاء
يمكنك الاطّلاع على مزيد من المعلومات حول نقاط الضعف في اختبار المتصفِّح المبرمَج والمساعدة في سد هذه الثغرات.

نعمل على تعديل مبادئ Chromium لمساعدتنا في اتخاذ قرارات بشأن المنتج:

السرعة: لا يُقاس أداء محرك البحث Puppeteer بأي أداء زائد على صفحة مبرمَجة.
الأمان: ينفِّذ محرّك بحث Puppeteer خارج المعالجة فيما يتعلق بـ Chromium، مما يجعله آمنًا لتشغيل الصفحات التي يُحتمل أن تكون ضارة تلقائيًا.
الثبات: يجب ألا يكون محرك الدمى غير مستقر ويجب ألا يؤدي إلى تسريب الذاكرة.
البساطة: يوفر Puppeteer واجهة برمجة تطبيقات عالية المستوى يسهل استخدامها وفهمها وتصحيح الأخطاء.

هل يحل Puppeteer محل Selenium/WebDriver؟

لا، كلا المشروعين مفيدان لأسباب مختلفة جدًا:

يركّز Selenium/WebDriver على التشغيل الآلي على جميع المتصفِّحات، ويمثّل عرض القيمة لواجهة برمجة تطبيقات عادية واحدة تعمل على جميع المتصفّحات الرئيسية.
يركّز محرّك بحث Puppeteer على Chromium، الذي يعرض قيمة أكبر وموثوقية أعلى.

ومع ذلك، يمكنك استخدام Puppeteer لإجراء اختبارات ضد Chromium، مثل استخدام jest-ppeteer الذي يستعين به المنتدى. على الرغم من أنّه من المحتمل ألا يكون هذا هو حل الاختبار الوحيد لديك، فإنّه يحتوي على بعض النقاط الجيدة مقارنةً بـ WebDriver:

يتطلّب Puppeteer إعدادًا صفرًا ويأتي مزوّدًا بإصدار Chromium الذي يعمل معه بشكل أفضل. ومن الأفضل إجراء بعض الاختبارات التي تجري في Chromium فقط بدلاً من عدم إجراء اختبارات على الإطلاق.
لدى Puppeteer بنية قائمة على الأحداث، مما يزيل الكثير من القصور المحتمل. ليست هناك حاجة إلى استدعاءات "sleep(1000)" الشريرة في نصوص العرائس النصية.
يعمل محرك الدُمى بلا واجهة مستخدم رسومية بشكل افتراضي، مما يجعله سريعًا في الركض. يعرض الإصدار 1.5.0 من Puppeteer أيضًا سياقات المتصفح، ما يتيح له توقُّع سير عملية تنفيذ الاختبار بكفاءة.
يتألق Puppeteer عندما يتعلق الأمر بتصحيح الأخطاء: اقلب الجزء "بلا واجهة" إلى خطأ، وأضف "slowMo"، وسترى ما يفعله المتصفح. يمكنك أيضًا فتح "أدوات مطوري البرامج في Chrome" لفحص بيئة الاختبار.

لماذا لا يعمل إصدار Puppeteer v.XXX مع Chromium v.YYY؟

نعتبر أنّ Puppeteer كيانًا غير قابل للتقسيم في Chromium. يضم كل إصدار من Puppeteer إصدارًا محددًا من Chromium، وهو الإصدار الوحيد المضمون للعمل معه.

هذا ليس قيدًا مصطنعًا. يتم في الواقع تنفيذ الكثير من الأعمال على Puppeteer في مستودع Chromium. وإليك قصة نموذجية:

تم الإبلاغ عن خطأ في Puppeteer
هذه مشكلة متعلّقة ببروتوكول "أدوات مطوري البرامج"، لذا نصلحها في Chromium.
بعد الوصول إلى قمة البرنامج، نعرض Chromium المحدَّث إلى Puppeteer

ومع ذلك، غالبًا ما يكون من المستحسن استخدام Puppeteer مع Google Chrome الرسمي بدلاً من Chromium. لتنفيذ ذلك الإجراء، يجب تثبيت إصدار puppeteer-core الذي يتوافق مع إصدار Chrome.

على سبيل المثال، لتشغيل Chrome 101 مع Puppeteer-core، استخدِم العلامة chrome-101 npm:

npm install puppeteer-core@chrome-101

ما هو إصدار Chromium الذي يستخدمه Puppeteer؟

ابحث عن الإصدار باستخدام إحدى الطرق التالية:

ابحث عن الإدخال chromium في revisions.ts. للعثور على رقم الالتزام ورقم الإصدار المقابل في Chromium، ابحث عن النسخة السابقة المسبَقة بـ r في قسم "Find Releases" (البحث عن إصدارات) في OmahaProxy.
ابحث عن خريطة versionsPerRelease في versions.js التي تحتوي على تعيين بين إصداري Chromium وPuppeteer. ملاحظة: يحتوي الملف على إصدارات Puppeteer فقط التي يتم تحديث Chromium فيها. لم يتم سرد جميع إصدارات Puppeteer.

ما هو إصدار Firefox الذي يستخدمه Puppeteer؟

ولأنّ استخدام Firefox تجريبي، ينزّل Puppeteer أحدث إصدار من Firefox Nightly عند ضبط متغير بيئة PUPPETEER_PRODUCT على firefox. ولهذا السبب أيضًا تكون قيمة firefox في revisions.ts هي latest -- لا يرتبط Puppeteer بإصدار معين من Firefox.

لجلب Firefox Nightly كجزء من تثبيت Puppeteer:

PUPPETEER_PRODUCT=firefox npm i puppeteer
# or "yarn add puppeteer"

ما الذي يعتبر التنقل؟

من وجهة نظر Puppeteer، فإن "التنقل" هو أي شيء يغيّر عنوان URL للصفحة. بصرف النظر عن التنقّل العادي الذي يشغّل فيه المتصفّح الشبكة لجلب مستند جديد من خادم الويب، يشمل ذلك عمليات التنقّل إلى ارتساء واستخدام History API.

من خلال تعريف "التنقل" هذا، يعمل تطبيق Puppeteer بسلاسة مع تطبيقات الصفحة الواحدة.

ما الفرق بين حدث إدخال "موثوق به" و"غير موثوق به"؟

في المتصفِّحات، يمكن تقسيم أحداث الإدخال إلى مجموعتَين كبيرتَين: "موثوق بها" في مقابل "غير موثوق بها".

الأحداث الموثوق بها: الأحداث التي ينشئها المستخدمون الذين يتفاعلون مع الصفحة، مثل استخدام الماوس أو لوحة المفاتيح.
الحدث غير الموثوق به: الأحداث التي تم إنشاؤها بواسطة واجهات برمجة تطبيقات الويب، مثل طريقتَي document.createEvent أو element.click().

يمكن للمواقع الإلكترونية التمييز بين هاتين المجموعتَين:

باستخدام علامة حدث Event.isTrusted
والتقاط الصور للأحداث المصاحبة لها. على سبيل المثال، يسبق كل حدث 'click' موثوق به حدثان 'mousedown' و'mouseup'.

لأغراض التشغيل الآلي، من المهم إنشاء أحداث موثوق بها. جميع أحداث الإدخال التي يتم إنشاؤها باستخدام Puppeteer موثوقة ويتم تنشيطها للأحداث المصاحبة بشكل صحيح.

إذا احتاج المرء لسبب ما إلى حدث غير موثوق به، من الممكن دائمًا الانتقال إلى سياق الصفحة باستخدام page.evaluate وإنشاء حدث مزيّف:

await page.evaluate(() => {
  document.querySelector('button[type=submit]').click();
});

ما هي الميزات غير المتوفّرة في Puppeteer؟

قد تجد أنّ محتوى Puppeteer لا يتصرف كما هو متوقع عند التحكم في الصفحات التي تتضمن صوتًا وفيديو. على سبيل المثال، من المحتمل أن يتعذّر تشغيل الفيديو ولقطات الشاشة). هناك سببان لذلك:

يكون Puppeteer مُرفقًا مع Chromium (وليس Chrome). لذلك، تكتسب بشكل افتراضي كل القيود المتعلقة بالوسائط في Chromium. يعني ذلك أنّ Puppeteer لا يتيح استخدام التنسيقات المرخّصة مثل AAC أو H.264.
- من الممكن إجبار Puppeteer على استخدام إصدار مثبَّت بشكل منفصل من Chrome بدلاً من Chromium باستخدام خيار executablePath لإجراء puppeteer.launch. يجب استخدام هذه الإعدادات فقط إذا كنت بحاجة إلى إصدار رسمي من Chrome يتوافق مع تنسيقات الوسائط هذه.
نظرًا لأن Puppeteer (في جميع الإعدادات) يتحكم في إصدار سطح المكتب من Chromium أو Chrome، فلا تتوفر الميزات التي لا تتوافق إلا مع إصدار Chrome للأجهزة الجوّالة. يعني ذلك أنّ تطبيق Puppeteer لا يتيح استخدام البث المباشر وفق بروتوكول HTTP (HLS).

أواجه مشكلة في تثبيت / تشغيل Puppeteer في بيئة الاختبار. أين يمكنني البحث عن مساعدة؟

لدينا دليل تحديد المشاكل وحلّها لأنظمة التشغيل المختلفة الذي يسرد التبعيات المطلوبة.

يتم تنزيل Chromium عند كل عملية تشغيل `npm ci`. كيف يمكنني تخزين المحتوى الذي تم تنزيله في ذاكرة التخزين المؤقت؟

مسار التنزيل التلقائي هو node_modules/puppeteer/.local-chromium. ومع ذلك، يمكنك تغيير هذا المسار باستخدام متغير بيئة PUPPETEER_DOWNLOAD_PATH.

يستخدم Puppeteer هذا المتغيّر لحل موقع Chromium القابل للتنفيذ أثناء الإطلاق، لذلك لا تحتاج إلى تحديد PUPPETEER_EXECUTABLE_PATH أيضًا.

على سبيل المثال، للاحتفاظ بتنزيل Chromium في ~/.npm/chromium:

export PUPPETEER_DOWNLOAD_PATH=~/.npm/chromium
npm ci

# by default the Chromium executable path is inferred
# from the download path
npm test

# a new run of npm ci will check for the existence of
# Chromium in ~/.npm/chromium
npm ci

لدي المزيد من الأسئلة! أين يمكنني طرح الأسئلة؟

هناك العديد من الطرق للحصول على المساعدة بشأن Puppeteer:

احرص على البحث في هذه القنوات قبل نشر سؤالك.