cuprite 0.14.1 → 0.14.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba6b2d59f81358541ceedf4d5897c776ec4e36f2749894ec989b7e00d239f5dc
-  data.tar.gz: 8c387e1473c47a21ae3f21641f9a9d63084c4ed042b94c07fcc9376f568f28d6
+  metadata.gz: e6480f3033eff59cc4f7d261e47c37ae7169ef8dd806c9b1f471d4d59be5b5a7
+  data.tar.gz: 4d35f4b5df0457b7ea51842738e66c1b6aecc2d1753bdec5d7dbf82d28273ecd
 SHA512:
-  metadata.gz: 736a95aefb32b8704be3c44f3b0e22ebae5ea7f17b61a235bf9093618093c2edb3693c831be11d7d58d1f16429a1472ea73d6e7a8228ec395b7b808471ad410b
-  data.tar.gz: f3ecd0e01f4cb54c9e1623a30c50c369c526e19b57d4157a84a6368ae9db722000323fdd011d3375186fdac7e9307727c5a15203b10b9c8a5ae29f4e18755dc0
+  metadata.gz: c347f3f5555138a6ae5660de778ec13d9e7686007ffdf9d635b826e6fa13a42520cb137693ee0142395b7cb00efa3a5939c9ccfc6fa75411397310f0593fef33
+  data.tar.gz: 82dd53121faab3a9f700928873d13dc42c33aae6a6065b88efcbadf02094356226ef8d72fa2d3ccfaf460a89ecfaf53950db49a57e6d9222ef9cf968eea7d6d2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2022 Dmitry Vorotilin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# Cuprite - Headless Chrome driver for Capybara
+
+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
+uses [Ferrum](https://github.com/rubycdp/ferrum#index) which is high-level API
+to the browser by CDP protocol. The design of the driver is as close to
+[Poltergeist](https://github.com/teampoltergeist/poltergeist) as possible though
+it's not a goal.
+
+
+## Install
+
+Add this to your `Gemfile` and run `bundle install`.
+
+``` ruby
+group :test do
+  gem "cuprite"
+end
+```
+
+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
+```
+
+if you use `Docker` don't forget to pass `no-sandbox` option:
+
+```ruby
+Capybara::Cuprite::Driver.new(app, browser_options: { 'no-sandbox': nil })
+```
+
+Since Cuprite uses [Ferrum](https://github.com/rubycdp/ferrum#examples) there
+are many useful methods you can call even using this driver:
+
+```ruby
+browser = page.driver.browser
+browser.mouse.move(x: 123, y: 456).down.up
+```
+
+If you already have tests on Poltergeist then it should simply work, for
+Selenium you better check your code for `manage` calls because it works
+differently in Cuprite, see the documentation below.
+
+
+## Customization
+
+See the full list of options for
+[Ferrum](https://github.com/rubycdp/ferrum#customization).
+
+You can pass options with the following code in your test setup:
+
+``` ruby
+Capybara.register_driver(:cuprite) do |app|
+  Capybara::Cuprite::Driver.new(app, options)
+end
+```
+
+`Cuprite`-specific options are:
+
+* options `Hash`
+  * `:url_blacklist` (Array) - array of strings to match against requested URLs
+  * `:url_whitelist` (Array) - array of strings to match against requested URLs
+
+
+## Debugging
+
+If you pass `inspector` option, remote debugging will be enabled if you run
+tests with `INSPECTOR=true`. Then you can put `page.driver.debug` or
+`page.driver.debug(binding)` in your test to pause it. This will launch the
+browser where you can inspect the content.
+
+```ruby
+Capybara.register_driver :cuprite do |app|
+  Capybara::Cuprite::Driver.new(app, inspector: ENV['INSPECTOR'])
+end
+```
+
+then somewhere in the test:
+
+```ruby
+it "does something useful" do
+  visit root_path
+
+  fill_in "field", with: "value"
+  page.driver.debug(binding)
+
+  expect(page).to have_content("value")
+end
+```
+
+In the middle of the execution Chrome will open a new tab where you can inspect
+the content and also if you passed `binding` an `irb` or `pry` console will be
+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.
+* `element.send_keys(*keys)` Send keys to a given node.
+
+
+## Request headers
+
+Manipulate HTTP request headers like a boss:
+
+``` 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" }
+```
+
+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.
+
+
+## Network traffic
+
+* `page.driver.network_traffic` Inspect network traffic (loaded resources) on
+the current page. This returns an array of request objects.
+
+```ruby
+page.driver.network_traffic # => [Request, ...]
+request = page.driver.network_traffic.first
+request.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
+[`wait_for_idle`](https://github.com/rubycdp/ferrum#wait_for_idleoptions)
+
+```ruby
+page.driver.wait_for_network_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`
+
+* `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
+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
+return earlier even before the whole page is started to reload. Here's the
+rescue.
+
+
+## Manipulating cookies
+
+The following methods are used 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
+
+
+## Screenshot
+
+Besides capybara screenshot method you can get image as Base64:
+
+* `page.driver.render_base64(format, options)`
+
+
+## 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
+running on designated domains:
+
+```ruby
+page.driver.browser.url_blacklist = ["http://www.example.com"]
+```
+
+and also URL whitelisting, which allows scripts to only run on designated
+domains:
+
+```ruby
+page.driver.browser.url_whitelist = ["http://www.example.com"]
+```
+
+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.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/lib/capybara/cuprite/browser.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Capybara
+  module Cuprite
+    class Browser < Ferrum::Browser
+      extend Forwardable
+
+      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
+
+      attr_reader :url_blacklist, :url_whitelist
+
+      def initialize(options = nil)
+        options ||= {}
+        @client = nil
+        self.url_blacklist = options[:url_blacklist]
+        self.url_whitelist = options[:url_whitelist]
+
+        super
+        @page = false
+      end
+
+      def timeout=(value)
+        super
+        @page.timeout = value unless @page.nil?
+      end
+
+      def page
+        raise Ferrum::NoSuchPageError if @page.nil?
+
+        @page ||= attach_page
+      end
+
+      def reset
+        super
+        @page = attach_page
+      end
+
+      def quit
+        super
+        @page = false
+      end
+
+      def url_whitelist=(patterns)
+        @url_whitelist = prepare_wildcards(patterns)
+        page.network.intercept if @client && !@url_whitelist.empty?
+      end
+
+      def url_blacklist=(patterns)
+        @url_blacklist = prepare_wildcards(patterns)
+        page.network.intercept if @client && !@url_blacklist.empty?
+      end
+
+      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
+        page.target_id
+      end
+
+      def window_handles
+        targets.keys
+      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)
+      end
+
+      def switch_to_window(target_id)
+        target = targets[target_id]
+        raise Ferrum::NoSuchPageError unless target
+
+        @page = attach_page(target.id)
+      end
+
+      def close_window(target_id)
+        target = targets[target_id]
+        raise Ferrum::NoSuchPageError unless target
+
+        @page = nil if @page.target_id == target.id
+        target.page.close
+      end
+
+      def browser_error
+        evaluate("_cuprite.browserError()")
+      end
+
+      def source
+        raise NotImplementedError
+      end
+
+      def drag(node, other)
+        x1, y1 = node.find_position
+        x2, y2 = other.find_position
+
+        mouse.move(x: x1, y: y1)
+        mouse.down
+        mouse.move(x: x2, y: y2)
+        mouse.up
+      end
+
+      def drag_by(node, x, y)
+        x1, y1 = node.find_position
+        x2 = x1 + x
+        y2 = y1 + y
+
+        mouse.move(x: x1, y: y1)
+        mouse.down
+        mouse.move(x: x2, y: y2)
+        mouse.up
+      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 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
+      end
+
+      def prepare_wildcards(wc)
+        Array(wc).map do |wildcard|
+          if wildcard.is_a?(Regexp)
+            wildcard
+          else
+            wildcard = wildcard.gsub("*", ".*")
+            Regexp.new(wildcard, Regexp::IGNORECASE)
+          end
+        end
+      end
+
+      def attach_page(target_id = nil)
+        target = targets[target_id] if target_id
+        target ||= default_context.default_target
+        return target.page if target.attached?
+
+        target.maybe_sleep_if_new_window
+        target.page = Page.new(target.id, self)
+        target.page
+      end
+    end
+  end
+end

data/lib/capybara/cuprite/cookie.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Cuprite
+    class Cookie
+      def initialize(attributes)
+        @attributes = attributes
+      end
+
+      def name
+        @attributes["name"]
+      end
+
+      def value
+        @attributes["value"]
+      end
+
+      def domain
+        @attributes["domain"]
+      end
+
+      def path
+        @attributes["path"]
+      end
+
+      def size
+        @attributes["size"]
+      end
+
+      def secure?
+        @attributes["secure"]
+      end
+
+      def httponly?
+        @attributes["httpOnly"]
+      end
+
+      def session?
+        @attributes["session"]
+      end
+
+      def expires
+        Time.at(@attributes["expires"]) if (@attributes["expires"]).positive?
+      end
+    end
+  end
+end