cuprite 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 117f25092d57e0e61feeec4d161d3b9da6cdde4ea6963e624dca22af48de75fa
-  data.tar.gz: aae39fa9139563a5870e66be1d564c69136df2e7d73c72ff744edf4bb5cccc8a
+  metadata.gz: 07b0203f3647868b796a4649f28e2ed0a549412156e08a3ef50e83625acaca11
+  data.tar.gz: 9854d6126698f53691c30b04c9a8677f24091c76720227ceb474101dab06a475
 SHA512:
-  metadata.gz: f77ad45ba3abe3a1a4dec994566cbf1d0ab0c7364fbc879bf89583e1602a5a5c16da3cc1d6e1d6b8c2b5eee601409d1c8cf31f291f01cc83217f495ae313e56a
-  data.tar.gz: 2a976e8a5ece9441ba281b2521c43cf8ed209258bbb386254539341157dad7245933292458c7ccb7a1f019119b2334d15f3c68fb0d9af9df0061f74879d62cfb
+  metadata.gz: 2fe300cdefbb2a2c7d09d37329ab7a31dcf2d7cda9177ffafc91bdec2923fabf24c933f6894e5e959bdb6218e03ac9211afedb7ae588ae97f87d7142fb249e7c
+  data.tar.gz: ede07bd3d885c5e711a80a6698d10ad28d855d7b6917f10ebc2cfe0153fde5af261ef553cdee62ad3a6cabdacfee659e12d13b95ebc8c2470d4d4b33772ad5be

data/README.md

@@ -5,59 +5,97 @@
 Cuprite is a pure Ruby driver (read as _no_ Java/Selenium/WebDriver/ChromeDriver
 requirement) for [Capybara](https://github.com/teamcapybara/capybara). It allows
 you to run your Capybara tests on a headless [Chrome](https://www.google.com/chrome/)
-or [Chromium](https://www.chromium.org/) browser by [CDP protocol](https://chromedevtools.github.io/devtools-protocol/).
+or [Chromium](https://www.chromium.org/) by [CDP protocol](https://chromedevtools.github.io/devtools-protocol/).
+Under the hood it uses [Ferrum](https://github.com/route/ferrum) which is
+high-level API to the browser again by CDP protocol.
 
 The emphasis was made on raw CDP protocol because Headless Chrome allows you to
-do so many cool things that are barely supported by WebDriver because it should
-have consistent design with other browsers. The design of the driver will be as
+do so many things that are barely supported by WebDriver because it should have
+consistent design with other browsers. The design of the driver will be as
 close to [Poltergeist](https://github.com/teampoltergeist/poltergeist) as
-possible but it's not a goal.
+possible though it's not a goal.
 
-## Installation ##
+## Install ##
+
+Add these lines to your `Gemfile` and run `bundle install`.
 
 ``` ruby
-gem "cuprite"
+gem "cuprite", group: :test
 ```
 
-and run `bundle install`.
-
 In your test setup add:
 
 ``` ruby
 require "capybara/cuprite"
 Capybara.javascript_driver = :cuprite
+Capybara.register_driver(:cuprite) do |app|
+  Capybara::Cuprite::Driver.new(app, window_size: [1200, 800])
+end
 ```
 
-## Installing Chromium ##
+If you already had tests on Poltergeist then it should simply work, for Selenium
+you better check your code for `.manage` calls because things are much easier
+with Cuprite, see the documentation below.
 
-As Chromium is stopped being built as a package for Linux don't even try to
-install it this way because it will either be outdated or unofficial package.
-Both are bad. Download it from official [source](https://www.chromium.org/getting-involved/download-chromium).
+## Install Chrome ##
 
-## Supported features ##
+There's no official Chrome or Chromium package for Linux don't install it this
+way because it either will be outdated or unofficial, both are bad. Download it
+from official [source](https://www.chromium.org/getting-involved/download-chromium).
+Chrome binary should be in the `PATH` or `BROWSER_PATH` or you can pass it as an
+option
 
-All the mandatory capybara features plus optional ones:
+## Customization ##
 
-* `page.evaluate_script` and `page.execute_script`
-* `page.within_frame`
-* `page.status_code`
-* `page.response_headers`
-* `page.save_screenshot`
-* `page.driver.render_base64(format, options)`
-* `page.driver.scroll_to(left, top)`
-* `page.driver.basic_authorize(user, password)`
-* `element.send_keys(*keys)`
-* `page.driver.set_proxy(ip, port, type, user, password)`
-* window API
-* cookie handling
+You can customize options with the following code in your test setup:
+
+``` ruby
+Capybara.register_driver(:cuprite) do |app|
+  Capybara::Cuprite::Driver.new(app, options)
+end
+```
 
-### Clicking coordinates ###
+#### Running in Docker ####
 
-Sometimes its desirable to click a very specific area of the screen. You can
-accomplish this with `page.driver.click(x, y)`, where x and y are the screen
-coordinates.
+In docker as root you must pass the no-sandbox browser option:
 
-### Manipulating request headers ###
+```ruby
+Capybara::Cuprite::Driver.new(app, browser_options: { 'no-sandbox': nil })
+```
+
+* options `Hash`
+  * `:browser_path` (String) - Path to chrome binary, you can also set ENV
+      variable as `BROWSER_PATH=some/path/chrome bundle exec rspec`.
+  * `:headless` (Boolean) - Set browser as headless or not, `true` by default.
+  * `:slowmo` (Integer | Float) - Set a delay to wait before sending command.
+      Usefull companion of headless option, so that you have time to see changes.
+  * `:logger` (Object responding to `puts`) - When present, debug output is
+      written to this object.
+  * `:timeout` (Numeric) - The number of seconds we'll wait for a response when
+      communicating with browser. Default is 5.
+  * `:js_errors` (Boolean) - When true, JavaScript errors get re-raised in Ruby.
+  * `:window_size` (Array) - The dimensions of the browser window in which to
+      test, expressed as a 2-element array, e.g. [1024, 768]. Default: [1024, 768]
+  * `:browser_options` (Hash) - Additional command line options,
+      [see them all](https://peter.sh/experiments/chromium-command-line-switches/)
+      e.g. `{ "ignore-certificate-errors" => nil }`
+  * `:extensions` (Array) - An array of JS files to be preloaded into the browser
+  * `:port` (Integer) - Remote debugging port for headless Chrome
+  * `:host` (String) - Remote debugging address for headless Chrome
+  * `:url` (String) - URL for a running instance of Chrome. If this is set, a
+      browser process will not be spawned.
+  * `:url_blacklist` (Array) - array of strings to match against requested URLs
+  * `:url_whitelist` (Array) - array of strings to match against requested URLs
+  * `:process_timeout` (Integer) - How long to wait for the Chrome process to
+      respond on startup
+
+### Clicking/Scrolling ###
+
+* `page.driver.click(x, y)` Click a very specific area of the screen.
+* `page.driver.scroll_to(left, top)` Scroll to given position.
+* `element.send_keys(*keys)` Send keys to given node.
+
+### Request headers ###
 
 Manipulate HTTP request headers like a boss:
 
@@ -73,12 +111,17 @@ Notice that `headers=` will overwrite already set headers. You should use
 subsequent HTTP requests (including requests for assets, AJAX, etc). They will
 be automatically cleared at the end of the test.
 
-### Inspecting network traffic ###
+### Network traffic ###
+
+* `page.driver.network_traffic` Inspect network traffic (resources have been
+  loaded) on the current page. This returns an array of request objects.
 
-You can inspect the network traffic (i.e. what resources have been loaded) on
-the current page by calling `page.driver.network_traffic`. This returns an array
-of request objects. A request object has a `response` method containing data
-about the response.
+
+```ruby
+page.driver.network_traffic # => [Request, ...]
+request = page.driver.network_traffic.first
+request.response
+```
 
 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`
@@ -99,41 +142,16 @@ The following methods are used to inspect and manipulate cookies:
 * `page.driver.remove_cookie(name)` - remove a cookie
 * `page.driver.clear_cookies` - clear all cookies
 
-## Customization ##
+### Screenshot ###
 
-You can customize the way that Capybara sets up Cuprite via the following code
-in your test setup:
+Besides capybara screenshot method you can get image as Base64:
 
-``` ruby
-Capybara.register_driver :cuprite do |app|
-  Capybara::Cuprite::Driver.new(app, options)
-end
-```
+* `page.driver.render_base64(format, options)`
 
-`options` is a hash of options. The following options are supported:
-
-* `:browser_path` (String) - Path to chrome binary, you can also set ENV
-    variable as `BROWSER_PATH=some/path/chrome bundle exec rspec`.
-* `:headless` (Boolean) - Set browser as headless or not, `true` by default.
-* `:slowmo` (Integer | Float) - Set a delay to wait before sending command.
-    Usefull companion of headless option, so that you have time to see changes.
-* `:logger` (Object responding to `puts`) - When present, debug output is
-    written to this object.
-* `:timeout` (Numeric) - The number of seconds we'll wait for a response when
-    communicating with browser. Default is 30.
-* `:js_errors` (Boolean) - When true, JavaScript errors get re-raised in Ruby.
-* `:window_size` (Array) - The dimensions of the browser window in which to
-    test, expressed as a 2-element array, e.g. [1024, 768]. Default: [1024, 768]
-* `:browser_options` (Hash) - Additional command line options,
-    [see them all](https://peter.sh/experiments/chromium-command-line-switches/)
-    e.g. `{ "ignore-certificate-errors" => nil }`
-* `:extensions` (Array) - An array of JS files to be preloaded into the browser
-* `:port` (Integer) - Remote debugging port for headless Chrome
-* `:host` (String) - Remote debugging address for headless Chrome
-* `:url_blacklist` (Array) - array of strings to match against requested URLs
-* `:url_whitelist` (Array) - array of strings to match against requested URLs
-* `:process_timeout` (Integer) - How long to wait for the Chrome process to respond on startup
+### Authorization ###
 
+* `page.driver.basic_authorize(user, password)`
+* `page.driver.set_proxy(ip, port, type, user, password)`
 
 ### URL Blacklisting & Whitelisting ###
 Cuprite supports URL blacklisting, which allows you to prevent scripts from
@@ -154,6 +172,24 @@ If you are experiencing slower run times, consider creating a URL whitelist of
 domains that are essential or a blacklist of domains that are not essential,
 such as ad networks or analytics, to your testing environment.
 
+### Remote debugging ###
+
+If you use the `inspector: true` option, remote debugging will be enabled. When
+this option is enabled, you can insert `page.driver.debug` into your tests to
+pause the test and launch a browser which gives you the Chrome inspector to view
+all your open pages and inspect them.
+
+You can register this debugger driver with a different name and set it
+as the current javascript driver. By example, in your helper file:
+
+```ruby
+Capybara.register_driver :cuprite_debug do |app|
+  Capybara::Cuprite::Driver.new(app, inspector: true)
+end
+
+Capybara.javascript_driver = :cuprite_debug
+```
+
 ## License ##
 
 Copyright 2018-2019 Machinio

data/lib/capybara/cuprite.rb

@@ -1,31 +1,18 @@
 # frozen_string_literal: true
 
+require "ferrum"
 require "capybara"
 
-Thread.abort_on_exception = true
-Thread.report_on_exception = true if Thread.respond_to?(:report_on_exception=)
-
 module Capybara::Cuprite
-  require "capybara/cuprite/driver"
-  require "capybara/cuprite/browser"
-  require "capybara/cuprite/node"
-  require "capybara/cuprite/errors"
-  require "capybara/cuprite/cookie"
-
-  class << self
-    def windows?
-      RbConfig::CONFIG["host_os"] =~ /mingw|mswin|cygwin/
-    end
+end
 
-    def mac?
-      RbConfig::CONFIG["host_os"] =~ /darwin/
-    end
+require "capybara/cuprite/driver"
+require "capybara/cuprite/browser"
+require "capybara/cuprite/page"
+require "capybara/cuprite/node"
+require "capybara/cuprite/errors"
 
-    def mri?
-      defined?(RUBY_ENGINE) && RUBY_ENGINE == "ruby"
-    end
-  end
-end
+Ferrum::Page.prepend(Capybara::Cuprite::Page)
 
 Capybara.register_driver(:cuprite) do |app|
   Capybara::Cuprite::Driver.new(app)

data/lib/capybara/cuprite/browser.rb

@@ -1,301 +1,143 @@
 # frozen_string_literal: true
 
-require "base64"
 require "forwardable"
-require "capybara/cuprite/browser/targets"
-require "capybara/cuprite/browser/process"
-require "capybara/cuprite/browser/client"
-require "capybara/cuprite/browser/page"
 
 module Capybara::Cuprite
-  class Browser
-    TIMEOUT = 5
-    WINDOW_SIZE = [1024, 768].freeze
-    EXTENSIONS = [
-      File.expand_path("browser/javascripts/index.js", __dir__)
-    ].freeze
-
+  class Browser < Ferrum::Browser
     extend Forwardable
 
-    attr_reader :headers, :window_size
-
-    def self.start(*args)
-      new(*args)
-    end
+    delegate %i[find_or_create_page] => :targets
+    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
 
-    delegate subscribe: :@client
-    delegate %i(window_handle window_handles switch_to_window open_new_window
-                close_window within_window page) => :targets
-    delegate %i(visit status_code body all_text property attributes attribute
-                value visible? disabled? network_traffic clear_network_traffic
-                path response_headers refresh click right_click double_click
-                hover set click_coordinates drag drag_by select trigger
-                scroll_to send_keys evaluate evaluate_on evaluate_async execute
-                frame_url frame_title switch_to_frame current_url title go_back
-                go_forward find_modal accept_confirm dismiss_confirm
-                accept_prompt dismiss_prompt reset_modals authorize
-                proxy_authorize) => :page
-
-    attr_reader :process, :logger, :js_errors, :slowmo,
-                :url_blacklist, :url_whitelist
-    attr_writer :timeout
+    attr_reader :url_blacklist, :url_whitelist
 
     def initialize(options = nil)
-      # Doesn't work on MacOS, so we need to set it by CDP as well
       options ||= {}
-      @window_size = options.fetch(:window_size, WINDOW_SIZE)
-      @original_window_size = @window_size
-
-      @options = Hash(options.merge(window_size: @window_size))
-      @logger, @timeout = @options.values_at(:logger, :timeout)
-      @js_errors = @options.fetch(:js_errors, false)
-      @slowmo = @options[:slowmo]
-
-      self.url_blacklist = @options[:url_blacklist]
-      self.url_whitelist = @options[:url_whitelist]
-
-      if ENV["CUPRITE_DEBUG"] && !@logger
-        STDOUT.sync = true
-        @logger = STDOUT
-        @options[:logger] = @logger
-      end
-
-      @options.freeze
+      self.url_blacklist = options[:url_blacklist]
+      self.url_whitelist = options[:url_whitelist]
 
-      start
+      super
     end
 
-    def extensions
-      @extensions ||= begin
-        exts = @options.fetch(:extensions, [])
-        (EXTENSIONS + exts).map { |p| File.read(p) }
-      end
+    def url_whitelist=(patterns)
+      @url_whitelist = prepare_wildcards(patterns)
+      page.intercept_request if @client && !@url_whitelist.empty?
     end
 
-    def timeout
-      @timeout || TIMEOUT
+    def url_blacklist=(patterns)
+      @url_blacklist = prepare_wildcards(patterns)
+      page.intercept_request if @client && !@url_blacklist.empty?
     end
 
-    def source
-      raise NotImplementedError
+    def visit(*args)
+      goto(*args)
     end
 
-    def parents(node)
-      evaluate_on(node: node, expr: "_cuprite.parents(this)", by_value: false)
+    def status_code
+      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["nodeId"])
+      resolved = page.command("DOM.resolveNode", nodeId: node.node_id)
       object_id = resolved.dig("object", "objectId")
       find_all(method, selector, { "objectId" => object_id })
     end
 
-    def visible_text(node)
-      evaluate_on(node: node, expr: "_cuprite.visibleText(this)")
-    end
-
-    def delete_text(node)
-      evaluate_on(node: node, expr: "_cuprite.deleteText(this)")
-    end
-
-    def select_file(node, value)
-      page.command("DOM.setFileInputFiles", nodeId: node["nodeId"], files: Array(value))
-    end
-
-    def render(path, options = {})
-      format = options.delete(:format)
-      options = options.merge(path: path)
-      bin = Base64.decode64(render_base64(format, options))
-      File.open(path.to_s, "wb") { |f| f.write(bin) }
-    end
-
-    def render_base64(format, options = {})
-      options = render_options(format, options)
-
-      if options[:format].to_s == "pdf"
-        options = {}
-        options[:paperWidth] = @paper_size[:width].to_f if @paper_size
-        options[:paperHeight] = @paper_size[:height].to_f if @paper_size
-        options[:scale] = @zoom_factor if @zoom_factor
-        page.command("Page.printToPDF", **options)
-      else
-        page.command("Page.captureScreenshot", **options)
-      end.fetch("data")
-    end
-
-    def set_zoom_factor(zoom_factor)
-      @zoom_factor = zoom_factor.to_f
-    end
-
-    def set_paper_size(size)
-      @paper_size = size
-    end
-
-    def headers=(headers)
-      @headers = {}
-      add_headers(headers)
-    end
-
-    def add_headers(headers, permanent: true)
-      if headers["Referer"]
-        page.referrer = headers["Referer"]
-        headers.delete("Referer") unless permanent
+    def within_window(locator = nil, &block)
+      if Capybara::VERSION.to_f < 3.0
+        target_id = window_handles.find do |target_id|
+          page = find_or_create_page(target_id)
+          locator == page.frame_name
+        end
+        locator = target_id if target_id
       end
 
-      @headers.merge!(headers)
-      user_agent = @headers["User-Agent"]
-      accept_language = @headers["Accept-Language"]
-
-      set_overrides(user_agent: user_agent, accept_language: accept_language)
-      page.command("Network.setExtraHTTPHeaders", headers: @headers)
-    end
-
-    def add_header(header, permanent: true)
-      add_headers(header, permanent: permanent)
-    end
-
-    def set_overrides(user_agent: nil, accept_language: nil, platform: nil)
-      options = Hash.new
-      options[:userAgent] = user_agent if user_agent
-      options[:acceptLanguage] = accept_language if accept_language
-      options[:platform] if platform
-
-      page.command("Network.setUserAgentOverride", **options) if !options.empty?
+      targets.within_window(locator, &block)
     end
 
-    def cookies
-      cookies = page.command("Network.getAllCookies")["cookies"]
-      cookies.map { |c| [c["name"], Cookie.new(c)] }.to_h
+    def browser_error
+      evaluate("_cuprite.browserError()")
     end
 
-    def set_cookie(cookie)
-      page.command("Network.setCookie", **cookie)
+    def source
+      raise NotImplementedError
     end
 
-    def remove_cookie(options)
-      page.command("Network.deleteCookies", **options)
+    def drag(node, other)
+      raise NotImplementedError
     end
 
-    def clear_cookies
-      page.command("Network.clearBrowserCookies")
+    def drag_by(node, x, y)
+      raise NotImplementedError
     end
 
-    def url_whitelist=(wildcards)
-      @url_whitelist = prepare_wildcards(wildcards)
-      page.intercept_request("*") if @client && !@url_whitelist.empty?
+    def select_file(node, value)
+      node.select_file(value)
     end
 
-    def url_blacklist=(wildcards)
-      @url_blacklist = prepare_wildcards(wildcards)
-      page.intercept_request("*") if @client && !@url_blacklist.empty?
+    def parents(node)
+      evaluate_on(node: node, expression: "_cuprite.parents(this)", by_value: false)
     end
 
-    def clear_memory_cache
-      page.command("Network.clearBrowserCache")
+    def visible_text(node)
+      evaluate_on(node: node, expression: "_cuprite.visibleText(this)")
     end
 
-    def reset
-      @headers = {}
-      @zoom_factor = nil
-      @window_size = @original_window_size
-      targets.reset
+    def delete_text(node)
+      evaluate_on(node: node, expression: "_cuprite.deleteText(this)")
     end
 
-    def restart
-      quit
-      start
+    def attributes(node)
+      value = evaluate_on(node: node, expression: "_cuprite.getAttributes(this)")
+      JSON.parse(value)
     end
 
-    def quit
-      @client.close
-      @process.stop
-      @client = @process = @targets = nil
+    def attribute(node, name)
+      evaluate_on(node: node, expression: %Q(_cuprite.getAttribute(this, "#{name}")))
     end
 
-    def crash
-      command("Browser.crash")
+    def value(node)
+      evaluate_on(node: node, expression: "_cuprite.value(this)")
     end
 
-    def browser_error
-      page.evaluate("_cuprite.browserError()")
+    def visible?(node)
+      evaluate_on(node: node, expression: "_cuprite.isVisible(this)")
     end
 
-    def resize(**options)
-      @window_size = [options[:width], options[:height]]
-      page.resize(**options)
+    def disabled?(node)
+      evaluate_on(node: node, expression: "_cuprite.isDisabled(this)")
     end
 
-    def command(*args)
-      id = @client.command(*args)
-      @client.wait(id: id)
-    rescue DeadBrowser
-      restart
-      raise
+    def path(node)
+      evaluate_on(node: node, expression: "_cuprite.path(this)")
     end
 
-    def targets
-      @targets ||= Targets.new(self)
+    def all_text(node)
+      node.text
     end
 
     private
 
-    def start
-      @headers = {}
-      @process = Process.start(@options)
-      @client = Client.new(self, @process.ws_url, false)
-    end
-
-    def render_options(format, opts)
-      options = {}
-
-      format ||= File.extname(opts[:path]).delete(".") || "png"
-      format = "jpeg" if format == "jpg"
-      raise "Not supported format: #{format}. jpeg | png | pdf" if format !~ /jpeg|png|pdf/i
-      options.merge!(format: format)
-
-      options.merge!(quality: opts[:quality] ? opts[:quality] : 75) if format == "jpeg"
-
-      warn "Ignoring :selector in #render since full: true was given at #{caller(1..1).first}" if !!opts[:full] && opts[:selector]
-
-      if !!opts[:full]
-        width, height = page.evaluate("[document.documentElement.offsetWidth, document.documentElement.offsetHeight]")
-        options.merge!(clip: { x: 0, y: 0, width: width, height: height, scale: @zoom_factor || 1.0 }) if width > 0 && height > 0
-      elsif opts[:selector]
-        rect = page.evaluate("document.querySelector('#{opts[:selector]}').getBoundingClientRect()")
-        options.merge!(clip: { x: rect["x"], y: rect["y"], width: rect["width"], height: rect["height"], scale: @zoom_factor || 1.0 })
-      end
-
-      if @zoom_factor
-        if !options[:clip]
-          width, height = page.evaluate("[document.documentElement.clientWidth, document.documentElement.clientHeight]")
-          options[:clip] = { x: 0, y: 0, width: width, height: height }
-        end
-
-        options[:clip].merge!(scale: @zoom_factor)
-      end
-
-      options
-    end
-
     def find_all(method, selector, within = nil)
       begin
-        elements = if within
+        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
 
-        elements.map do |element|
-          # nodeType: 3, nodeName: "#text" e.g.
-          target_id, node = element.values_at("target_id", "node")
-          next if node["nodeType"] != 1
-          within ? node : [target_id, node]
-        end.compact
-      rescue JavaScriptError => e
+        nodes.map { |n| n.node? ? n : next }.compact
+      rescue Ferrum::JavaScriptError => e
         if e.class_name == "InvalidSelector"
           raise InvalidSelector.new(e.response, method, selector)
         end