cuprite 0.18 → 0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed2641aa002e810fd4dfedc8b3128f38e5f2df0f747d59bc1cf7a81aa1295076
-  data.tar.gz: 7e967cb1a6a11ad9f446290cd5035d2d5d3e9c6724ba6f4df4c31e761b29545d
+  metadata.gz: 159c7e6289accaf81577a8549e3e1447ea90e0f99694b91547704fef206b8c56
+  data.tar.gz: 1b70f9e72fbdd0a089d45229ecb12604d655a782ca2a10b358220b66865e5d09
 SHA512:
-  metadata.gz: dcee409e8ee24caf139c3a0c29318ccea5ddefb0759f228f0f24db76aef28864c73d46e02ecc820160e82d6f366c61648ad1dc20dd930b5d9f300c8853d17003
-  data.tar.gz: 5168b1c18e81936795a02154829100dc3a616c2d2c3db71c134c8e64f5f13d93fd1098e8c26aea8d84a26840bf547a80b263b63b293420dc9f18cc18a5d29632
+  metadata.gz: dac1cb17193f518ce4e276c2580d02118e9a1cce86737c8e0b501c2747a438b89dfda2ed2eb5b66b23e4a92fa7d30c53cbb991ae172358fbbb12531fd441a777
+  data.tar.gz: f9758427a804d2dc3ecda09610598fa2a22389f520789800fc5b71bf60f5cef9be01a48a464610a1200914ab4f005ca71634557f9b113586c594097a0c592884

data/README.md

@@ -1,5 +1,12 @@
 # Cuprite - Headless Chrome driver for Capybara
 
+## [Documentation](https://docs.rubycdp.com/docs/cuprite/introduction)
+
+<img align="right"
+     width="160" height="160"
+     alt="Cuprite logo"
+     src="https://raw.githubusercontent.com/rubycdp/cuprite/main/logo.svg?sanitize=true">
+
 Cuprite is a pure Ruby driver (read as _no_ Selenium/WebDriver/ChromeDriver
 dependency) for [Capybara](https://github.com/teamcapybara/capybara). It allows
 you to run Capybara tests on a headless Chrome or Chromium. Under the hood it
@@ -7,6 +14,8 @@ uses [Ferrum](https://github.com/rubycdp/ferrum#index) which is high-level API
 to the browser by CDP protocol.
 
 
+<br clear="right">
+
 ## Install
 
 Add this to your `Gemfile` and run `bundle install`.
@@ -49,7 +58,8 @@ because Docker is involved. Prefer running the browser as a non-root user with
 a working sandbox when possible.
 
 Since Cuprite uses [Ferrum](https://github.com/rubycdp/ferrum#examples) there
-are many useful methods you can call even using this driver:
+are many useful methods you can call even using this driver.
+`page.driver.browser` is a `Ferrum::Browser`:
 
 ```ruby
 browser = page.driver.browser
@@ -84,7 +94,18 @@ end
     timer) only surfaces on whatever command runs next.
   * `:url_blacklist` (Array) - array of regexes to match against requested URLs
   * `:url_whitelist` (Array) - array of regexes to match against requested URLs
+  * `:emulate` (Symbol) - device from Chrome DevTools' list to emulate, e.g. `:iphone_16`, `:pixel_9`, `:ipad_mini`
+  * `:mobile` (Boolean) - emulate a mobile device: viewport meta tag and touch events
+  * `:scale_factor` (Numeric) - device scale factor to emulate
 
+`emulate:` sets the device's `:window_size`, `:scale_factor`, `:mobile` and user agent, options passed explicitly
+take precedence:
+
+```ruby
+Capybara.register_driver(:cuprite) do |app|
+  Capybara::Cuprite::Driver.new(app, emulate: :iphone_14)
+end
+```
 
 ## Debugging
 
@@ -109,35 +130,35 @@ opened where you can further experiment with the test.
 
 ## Clicking/Scrolling
 
-* `page.driver.click(x, y)` Click a very specific area of the screen.
-* `page.driver.scroll_to(left, top)` Scroll to a given position.
+* `page.driver.browser.mouse.click(x:, y:)` Click a very specific area of the screen.
+* `page.scroll_to(left, top)` Scroll to a given position.
 * `element.send_keys(*keys)` Send keys to a given node.
 
 
 ## Request headers
 
-Manipulate HTTP request headers like a boss:
+Manipulate HTTP request headers with Ferrum:
 
 ``` ruby
-page.driver.headers # => {}
-page.driver.headers = { "User-Agent" => "Cuprite" }
-page.driver.add_headers("Referer" => "https://example.com")
-page.driver.headers # => { "User-Agent" => "Cuprite", "Referer" => "https://example.com" }
+page.driver.browser.headers.get # => {}
+page.driver.browser.headers.set("User-Agent" => "Cuprite")
+page.driver.browser.headers.add({ "Referer" => "https://example.com" })
+page.driver.browser.headers.get # => { "User-Agent" => "Cuprite", "Referer" => "https://example.com" }
 ```
 
-Notice that `headers=` will overwrite already set headers. You should use
-`add_headers` if you want to add a few more. These headers will apply to all
-subsequent HTTP requests (including requests for assets, AJAX, etc). They will
-be automatically cleared at the end of the test.
+Notice that `set` will overwrite already set headers. You should use `add` if
+you want to add a few more. These headers will apply to all subsequent HTTP
+requests (including requests for assets, AJAX, etc). They will be automatically
+cleared at the end of the test.
 
 
 ## Network traffic
 
-* `page.driver.network_traffic` allows you to inspect network traffic (i.e., loaded resources) on the current page. It returns an array of `Ferrum::Network::Exchange` objects, each representing a network request/response exchange. You can query both the request and response details of each exchange.
+* `page.driver.browser.network.traffic` allows you to inspect network traffic (i.e., loaded resources) on the current page. It returns an array of `Ferrum::Network::Exchange` objects, each representing a network request/response exchange. You can query both the request and response details of each exchange.
 
 ```ruby
 # Retrieve all network exchanges
-network_traffic = page.driver.network_traffic
+network_traffic = page.driver.browser.network.traffic
 
 # Access the first exchange
 first_exchange = network_traffic.first
@@ -146,22 +167,22 @@ first_exchange = network_traffic.first
 response = first_exchange.response
 ```
 
-* `page.driver.wait_for_network_idle` Natively waits for network idle and if
-there are no active connections returns or raises `TimeoutError` error. Accepts
-the same options as
+* `page.driver.browser.network.wait_for_idle` Natively waits for network idle
+and returns `false` if there are still active connections after timeout.
+Accepts the same options as
 [`wait_for_idle`](https://github.com/rubycdp/ferrum#wait_for_idleoptions)
 
 ```ruby
-page.driver.wait_for_network_idle
+page.driver.browser.network.wait_for_idle
 page.driver.refresh
 ```
 
 Please note that network traffic is not cleared when you visit new page. You can
-manually clear the network traffic by calling `page.driver.clear_network_traffic`
-or `page.driver.reset`
+manually clear the network traffic by calling
+`page.driver.browser.network.clear(:traffic)` or `page.driver.reset!`
 
-* `page.driver.wait_for_reload` unlike `wait_for_network_idle` will wait until
-the whole page is reloaded or raise a timeout error. It's useful when you know
+* `page.driver.browser.wait_for_reload` unlike `network.wait_for_idle` will wait until
+the whole page is reloaded or the timeout passes. It's useful when you know
 that for example after clicking autocomplete suggestion you expect page to be
 reloaded, you have a few choices - put sleep or wait for network idle, but both
 are bad. Sleep makes you wait longer or less than needed, network idle can
@@ -171,34 +192,45 @@ rescue.
 
 ## Manipulating cookies
 
-The following methods are used to inspect and manipulate cookies:
+Use Ferrum's cookies to inspect and manipulate cookies:
 
-* `page.driver.cookies` - a hash of cookies accessible to the current
-  page. The keys are cookie names. The values are `Cookie` objects, with
-  the following methods: `name`, `value`, `domain`, `path`, `size`, `secure?`,
-  `httponly?`, `session?`, `expires`.
-* `page.driver.set_cookie(name, value, options = {})` - set a cookie.
-  The options hash can take the following keys: `:domain`, `:path`,
-  `:secure`, `:httponly`, `:expires`. `:expires` should be a
-  `Time` object.
-* `page.driver.remove_cookie(name)` - remove a cookie
-* `page.driver.clear_cookies` - clear all cookies
+```ruby
+cookies = page.driver.browser.cookies
+cookies.set(name: "stealth", value: "omg")
+cookies["stealth"].value # => "omg"
+cookies.all # => { "stealth" => #<Ferrum::Cookies::Cookie ...> }
+cookies.remove(name: "stealth")
+cookies.clear
+```
 
 
 ## Screenshot
 
-Besides capybara screenshot method you can get image as Base64:
+Besides capybara screenshot method you can get image or PDF as Base64 with Ferrum:
 
-* `page.driver.render_base64(format, options)`
+```ruby
+page.driver.browser.screenshot(format: :jpeg, full: true)
+page.driver.browser.pdf(paper_width: 6, paper_height: 12)
+```
 
 
 ## Authorization
 
-* `page.driver.basic_authorize(user, password)`
+* `page.driver.browser.network.authorize(user:, password:) { |request, _index, _total| request.continue }`
 
 ## Proxy
 
-* `page.driver.set_proxy(ip, port, user, password)`
+```ruby
+Capybara::Cuprite::Driver.new(app, proxy: { host: "127.0.0.1", port: 8080, user: "user", password: "password" })
+```
+
+The proxy is passed to Chrome as a command-line flag when the browser starts.
+
+When connecting to a remote browser with the `:url` option (browserless, Selenoid, etc.), Cuprite doesn't launch
+Chrome and the proxy flag is never applied, so configure the proxy on the remote browser itself. The `user` and
+`password` are still used to answer the proxy's authentication challenge.
+
+The `bypass` option is a list of hosts that skip the proxy, so don't pass the host you want to go through it.
 
 
 ## URL Blocklisting & Allowlisting

data/lib/capybara/cuprite/browser/deprecations.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "capybara/cuprite/deprecation"
+
+module Capybara
+  module Cuprite
+    class Browser < Ferrum::Browser
+      module Deprecations
+        def visit(*args)
+          Cuprite.deprecation_warning("#{self.class}#visit", "use #goto")
+          goto(*args)
+        end
+
+        def status_code
+          Cuprite.deprecation_warning("#{self.class}#status_code", "use #network.status")
+          network.status
+        end
+
+        def window_handle
+          Cuprite.deprecation_warning("#{self.class}#window_handle", "use #current_window_handle")
+          current_window_handle
+        end
+      end
+    end
+  end
+end

data/lib/capybara/cuprite/browser/extensions.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Cuprite
+    class Browser < Ferrum::Browser
+      module Extensions
+        def raise_on_unhandled_modal
+          @options.raise_on_unhandled_modal
+        end
+
+        def raise_on_unhandled_modal=(value)
+          @options.raise_on_unhandled_modal = value
+        end
+
+        def url_whitelist
+          @options.url_whitelist
+        end
+        alias url_allowlist url_whitelist
+
+        def url_whitelist=(patterns)
+          @options.url_whitelist = prepare_wildcards(patterns)
+          page.network.whitelist = @options.url_whitelist if @client && @options.url_whitelist.any?
+        end
+        alias url_allowlist= url_whitelist=
+
+        def url_blacklist
+          @options.url_blacklist
+        end
+        alias url_blocklist url_blacklist
+
+        def url_blacklist=(patterns)
+          @options.url_blacklist = prepare_wildcards(patterns)
+          page.network.blacklist = @options.url_blacklist if @client && @options.url_blacklist.any?
+        end
+        alias url_blocklist= url_blacklist=
+
+        private
+
+        def prepare_wildcards(patterns)
+          string_passed = false
+
+          Array(patterns).map do |pattern|
+            if pattern.is_a?(Regexp)
+              pattern
+            else
+              string_passed = true
+              pattern = pattern.gsub("*", ".*")
+              Regexp.new(pattern, Regexp::IGNORECASE)
+            end
+          end
+        ensure
+          if string_passed
+            warn "Passing strings to blacklist/whitelist is deprecated, pass regexp at #{caller(4..4).first}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capybara/cuprite/browser.rb

@@ -1,19 +1,17 @@
 # frozen_string_literal: true
 
-require "forwardable"
+require "capybara/cuprite/browser/deprecations"
+require "capybara/cuprite/browser/extensions"
 
 module Capybara
   module Cuprite
     class Browser < Ferrum::Browser
-      extend Forwardable
-
-      DRAG_HTML5_JS = File.read(File.expand_path("javascripts/drag.js", __dir__))
-
-      delegate %i[send_keys select set hover trigger before_click switch_to_frame
-                  find_modal accept_confirm dismiss_confirm accept_prompt
-                  dismiss_prompt reset_modals] => :page
+      include Deprecations
+      include Extensions
 
       def initialize(options = nil)
+        device = options&.dig(:emulate)
+        options = Devices.fetch(device).except(:user_agent).merge(options) if device
         super
 
         @options.raise_on_unhandled_modal = options&.dig(:raise_on_unhandled_modal)
@@ -31,20 +29,21 @@ module Capybara
       end
 
       def page
-        raise Ferrum::NoSuchPageError if @page&.closed?
+        raise Ferrum::NoSuchPageError if @page_closed
 
         @page ||= attach_page
       end
 
       def reset
         super
+      ensure
         @options.reset_window_size
-        @page = nil
+        forget_page
       end
 
       def quit
         super
-        @page = nil
+        forget_page
       end
 
       def resize(**options)
@@ -52,249 +51,47 @@ module Capybara
         super
       end
 
-      def raise_on_unhandled_modal
-        @options.raise_on_unhandled_modal
-      end
-
-      def raise_on_unhandled_modal=(value)
-        @options.raise_on_unhandled_modal = value
-      end
-
-      def url_whitelist
-        @options.url_whitelist
-      end
-      alias url_allowlist url_whitelist
-
-      def url_whitelist=(patterns)
-        @options.url_whitelist = prepare_wildcards(patterns)
-        page.network.whitelist = @options.url_whitelist if @client && @options.url_whitelist.any?
-      end
-      alias url_allowlist= url_whitelist=
-
-      def url_blacklist
-        @options.url_blacklist
-      end
-      alias url_blocklist url_blacklist
-
-      def url_blacklist=(patterns)
-        @options.url_blacklist = prepare_wildcards(patterns)
-        page.network.blacklist = @options.url_blacklist if @client && @options.url_blacklist.any?
-      end
-      alias url_blocklist= url_blacklist=
-
-      def visit(*args)
-        goto(*args)
-      end
-
-      def status_code
-        network.status
-      end
-
-      def find(method, selector)
-        find_all(method, selector)
-      end
-
-      def property(node, name)
-        node.property(name)
-      end
-
-      def find_within(node, method, selector)
-        resolved = page.command("DOM.resolveNode", nodeId: node.node_id)
-        object_id = resolved.dig("object", "objectId")
-        find_all(method, selector, { "objectId" => object_id })
-      end
-
-      def window_handle
+      def current_window_handle
         page.target_id
       end
 
       def window_handles
-        targets.keys
+        targets.values.select(&:page?).map(&:id)
       end
 
-      def within_window(locator = nil)
-        original = window_handle
-        raise Ferrum::NoSuchPageError unless window_handles.include?(locator)
-
-        switch_to_window(locator)
-        yield
-      ensure
-        switch_to_window(original)
+      def open_new_window
+        attach_page(default_context.create_target.id)
       end
 
       def switch_to_window(target_id)
-        target = targets[target_id]
-        raise Ferrum::NoSuchPageError unless target
-
+        target = window_target(target_id)
+        forget_page
         @page = attach_page(target.id)
         @page.activate
       end
 
       def close_window(target_id)
-        target = targets[target_id]
-        raise Ferrum::NoSuchPageError unless target
-
-        @page = ClosedPage.new if @page.target_id == target.id
+        target = window_target(target_id)
+        if @page&.target_id == target.id
+          forget_page
+          @page_closed = true
+        end
         target.page.close
         targets.delete(target_id) # page.close is async, delete target asap
       end
 
-      def active_element
-        evaluate("document.activeElement")
-      end
-
-      def browser_error
-        evaluate("_cuprite.browserError()")
-      end
-
-      def source
-        raise NotImplementedError
-      end
-
-      def drag(node, other, drop_modifiers, options = {})
-        steps = options.fetch(:steps, 1)
-        delay = options[:delay]
-        scroll = options.fetch(:scroll, true)
-        html5 = options[:html5]
-
-        execute("_cuprite.dragMousedownTracker()")
-
-        node.scroll_into_view if scroll
-        x1, y1 = node.find_position
-
-        mouse.move(x: x1, y: y1)
-        mouse.down
-        sleep delay if delay
-
-        html5 = !evaluate_on(node: node, expression: "_cuprite.legacyDragCheck(this)") if html5.nil?
-
-        if html5
-          drag_html5(node, other, drop_modifiers, delay)
-        else
-          modifiers = keyboard.modifiers(drop_modifiers)
-
-          other.scroll_into_view if scroll
-          x2, y2 = other.find_position
-          mouse.move(x: x2, y: y2, steps: steps)
-
-          mouse.up(modifiers: modifiers)
-        end
-      end
-
-      def drag_html5(node, other, drop_modifiers, delay)
-        keys = drop_modifiers.map(&:to_s)
-        evaluate_async(DRAG_HTML5_JS, timeout, node, other, (delay || 0.05) * 1000, keys)
-        mouse.up
-      end
-
-      def drag_by(node, dx, dy, steps, delay = nil, scroll = true)
-        x1, y1 = node.find_position
-
-        mouse.move(x: x1, y: y1)
-        mouse.down
-
-        sleep delay if delay
-
-        evaluate("window.scrollBy(#{dx}, #{dy})") if scroll # should be extracted to Mouse#scroll_by in ferrum
-
-        x2, y2 = node.find_position
-        mouse.move(x: x2 + dx, y: y2 + dy, steps: steps)
-        mouse.up
-      end
-
-      def drop(node, *args)
-        if args[0].is_a?(String)
-          execute("_cuprite.attachDropInput()")
-          input = find(:css, "#_cuprite_drop_file").first
-          select_file(input, args)
-          evaluate_on(node: node, expression: "_cuprite.dropFile(this)")
-        else
-          strings = args.flat_map { |arg| arg.map { |type, data| { "type" => type, "data" => data } } }
-          evaluate_on(node: node, expression: "_cuprite.dropString(#{strings.to_json}, this)")
-        end
-      end
-
-      def select_file(node, value)
-        node.select_file(value)
-      end
-
-      def parents(node)
-        evaluate_on(node: node, expression: "_cuprite.parents(this)", by_value: false)
-      end
-
-      def visible_text(node)
-        evaluate_on(node: node, expression: "_cuprite.visibleText(this)")
-      end
-
-      def delete_text(node)
-        evaluate_on(node: node, expression: "_cuprite.deleteText(this)")
-      end
-
-      def attributes(node)
-        value = evaluate_on(node: node, expression: "_cuprite.getAttributes(this)")
-        JSON.parse(value)
-      end
-
-      def attribute(node, name)
-        evaluate_on(node: node, expression: %(_cuprite.getAttribute(this, "#{name}")))
-      end
-
-      def value(node)
-        evaluate_on(node: node, expression: "_cuprite.value(this)")
-      end
-
-      def visible?(node)
-        evaluate_on(node: node, expression: "_cuprite.isVisible(this)")
-      end
-
-      def disabled?(node)
-        evaluate_on(node: node, expression: "_cuprite.isDisabled(this)")
-      end
-
-      def path(node)
-        evaluate_on(node: node, expression: "_cuprite.path(this)")
-      end
-
-      def obscured?(node)
-        evaluate_on(node: node, expression: "_cuprite.isObscured(this)")
-      end
-
-      def all_text(node)
-        node.text
-      end
-
       private
 
-      def find_all(method, selector, within = nil)
-        nodes = if within
-                  evaluate("_cuprite.find(arguments[0], arguments[1], arguments[2])", method, selector, within)
-                else
-                  evaluate("_cuprite.find(arguments[0], arguments[1])", method, selector)
-                end
-
-        nodes.select(&:node?)
-      rescue Ferrum::JavaScriptError => e
-        raise InvalidSelector.new(e.response, method, selector) if e.class_name == "InvalidSelector"
-
-        raise
+      def forget_page
+        @page = nil
+        @page_closed = false
       end
 
-      def prepare_wildcards(patterns)
-        string_passed = false
+      def window_target(target_id)
+        target = targets[target_id]
+        raise Ferrum::NoSuchPageError unless target&.page?
 
-        Array(patterns).map do |pattern|
-          if pattern.is_a?(Regexp)
-            pattern
-          else
-            string_passed = true
-            pattern = pattern.gsub("*", ".*")
-            Regexp.new(pattern, Regexp::IGNORECASE)
-          end
-        end
-      ensure
-        if string_passed
-          warn "Passing strings to blacklist/whitelist is deprecated, pass regexp at #{caller(4..4).first}"
-        end
+        target
       end
 
       def attach_page(target_id = nil)

data/lib/capybara/cuprite/deprecation.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Cuprite
+    REMOVE_DEPRECATED_IN = "0.21"
+
+    def self.deprecation_warning(method, advice = nil)
+      message = "#{method} is deprecated and will be removed in #{REMOVE_DEPRECATED_IN}"
+      message += ", #{advice} instead" if advice
+      warn message, uplevel: 2
+    end
+  end
+end