ferrum

Ferrum - API عالي المستوى للتحكم في الكروم في روبي

بسيطة مثل العرائس ، على الرغم من أبسط.

إنه API نظيف Ruby وعالي المستوى إلى Chrome. يتم تشغيل مقطوعة الرأس بشكل افتراضي ، ولكن يمكنك تكوينها لتشغيلها في وضع الرأس. كل ما تحتاجه هو Ruby و Chrome أو Chromium. يتصل Ferrum بالمستعرض بواسطة بروتوكول CDP ولا يوجد تبعية سيلينيوم/WebDriver/Chromedriver. تم التركيز على بروتوكول CDP الخام لأن Chrome يسمح لك بالقيام بالعديد من الأشياء التي بالكاد تدعمها WebDriver لأنه يجب أن يكون له تصميم ثابت مع متصفحات أخرى.

• Cuprite هو سائق روبي نقي لـ Capybara على أساس Ferrum. إذا كنت ستزحف إلى مواقع ، فمن الأفضل أن تستخدم ferrum أو الوعاء لأنك تزحف ، وليس الاختبار.

• إطار زحف الويب على شبكة الإنترنت على مستوى السفينة على أساس Ferrum و Mechanize.

فِهرِس

• ثَبَّتَ
• أمثلة
• عامل ميناء
• التخصيص
• ملاحة
• الباحثون
• لقطات الشاشة
• شبكة
• التنزيلات
• الوكيل
• الماوس
• لوحة المفاتيح
• ملفات تعريف الارتباط
• الرؤوس
• جافا سكريبت
• إطارات
• إطار
• مربعات الحوار
• الرسوم المتحركة
• العقدة
• تتبع
• تنظيف
• السلامة الموضوع
• تطوير
• المساهمة
• رخصة

ثَبَّتَ

لا توجد حزمة كروم أو كروم رسمية لـ Linux لا يتم تثبيتها بهذه الطريقة لأنها إما عفا عليها الزمن أو غير رسمية ، كلاهما سيء. قم بتنزيله من المصدر الرسمي للكروم أو الكروم. يجب أن يكون Chrome Binary في PATH أو BROWSER_PATH ويمكنك تمريره كخيار لمثيل المتصفح راجع :browser_path في التخصيص.

أضف هذا إلى Gemfile الخاص بك وتركيب bundle install .

 gem "ferrum" 

أمثلة

انتقل إلى موقع ويب وحفظ لقطة شاشة:

 browser = Ferrum :: Browser . new
browser . go_to ( "https://google.com" )
browser . screenshot ( path : "google.png" )
browser . quit

عندما تعمل مع مثيل المتصفح ، يقوم Ferrum بإنشاء صفحة افتراضية لك ، في الواقع ، يتم إرسال جميع الطرق المذكورة أعلاه إلى مثيل page الذي يتم إنشاؤه في default_context من مثيل browser . يمكنك التفاعل مع صفحة تم إنشاؤها يدويًا وهذا مفضل:

 browser = Ferrum :: Browser . new
page = browser . create_page
page . go_to ( "https://google.com" )
input = page . at_xpath ( "//input[@name='q']" )
input . focus . type ( "Ruby headless driver for Chrome" , :Enter )
page . at_css ( "a > h3" ) . text # => "rubycdp/ferrum: Ruby Chrome/Chromium driver - GitHub"
browser . quit

تقييم بعض JavaScript والحصول على عرض/ارتفاع كامل:

 browser = Ferrum :: Browser . new
page = browser . create_page
page . go_to ( "https://www.google.com/search?q=Ruby+headless+driver+for+Capybara" )
width , height = page . evaluate <<~JS
  [document.documentElement.offsetWidth,
   document.documentElement.offsetHeight]
JS
# => [1024, 1931]
browser . quit

افعل أي حركات ماوس تحبها:

 # Trace a 100x100 square
browser = Ferrum :: Browser . new
page = browser . create_page
page . go_to ( "https://google.com" )
page . mouse
  . move ( x : 0 , y : 0 )
  . down
  . move ( x : 0 , y : 100 )
  . move ( x : 100 , y : 100 )
  . move ( x : 100 , y : 0 )
  . move ( x : 0 , y : 0 )
  . up

browser . quit 

عامل ميناء

في Docker كجذر ، يجب أن تمرر خيار متصفح No-Sandbox:

 Ferrum :: Browser . new ( browser_options : { 'no-sandbox' : nil } )

وقد تم الإبلاغ أيضًا عن تعطل عملية Chrome مرارًا وتكرارًا عند الركض داخل حاوية Docker على جهاز M1 Mac يمنع Ferrum من العمل. يجب أن تعمل Ferrum كما هو متوقع عند نشرها في حاوية Docker على جهاز Mac غير M1.

التخصيص

يمكنك تخصيص الخيارات مع الكود التالي في إعداد الاختبار الخاص بك:

 Ferrum :: Browser . new ( options )

• خيارات Hash
  • :headless (سلسلة | منطقية) - ضبط المتصفح على أنه مقطوع الرأس أم لا ، true بشكل افتراضي. يمكنك تعيين "new" لدعم وضع جديد مقطوعة الرأس.
  • :xvfb (منطقية) - تشغيل المتصفح في إطار افتراضي ، false بشكل افتراضي.
  • :flatten (Boolean) - استخدم اتصال WebSocket واحد بالمتصفح وجميع الصفحات في وضع Flatten.
  • :window_size (صفيف) - أبعاد نافذة المتصفح التي لاختبار فيها ، معبراً عنها كصفيف من العناصر ، على سبيل المثال [1024 ، 768]. الافتراضي: [1024 ، 768]
  • :extensions (Array [String | hash]) - مجموعة من المسارات إلى الملفات أو رمز مصدر JS ليتم تحميلها مسبقًا في المتصفح على سبيل المثال: ["/path/to/script.js", { source: "window.secret = 'top'" }]
  • :logger (الكائن الذي يستجيب لـ puts ) - عند الحضور ، يتم كتابة ناتج التصحيح إلى هذا الكائن.
  • :slowmo (عدد صحيح | تعويم) - تعيين تأخير في ثوان للانتظار قبل إرسال الأمر. رفيق مفيد لخيار مقطوع الرأس ، بحيث يكون لديك وقت لرؤية التغييرات.
  • :timeout (Numeric) - عدد الثواني سننتظر الرد عند التواصل مع المتصفح. الافتراضي هو 5.
  • :js_errors (منطقية) - عندما يتم إعادة إعادة أخطاء JavaScript في Ruby.
  • :pending_connection_errors (Boolean) - عندما لا يزال الإطار الرئيسي ينتظر الاستجابات البطيئة أثناء الوصول إلى المهلة PendingConnectionsError . من الأفضل معرفة سبب استجابات بطيئة وإصلاحها أو حظرها بدلاً من إيقاف هذا الإعداد. الافتراضي صحيح.
  • :browser_name (رمز) - :chrome افتراضيًا ، الدعم التجريبي فقط لـ :firefox في الوقت الحالي.
  • :browser_path (String) - Path to Chrome Binary ، يمكنك أيضًا تعيين Env متغير مثل BROWSER_PATH=some/path/chrome bundle exec rspec .
  • :browser_options (hash)-خيارات سطر الأوامر الإضافية ، شاهدها جميعًا على سبيل المثال { "ignore-certificate-errors" => nil }
  • :ignore_default_browser_options (منطقية) - يحتوي Ferrum على عدد من الخيارات الافتراضية التي تنتقلها إلى المتصفح ، إذا قمت بتعيين هذا على true ، ثم الخيارات فقط التي تضعها :browser_options إلى المتصفح ، باستثناء المطلوب بالطبع.
  • :port (Integer) - منفذ تصحيح الأخطاء عن بُعد للكروم مقطوع الرأس.
  • :host (سلسلة) - عنوان تصحيح الأخطاء عن بُعد للكروم بدون رأس.
  • :url (سلسلة) - عنوان URL لمثيل تشغيل من الكروم. إذا تم تعيين هذا ، فلن يتم أن تولد عملية المتصفح.
  • :ws_url (سلسلة) - عنوان URL WebSocket لمثيل تشغيل Chrome. إذا تم تعيين هذا ، فلن يتم أن تولد عملية المتصفح. إنها أولوية أعلى من :url ، وضع كلاهما لا معنى له.
  • :process_timeout (عدد صحيح) - كم من الوقت لانتظار عملية Chrome للرد على بدء التشغيل.
  • :ws_max_receive_size (عدد صحيح) - ما مدى كمية الرسائل التي يجب قبولها من Chrome عبر مقبس الويب ، بالبايت. الإعدادات الافتراضية إلى 64 ميجابايت. الرسائل الواردة أكبر من هذا سوف تسبب Ferrum::DeadBrowserError .
  • :proxy (التجزئة) - حدد إعدادات الوكيل ، اقرأ المزيد
  • :save_path (سلسلة) - مسار لحفظ المرفقات مع رأس تحديد المحتوى.
  • :env (التجزئة) - متغيرات البيئة التي ترغب في نقلها إلى العملية

ملاحة

go_to (url): String

تنقل الصفحة إلى.

• String URL يجب أن يتضمن عنوان URL مخططًا ما لم تقم بتعيين base_url عند تكوين برنامج التشغيل.

 page . go_to ( "https://github.com/" ) 

خلف

انتقل إلى الصفحة السابقة في التاريخ.

 page . go_to ( "https://github.com/" )
page . at_xpath ( "//a" ) . click
page . back 

إلى الأمام

انتقل إلى الصفحة التالية في التاريخ.

 page . go_to ( "https://github.com/" )
page . at_xpath ( "//a" ) . click
page . back
page . forward 

ينعش

إعادة تحميل الصفحة الحالية.

 page . go_to ( "https://github.com/" )
page . refresh 

قف

أوقف جميع عمليات التنقل وتحميل الموارد المعلقة على الصفحة

 page . go_to ( "https://github.com/" )
page . stop 

الموضع = ** خيارات

اضبط موضع نافذة المتصفح

• خيارات Hash
  • : Integer ترك
  • : Integer أعلى

 browser . position = { left : 10 , top : 20 } 

الموقف: Array<Integer>

احصل على موقف نافذة المتصفح

 browser . position # => [10, 20] 

Window_bounds = ** خيارات

تعيين حدود النافذة

• خيارات Hash
  • : Integer ترك
  • : Integer أعلى
  • : Integer العرض
  • : ارتفاع Integer
  • : Window_state String

 browser . window_bounds = { left : 10 , top : 20 , width : 1024 , height : 768 , window_state : "normal" } 

window_bounds: Hash<String, Integer | String>

احصل على حدود النافذة

 browser . window_bounds # => { "left": 0, "top": 1286, "width": 10, "height": 10, "windowState": "normal" } 

Window_id: Integer

معرف النافذة الحالي

 browser . window_id # => 1 

الباحثون

AT_CSS (المحدد ، ** خيارات): Node | nil

العثور على عقدة بواسطة المحدد. تشغيل document.querySelector .

• String المحدد
• خيارات Hash
  • : داخل Node | nil

 page . go_to ( "https://github.com/" )
page . at_css ( "a[aria-label='Issues you created']" ) # => Node 

CSS (محدد ، ** خيارات): Array<Node> | []

العثور على العقد من قبل المحدد. تقوم الطريقة بتشغيل document.querySelectorAll داخل المستند أو العقدة المقدمة.

• String المحدد
• خيارات Hash
  • : داخل Node | nil

 page . go_to ( "https://github.com/" )
page . css ( "a[aria-label='Issues you created']" ) # => [Node] 

AT_XPATH (محدد ، ** خيارات): Node | nil

العثور على عقدة بواسطة XPath.

• String المحدد
• خيارات Hash
  • : داخل Node | nil

 page . go_to ( "https://github.com/" )
page . at_xpath ( "//a[@aria-label='Issues you created']" ) # => Node 

xPath (محدد ، ** خيارات): Array<Node> | []

العثور على العقد بواسطة xpath.

• String المحدد
• خيارات Hash
  • : داخل Node | nil

 page . go_to ( "https://github.com/" )
page . xpath ( "//a[@aria-label='Issues you created']" ) # => [Node] 

Current_url: String

إرجاع موقع النافذة العلوي الحالي HREF.

 page . go_to ( "https://google.com/" )
page . current_url # => "https://www.google.com/" 

Current_title: String

إرجاع عنوان النافذة الحالية الحالية

 page . go_to ( "https://google.com/" )
page . current_title # => "Google" 

الجسم: String

إرجاع HTML الصفحة الحالية.

 page . go_to ( "https://google.com/" )
page . body # => '<html itemscope="" itemtype="http://schema.org/WebPage" lang="ru"><head>... 

لقطات الشاشة

لقطة الشاشة (** خيارات): String | Integer

يحفظ لقطة الشاشة على قرص أو يعيدها كـ BASE64.

• خيارات Hash
  • : String المسار لحفظ لقطة شاشة على القرص. :encoding على :binary تلقائيًا
  • : Symbol الترميز :base64 | :binary يمكنك تعيينه لإرجاع الصورة كـ BASE64
  • : تنسيق String "JPEG" ("JPG") | "PNG" | "webp"
  • : جودة Integer 0-100 يعمل مع JPEG فقط
  • : Boolean كاملة سواء كنت بحاجة إلى لقطة شاشة كاملة أو منفذ عرض
  • : محدد CSS String Selector للعنصر المعطى ، اختياري
  • : منطقة Hash المنطقة لقطات الشاشة ، اختيارية
    • : x Integer
    • : y Integer
    • : Integer العرض
    • : ارتفاع Integer
  • : المقياس Float التكبير/خارج
  • : background_color Ferrum::RGBA.new(0, 0, 0, 0.0) للحصول على لون خلفية محدد

 page . go_to ( "https://google.com/" )
# Save on the disk in PNG
page . screenshot ( path : "google.png" ) # => 134660
# Save on the disk in JPG
page . screenshot ( path : "google.jpg" ) # => 30902
# Save to Base64 the whole page not only viewport and reduce quality
page . screenshot ( full : true , quality : 60 , encoding : :base64 ) # "iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAYAAAC6uhUNAAAAAXNSR0IArs4c6Q...
# Save on the disk with the selected element in PNG
page . screenshot ( path : "google.png" , selector : 'textarea' ) # => 11340
# Save to Base64 with an area of the page in PNG
page . screenshot ( path : "google.png" , area : { x : 0 , y : 0 , width : 400 , height : 300 } ) # => 54239
# Save with specific background color
page . screenshot ( background_color : Ferrum :: RGBA . new ( 0 , 0 , 0 , 0.0 ) ) 

PDF (** خيارات): String | Boolean

يحفظ PDF على قرص أو يعيده كـ BASE64.

• خيارات Hash

  • : String المسار لحفظ PDF على القرص. :encoding على :binary تلقائيًا

  • : Symbol الترميز :base64 | :binary يمكنك تعيينه لإرجاع PDF كـ BASE64

  • : اتجاه المناظر الطبيعية Boolean . الإعدادات الافتراضية إلى خطأ.

  • : المقياس Float التكبير/خارج

  • : أحجام الورق القياسية symbol التنسيق: الحروف ،: قانوني ،: تابلويد ،: Ledger ،: A0 ،: A1 ،: A2 ،: A3 ،: A4 ،: A5 ،: A6

  • : paper_width Float عرض الورق عرض الورق

  • : Paper_Height Float Leight Leaft

  • انظر الخيارات الأصلية الأخرى التي يمكنك تمريرها

 page . go_to ( "https://google.com/" )
# Save to disk as a PDF
page . pdf ( path : "google.pdf" , paper_width : 1.0 , paper_height : 1.0 ) # => true 

MHTML (** خيارات): String | Integer

يحفظ MHTML على قرص أو يعيده كسلسلة.

• خيارات Hash
  • : String المسار لحفظ ملف على القرص.

 page . go_to ( "https://google.com/" )
page . mhtml ( path : "google.mhtml" ) # => 87742 

شبكة

page.network

Array<Network::Exchange>

إرجاع جميع المعلومات حول حركة مرور الشبكة كشبكة Network::Exchange مثيل والذي يعد غلافًا حول request response error .

 page . go_to ( "https://github.com/" )
page . network . traffic # => [#<Ferrum::Network::Exchange, ...] 

طلب: Network::Request

طلب صفحة الإطار الرئيسي.

 page . go_to ( "https://github.com/" )
page . network . request # => #<Ferrum::Network::Request... 

الاستجابة: Network::Response

استجابة الصفحة للإطار الرئيسي.

 page . go_to ( "https://github.com/" )
page . network . response # => #<Ferrum::Network::Response... 

الحالة: Integer

يحتوي على رمز الحالة لاستجابة الصفحة الرئيسية (على سبيل المثال ، 200 لتحقيق النجاح). هذا مجرد اختصار response.status .

 page . go_to ( "https://github.com/" )
page . network . status # => 200 

wait_for_idle (** خيارات): Boolean

ينتظر الشبكة الخاملة ، وإرجاع true في حالة النجاح false إذا كانت لا تزال هناك اتصالات.

• خيارات Hash
  • : اتصالات Integer عدد الاتصالات المسموح بها للشبكة لتكون خامدة ، 0 افتراضيا
  • : مدة Float النوم لفترة معينة من الوقت وتحقق مرة أخرى ، 0.05 بشكل افتراضي
  • : Timeout Float خلال الفترة التي نحاول فيها التحقق من الخمول ، browser.timeout افتراضيًا

 page . go_to ( "https://example.com/" )
page . at_xpath ( "//a[text() = 'No UI changes button']" ) . click
page . network . wait_for_idle # => true 

wait_for_idle! (** خيارات)

ينتظر شبكة الخمول أو يرفع خطأ Ferrum::TimeoutError . يقبل نفس الوسائط مثل wait_for_idle .

 page . go_to ( "https://example.com/" )
page . at_xpath ( "//a[text() = 'No UI changes button']" ) . click
page . network . wait_for_idle! # might raise an error 

واضح (النوع)

مسح ذاكرة التخزين المؤقت للصفحة أو حركة المرور التي تم جمعها.

• اكتب Symbol هو إما :traffic أو :cache

 traffic = page . network . traffic # => []
page . go_to ( "https://github.com/" )
traffic . size # => 51
page . network . clear ( :traffic )
traffic . size # => 0 

اعتراض (** خيارات)

تعيين اعتراض الطلب للخيارات المعطاة. هذه الطريقة هي فقط تعيين اعتراض الطلب ، يجب عليك استخدامها on رد الاتصال للتقاط الطلبات وإحباطها أو متابعتها.

• خيارات Hash
  • : String نمط * افتراضيًا
  • : Resource_type Symbol أحد أنواع الموارد

 browser = Ferrum :: Browser . new
page = browser . create_page
page . network . intercept
page . on ( :request ) do | request |
  if request . match? ( /bla-bla/ )
    request . abort
  elsif request . match? ( /lorem/ )
    request . respond ( body : "Lorem ipsum" )
  else
    request . continue
  end
end
page . go_to ( "https://google.com" ) 

تفويض (** خيارات ، & block)

إذا كان الموقع أو الوكيل يستخدم التفويض ، فيمكنك توفير بيانات الاعتماد باستخدام هذه الطريقة.

• خيارات Hash
  • : اكتب Symbol :server | :proxy أو ترخيص الوكيل
  • : String المستخدم
  • : String كلمة المرور
• يقبل & Block طلب مصادق عليه ، والذي يجب عليك السماح به لاحقًا أو ترفضه ، إذا كنت لا تهتم بالطلبات غير المرغوب فيها ، فما عليك سوى request.continue الاتصال.

 page . network . authorize ( user : "login" , password : "pass" ) { | req | req . continue }
page . go_to ( "http://example.com/authenticated" )
puts page . network . status # => 200
puts page . body # => Welcome, authenticated client

نظرًا لأن أدوات Chrome تسمح باستخدام اعتراض الطلب ، يجب عليك متابعة الطلبات المسموح بها أو إحباطها. إذا كان لديك بالفعل رمز يستخدم اعتراضًا ، يمكنك استخدام authorize بدون كتلة ، ولكن إذا لم تكن ملزمًا بتمرير الكتلة ، فإن هذا الإصدار لا يمر بلوك ويمكنه العمل بشكل جيد:

 browser = Ferrum :: Browser . new
page = browser . create_page
page . network . intercept
page . on ( :request ) do | request |
  if request . resource_type == "Image"
    request . abort
  else
    request . continue
  end
end

page . network . authorize ( user : "login" , password : "pass" , type : :proxy )

page . go_to ( "https://google.com" )

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

MUTULE_NETWORK_CONDITIONS (** خيارات)

ينشط محاكاة ظروف الشبكة.

• خيارات Hash
  • : غير Boolean محاكاة انقطاع الإنترنت ، false بشكل افتراضي
  • : Integer زمن الانتقال الحد الأدنى لاستمرار الطلب من الطلب المرسلة إلى رؤوس الاستجابة المستلمة (MS) ، 0 بشكل افتراضي
  • : Download_throughput Integer MAXICREGATED تنزيل الإنتاجية (BYTES/SEC) ، -1 بشكل افتراضي ، تعطيل تنزيل الاختناق
  • : upload_throughpute Integer Maximal Mainted Andpload Tareput (Bytes/Sec) ، -1 بشكل افتراضي ، يعطل تنزيل الاختناق
  • : Connection_type نوع String إذا كان معروفًا ، أحد: لا شيء ، cellular2g ، cellular3g ، cellular4g ، البلوتوث ، الإيثرنت ، wifi ، wimax ، أخرى. nil افتراضيا

 page . network . emulate_network_conditions ( connection_type : "cellular2g" )
page . go_to ( "https://github.com/" ) 

غير متصل

ينشط الوضع دون اتصال للصفحة.

 page . network . offline_mode
page . go_to ( "https://github.com/" ) # => Ferrum::StatusError (Request to https://github.com/ failed(net::ERR_INTERNET_DISCONNECTED)) 

ذاكرة التخزين المؤقت (تعطيل: Boolean )

تبديل تجاهل ذاكرة التخزين المؤقت لكل طلب. إذا كان صحيحًا ، فلن يتم استخدام ذاكرة التخزين المؤقت.

 page . network . cache ( disable : true ) 

التنزيلات

page.downloads

ملفات Array<Hash>

إرجاع جميع المعلومات حول الملفات التي تم تنزيلها Hash .

 page . go_to ( "http://localhost/attachment.pdf" )
page . downloads . files # => [{"frameId"=>"E3316DF1B5383D38F8ADF7485005FDE3", "guid"=>"11a68745-98ac-4d54-9b57-9f9016c268b3", "url"=>"http://localhost/attachment.pdf", "suggestedFilename"=>"attachment.pdf", "totalBytes"=>4911, "receivedBytes"=>4911, "state"=>"completed"}] 

انتظر (مهلة)

ينتظر حتى ينتهي التنزيل.

 page . go_to ( "http://localhost/attachment.pdf" )
page . downloads . wait

أو

 page . go_to ( "http://localhost/page" )
page . downloads . wait { page . at_css ( "#download" ) . click } 

set_behavior (** خيارات)

يحدد السلوك في حالة تم تنزيل الملف.

• خيارات Hash
  • : Save_Path String المسار المطلق لمكان تخزين الملف
  • : Symbol السلوك deny | allow | allowAndName | default ، allow افتراضيا

 page . go_to ( "https://example.com/" )
page . downloads . set_behavior ( save_path : "/tmp" , behavior : :allow ) 

الوكيل

يمكنك تعيين وكيل مع :proxy :

 Ferrum :: Browser . new ( proxy : { host : "x.x.x.x" , port : "8800" , user : "user" , password : "pa$$" } )

:bypass قائمة المضيفين التي يفصل بينها كولون والتي لا ينبغي استخدام الوكيل:

 Ferrum :: Browser . new ( proxy : { host : "x.x.x.x" , port : "8800" , bypass : "*.google.com;*foo.com" } )

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

 browser = Ferrum :: Browser . new

browser . create_page ( proxy : { host : "x.x.x.x" , port : 31337 , user : "user" , password : "password" } ) do | page |
  page . go_to ( "https://api.ipify.org?format=json" )
  page . body # => "x.x.x.x"
end

browser . create_page ( proxy : { host : "y.y.y.y" , port : 31337 , user : "user" , password : "password" } ) do | page |
  page . go_to ( "https://api.ipify.org?format=json" )
  page . body # => "y.y.y.y"
end

الماوس

page.mouse

scroll_to (x ، y)

قم بالتمرير إلى x ، y

• X Integer طول البيكسل على طول المحور الأفقي للمستند الذي تريد عرضه في الجزء العلوي الأيسر
• y Integer البكسل على طول المحور العمودي للمستند الذي تريد عرضه في الجزء العلوي الأيسر

 page . go_to ( "https://www.google.com/search?q=Ruby+headless+driver+for+Capybara" )
page . mouse . scroll_to ( 0 , 400 ) 

انقر فوق (** خيارات): Mouse

انقر فوق الإحداثيات المعطاة ، تحرك الفأر ، والأحداث لأسفل وأعلى.

• خيارات Hash
  • : x Integer
  • : y Integer
  • : تأخير Float الافتراضات إلى 0. التأخير بين الأحداث لأسفل والماوس
  • : زر Symbol : اليسار | : اليمين ، الافتراضيات إلى: اليسار
  • : العد Integer الافتراضي إلى 1
  • : المعدلات Integer bitfield للمعدلات الرئيسية. انظر keyboard.modifiers

أسفل (** خيارات): Mouse

الماوس لأسفل للإحداثيات المعطاة.

• خيارات Hash
  • : زر Symbol : اليسار | : اليمين ، الافتراضيات إلى: اليسار
  • : العد Integer الافتراضي إلى 1
  • : المعدلات Integer bitfield للمعدلات الرئيسية. انظر keyboard.modifiers

UP (** خيارات): Mouse

الماوس حتى الإحداثيات المعطاة.

• خيارات Hash
  • : زر Symbol : اليسار | : اليمين ، الافتراضيات إلى: اليسار
  • : العد Integer الافتراضي إلى 1
  • : المعدلات Integer bitfield للمعدلات الرئيسية. انظر keyboard.modifiers

تحرك (x: ، y: ، الخطوات: 1): Mouse

انتقال الماوس إلى إعطاء x و y.

• خيارات Hash
  • : x Integer
  • : y Integer
  • : خطوات Integer الافتراضية إلى 1. يرسل أحداث mousemove الوسيطة.

لوحة المفاتيح

page.keyboard

أسفل (مفتاح): Keyboard

يرسل حدث keydown.

• String المفاتيح | اسم Symbol المفتاح مثل "A" ،: Enter ،: Packspace

UP (مفتاح): Keyboard

يرسل حدث keyup.

• String المفاتيح | اسم Symbol المفتاح مثل "B" ،: ENTER ،: Packspace

اكتب (*مفاتيح): Keyboard

يرسل حدث keydown ، keypress/input ، وحدث keyup لكل حرف في النص.

• String نص | Array<String> | Array<Symbol> نص لاكتبه في عنصر مركّز ، [:Shift, "s"], "tring"

المعدلات (المفاتيح): Integer

يعيد Bitfield لمفاتيح معينة

• Array<Symbol> : Alt | : Ctrl | : Command | :يحول

ملفات تعريف الارتباط

page.cookies

الكل: Hash<String, Cookie>

إرجاع ملفات تعريف الارتباط تجزئة

 page . cookies . all # => {"NID"=>#<Ferrum::Cookies::Cookie:0x0000558624b37a40 @attributes={"name"=>"NID", "value"=>"...", "domain"=>".google.com", "path"=>"/", "expires"=>1583211046.575681, "size"=>178, "httpOnly"=>true, "secure"=>false, "session"=>false}>} 

: Cookie

إرجاع ملف تعريف الارتباط

• String القيمة

 page . cookies [ "NID" ] # => <Ferrum::Cookies::Cookie:0x0000558624b67a88 @attributes={"name"=>"NID", "value"=>"...", "domain"=>".google.com", "path"=>"/", "expires"=>1583211046.575681, "size"=>178, "httpOnly"=>true, "secure"=>false, "session"=>false}> 

مجموعة (قيمة): Boolean

يضع ملف تعريف ارتباط

• قيمة Hash
  • : String الاسم
  • : String القيمة
  • : String المجال
  • : تنتهي Integer
  • : String sameite
  • : Httponly Boolean

 page . cookies . set ( name : "stealth" , value : "omg" , domain : "google.com" ) # => true

• قيمة Cookie

 nid_cookie = page . cookies [ "NID" ] # => <Ferrum::Cookies::Cookie:0x0000558624b67a88>
page . cookies . set ( nid_cookie ) # => true 

إزالة (** خيارات): Boolean

يزيل ملف تعريف الارتباط المعطى

• خيارات Hash
  • : String الاسم
  • : String المجال
  • : String URL

 page . cookies . remove ( name : "stealth" , domain : "google.com" ) # => true 

واضح: Boolean

يزيل جميع ملفات تعريف الارتباط للصفحة الحالية

 page . cookies . clear # => true 

المتجر (المسار): Boolean

يخزن جميع ملفات تعريف الارتباط للصفحة الحالية في ملف.

 # Cookies are saved into cookies.yml
page . cookies . store # => 15657 

تحميل (مسار): Boolean

تقوم بتحميل جميع ملفات تعريف الارتباط من الملف وتعيينها للصفحة الحالية.

 # Cookies are loaded from cookies.yml
page . cookies . load # => true 

الرؤوس

page.headers

الحصول على: Hash

احصل على جميع الرؤوس

مجموعة (رؤوس): Boolean

تعيين رؤوس معينة. في نهاية المطاف مسح جميع الرؤوس وضبطها.

• رؤوس Headers Hash -Halue-vairs على سبيل المثال "User-Agent" => "Browser"

إضافة (رؤوس): Boolean

يضيف الرؤوس المعطاة لضبطها بالفعل.

• رؤساء Headers Hash -key-vairs ، على سبيل المثال "Referer" => "http://example.com"

واضح: Boolean

امسح جميع الرؤوس.

جافا سكريبت

تقييم (التعبير ، *args)

تقييم ونتيجة العودة للتعبير JS المعطى

• يجب أن تكون String التعبير صالحة JavaScript
• Object args يمكنك تمرير الوسائط ، على الرغم من أنها يجب أن تكون Node صالحة أو قيمة بسيطة.

 page . evaluate ( "[window.scrollX, window.scrollY]" ) 

تقييم _async (التعبير ، wait_time ، *args)

تقييم التعبير غير المتزامن ونتيجة الإرجاع

• يجب أن تكون String التعبير صالحة JavaScript
• WAIT_TIME كم من الوقت يجب أن ننتظر وحد الوعد أو رفضه
• Object args يمكنك تمرير الوسائط ، على الرغم من أنها يجب أن تكون Node صالحة أو قيمة بسيطة.

 page . evaluate_async ( %(arguments[0]({foo: "bar"})) , 5 ) # => { "foo" => "bar" } 

تنفيذ (التعبير ، *args)

تنفيذ التعبير. لا يعيد النتيجة

• يجب أن تكون String التعبير صالحة JavaScript
• Object args يمكنك تمرير الوسائط ، على الرغم من أنها يجب أن تكون Node صالحة أو قيمة بسيطة.

 page . execute ( %(1 + 1) ) # => true 

تقييم _on_new_document (التعبير)

تقييم JavaScript لتعديل الأشياء قبل تحميل الصفحة

• يجب أن تكون String التعبير صالحة JavaScript

 browser . evaluate_on_new_document <<~JS
  Object.defineProperty(navigator, "languages", {
    get: function() { return ["tlh"]; }
  });
JS 

add_script_tag (** خيارات): Boolean

• خيارات Hash
  • : String URL
  • : String المسار
  • : String المحتوى
  • : اكتب String - text/javascript افتراضيًا

 page . add_script_tag ( url : "http://example.com/stylesheet.css" ) # => true 

add_style_tag (** خيارات): Boolean

• خيارات Hash
  • : String URL
  • : String المسار
  • : String المحتوى

 page . add_style_tag ( content : "h1 { font-size: 40px; }" ) # => true 

bypass_csp (** خيارات): Boolean

• خيارات Hash
  • : ممكّن Boolean ، true بشكل افتراضي

 page . bypass_csp # => true
page . go_to ( "https://github.com/ruby-concurrency/concurrent-ruby/blob/master/docs-source/promises.in.md" )
page . refresh
page . add_script_tag ( content : "window.__injected = 42" )
page . evaluate ( "window.__injected" ) # => 42 

مضاهاة

Disable_JavaScript

يعطل JavaScripts من مصدر HTML المحملة. لا يزال بإمكانك تقييم JavaScript مع evaluate أو execute . لا يعيد أي شيء.

 page . disable_javascript 

set_viewport

يتجاوز أبعاد شاشة الجهاز ويحاكي منفذ العرض.

• خيارات Hash
  • : Integer العرض ، عرض المنفذ. 0 بشكل افتراضي
  • : Integer الارتفاع ، ارتفاع المنفذ. 0 بشكل افتراضي
  • : Scale_Factor Float ، عامل مقياس الجهاز. 0 بشكل افتراضي
  • : Mobile Boolean ، سواء لمحاكاة الأجهزة المحمولة. false بشكل افتراضي

 page . set_viewport ( width : 1000 , height : 600 , scale_factor : 3 ) 

إطارات

الإطارات: Array[Frame] | []

إرجاع جميع الإطارات التي تحتوي عليها الصفحة الحالية.

 page . go_to ( "https://www.w3schools.com/tags/tag_frame.asp" )
page . frames # =>
# [
#   #<Ferrum::Frame @id="C6D104CE454A025FBCF22B98DE612B12" @parent_id=nil @name=nil @state=:stopped_loading @execution_id=1>,
#   #<Ferrum::Frame @id="C09C4E4404314AAEAE85928EAC109A93" @parent_id="C6D104CE454A025FBCF22B98DE612B12" @state=:stopped_loading @execution_id=2>,
#   #<Ferrum::Frame @id="2E9C7F476ED09D87A42F2FEE3C6FBC3C" @parent_id="C6D104CE454A025FBCF22B98DE612B12" @state=:stopped_loading @execution_id=3>,
#   ...
# ] 

main_frame: Frame

إرجاع الإطار الرئيسي للصفحة ، الجزء العلوي من الشجرة والوالد لجميع الإطارات.

Frame_by (** خيارات): Frame | nil

ابحث عن الإطار من خلال خيارات معينة.

• خيارات Hash
  • : id String - معرف الإطار الفريد الذي يوفره المتصفح
  • : اسم String - اسم الإطار إذا كان هناك واحد

 page . frame_by ( id : "C6D104CE454A025FBCF22B98DE612B12" ) 

إطار

معرف: String

معرف الإطار الفريد.

Parent_id: String | nil

معرف إطار الوالدين إذا كان هذا متداخلًا في واحد آخر.

execution_id: Integer

معرف سياق التنفيذ الذي يستخدمه JS ، يحتوي كل إطار على سياق خاص به يقييم فيه JS.

الاسم: String | nil

إذا تم إعطاء الإطار اسمًا ، فيجب أن يكون هنا.

الدولة: Symbol | nil

إحدى إطار الدول في:

• :started_loading
• :navigated
• :stopped_loading

عنوان URL: String

إرجاع موقع الإطار الحالي HREF.

 page . go_to ( "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe" )
frame = page . frames [ 1 ]
frame . url # => https://interactive-examples.mdn.mozilla.net/pages/tabbed/iframe.html 

عنوان

إرجاع عنوان الإطار الحالي.

 page . go_to ( "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe" )
frame = page . frames [ 1 ]
frame . title # => HTML Demo: <iframe> 

رئيسي؟ : Boolean

إذا كان الإطار الحالي هو الإطار الرئيسي للصفحة (أعلى الشجرة).

 page . go_to ( "https://www.w3schools.com/tags/tag_frame.asp" )
frame = page . frame_by ( id : "C09C4E4404314AAEAE85928EAC109A93" )
frame . main? # => false 

Current_url: String

إرجاع موقع النافذة العليا للإطار الحالي.

 page . go_to ( "https://www.w3schools.com/tags/tag_frame.asp" )
frame = page . frame_by ( id : "C09C4E4404314AAEAE85928EAC109A93" )
frame . current_url # => "https://www.w3schools.com/tags/tag_frame.asp" 

Current_title: String

إرجاع عنوان النافذة الأعلى للإطار الحالي.

 page . go_to ( "https://www.w3schools.com/tags/tag_frame.asp" )
frame = page . frame_by ( id : "C09C4E4404314AAEAE85928EAC109A93" )
frame . current_title # => "HTML frame tag" 

الجسم: String

إرجاع HTML الإطار الحالي.

 page . go_to ( "https://www.w3schools.com/tags/tag_frame.asp" )
frame = page . frame_by ( id : "C09C4E4404314AAEAE85928EAC109A93" )
frame . body # => "<html><head></head><body></body></html>" 

Doctype

إرجاع doctype الإطار الحالي.

 page . go_to ( "https://www.w3schools.com/tags/tag_frame.asp" )
page . main_frame . doctype # => "<!DOCTYPE html>" 

المحتوى = html

يضع محتوى من إطار معين.

• String

 page . go_to ( "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe" )
frame = page . frames [ 1 ]
frame . body # <html lang="en"><head><style>body {transition: opacity ease-in 0.2s; }...
frame . content = "<html><head></head><body><p>lol</p></body></html>"
frame . body # => <html><head></head><body><p>lol</p></body></html> 

مربعات الحوار

قبول (نص)

قبول مربع الحوار بنص معين أو موجه افتراضي إذا كان ذلك ممكنًا

• String نص

رفض

رفض الحوار

 page . on ( :dialog ) do | dialog |
  if dialog . match? ( /bla-bla/ )
    dialog . accept
  else
    dialog . dismiss
  end
end
page . go_to ( "https://google.com" ) 

الرسوم المتحركة

يمكنك إبطاء أو تسريع الرسوم المتحركة CSS.

playback_rate: Integer

إرجاع معدل التشغيل للرسوم المتحركة CSS ، الافتراضيات إلى 1 .

playback_rate = القيمة

يحدد معدل تشغيل الرسوم المتحركة CSS

• Integer القيمة

 page . playback_rate = 2000
page . go_to ( "https://google.com" )
page . playback_rate # => 2000 

العقدة

العقدة؟ : Boolean

frame_id

الإطار: Frame

إرجاع كائن الإطار للعقدة الحالية ، يمكنك الاستمرار في استخدام الباحثين لهذا الكائن:

 frame =  page . at_xpath ( "//iframe" ) . frame # => Frame
frame . at_css ( "//a[text() = 'Log in']" ) # => Node 

ركز

قابلة للتركيز؟

تتحرك؟ : Boolean

wait_for_stop_moving

طمس

يكتب

انقر

تحوم

select_file

AT_XPATH

AT_CSS

xpath

CSS

نص

inner_text

قيمة

ملكية

يصف

يقيم

محدد: Array<Node>

يختار

scroll_into_view

in_viewport؟ (من: Node | nil ): Boolean

يزيل

موجود؟

(سلسلة قابلة للسلسلة) يختار الخيارات بواسطة سمة تم تمريرها.

 page . at_xpath ( "//*[select]" ) . select ( [ "1" ] ) # => Node (select)
page . at_xpath ( "//*[select]" ) . select ( [ "text" ] , by : :text ) # => Node (select)

قبول السلسلة أو المصفوفة أو السلاسل:

 page . at_xpath ( "//*[select]" ) . select ( "1" )
page . at_xpath ( "//*[select]" ) . select ( "1" , "2" )
page . at_xpath ( "//*[select]" ) . select ( [ "1" , "2" ] ) 

تتبع

يمكنك استخدام tracing.record لإنشاء ملف تتبع يمكن فتحه في Chrome DevTools أو عارض الجدول الزمني.

 page . tracing . record ( path : "trace.json" ) do
  page . go_to ( "https://www.google.com" )
end 

Tracing.Record (** خيارات): String

يقبل Block و Trace Trace و Default بإرجاع بيانات Trace من Tracing.tracingComplete كإخراج. عند تحديد path ، يُرجع true ويخزن بيانات تتبع في ملف.

• خيارات Hash
  • : String المسار حفظ البيانات على القرص ، nil افتراضيا
  • : Symbol الترميز :base64 | :binary الإخراج كـ BASE64 أو نص عادي. :binary بشكل افتراضي
  • : Timeout Float انتظر حتى ينتهي تدفق الملف في الوقت المحدد أو رفع الخطأ ، الافتراضيات إلى nil
  • : لقطات الشاشة لقطات التقاط Boolean في التتبع ، false بشكل افتراضي
  • : trace_config Hash<String, Object> config for trace ، للاطلاع على الفئات ، انظر GetCategories ، يمكن أن يكون تكوين تتبع واحد فقط نشطًا في وقت لكل متصفح.

تنظيف

إعادة ضبط

يغلق علامات تبويب المتصفح التي تم فتحها بواسطة مثيل Browser .

 # connect to a long-running Chrome process
browser = Ferrum :: Browser . new ( url : 'http://localhost:9222' )

browser . go_to ( "https://github.com/" )

# clean up, lest the tab stays there hanging forever
browser . reset

browser . quit 

السلامة الموضوع

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

 browser = Ferrum :: Browser . new
context = browser . contexts . create

t1 = Thread . new ( context ) do | c |
  page = c . create_page
  page . go_to ( "https://www.google.com/search?q=Ruby+headless+driver+for+Capybara" )
  page . screenshot ( path : "t1.png" )
end

t2 = Thread . new ( context ) do | c |
  page = c . create_page
  page . go_to ( "https://www.google.com/search?q=Ruby+static+typing" )
  page . screenshot ( path : "t2.png" )
end

t1 . join
t2 . join

context . dispose
browser . quit

أو يمكنك إنشاء سياقين مستقلين:

 browser = Ferrum :: Browser . new

t1 = Thread . new ( browser ) do | b |
  context = b . contexts . create
  page = context . create_page
  page . go_to ( "https://www.google.com/search?q=Ruby+headless+driver+for+Capybara" )
  page . screenshot ( path : "t1.png" )
  context . dispose
end

t2 = Thread . new ( browser ) do | b |
  context = b . contexts . create
  page = context . create_page
  page . go_to ( "https://www.google.com/search?q=Ruby+static+typing" )
  page . screenshot ( path : "t2.png" )
  context . dispose
end

t1 . join
t2 . join

browser . quit 

تطوير

بعد التحقق من الريبو ، قم bundle install قم بتثبيت التبعيات.

ثم ، قم بتشغيل bundle exec rake test لتشغيل الاختبارات. يمكنك أيضًا تشغيل bin/console للحصول على مطالبة تفاعلية تتيح لك التجربة.

لتثبيت هذه الأحجار الكريمة على جهازك المحلي ، قم بتشغيل bundle exec rake install . لإصدار إصدار جديد ، قم بتحديث رقم الإصدار في version.rb ، ثم قم بتشغيل bundle exec rake release ، والذي سيقوم بإنشاء علامة GIT للإصدار ، و Commit Git Commits والعلامة التي تم إنشاؤها ، ودفع ملف .gem إلى rubygems.org.

المساهمة

تقارير الأخطاء وطلبات السحب هي موضع ترحيب على جيثب.

رخصة

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