ferrum 0.15 → 0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd12d4dc355349e2512a669ffd14000bbc21d00da0d04f1da810ae93f862a903
-  data.tar.gz: 4322afe3ea5606758907b7471cd8eb577c351821f457f8e61a5fdeda40077149
+  metadata.gz: f586cea5a9987e2a53bfb860fb503d36fc9e2f4e16b7288dafe68b2e62f20ede
+  data.tar.gz: a33d17e091b0d7b506f0934dd19f056ab15c72891659cc227f03bccad8d90cdd
 SHA512:
-  metadata.gz: 2c23f63deb1e31240bb10db2f09e9ddccc7a1c7dc742befeca8eeff1ce8cd621ac4977cfcc9ce74d3055d2fa3c45957c3af81dde3bdaf7e09a1a56ab42e67b86
-  data.tar.gz: ffc6f604d44abb9a75054df9c8691f4c6c8bf356f626d440c5538153e2b64a27761deacb699c69dee020def3977bb27b69533d06230d512d00b9321b0a897387
+  metadata.gz: 031a4dcb48ba0d22c1070ab8e905881f07369e7c19b61f03ef747d4ff3813be097a8f8bc65f692f4ed186687ba1e4e83c9de4482939a963b2541364c0d745b16
+  data.tar.gz: 207975dde463249331095cada046454110ee80d8a4a42fdc7f51898ad514e0aa5395946e037abd5c5599a7fa2d570c279925555822d432c4470c6e955f37b85b

data/README.md

@@ -25,9 +25,6 @@ going to crawl sites you better use Ferrum or
 * [Vessel](https://github.com/rubycdp/vessel) high-level web crawling framework
 based on Ferrum and Mechanize.
 
-The development is done in [![RubyMine](https://resources.jetbrains.com/storage/products/company/brand/logos/RubyMine_icon.svg?width=10px)](https://jb.gg/ruby)
-provided by [OSS license](https://jb.gg/OpenSourceSupport).
-
 ## Index
 
 * [Install](https://github.com/rubycdp/ferrum#install)
@@ -37,6 +34,7 @@ provided by [OSS license](https://jb.gg/OpenSourceSupport).
 * [Navigation](https://github.com/rubycdp/ferrum#navigation)
 * [Finders](https://github.com/rubycdp/ferrum#finders)
 * [Screenshots](https://github.com/rubycdp/ferrum#screenshots)
+* [Screencast](https://github.com/rubycdp/ferrum#screencast)
 * [Network](https://github.com/rubycdp/ferrum#network)
 * [Downloads](https://github.com/rubycdp/ferrum#downloads)
 * [Proxy](https://github.com/rubycdp/ferrum#proxy)
@@ -139,7 +137,7 @@ browser.quit
 In docker as root you must pass the no-sandbox browser option:
 
 ```ruby
-Ferrum::Browser.new(browser_options: { 'no-sandbox': nil })
+Ferrum::Browser.new(browser_options: { "no-sandbox": nil })
 ```
 
 It has also been reported that the Chrome process repeatedly crashes when running inside a Docker container on an M1 Mac preventing Ferrum from working. Ferrum should work as expected when deployed to a Docker container on a non-M1 Mac.
@@ -153,8 +151,8 @@ Ferrum::Browser.new(options)
 ```
 
 * options `Hash`
-  * `:headless` (String | Boolean) - Set browser as headless or not, `true` by default. You can set `"new"` to support
-      [new headless mode](https://developer.chrome.com/articles/new-headless/).
+  * `:headless` (Boolean) - Set browser as headless or not, `true` by default.
+  * `:incognito` (Boolean) - Create an incognito profile for the browser startup window, `true` by default.
   * `:xvfb` (Boolean) - Run browser in a virtual framebuffer, `false` by default.
   * `:flatten` (Boolean) - Use one websocket connection to the browser and all the pages in flatten mode.
   * `:window_size` (Array) - The dimensions of the browser window in which to
@@ -188,7 +186,7 @@ Ferrum::Browser.new(options)
   * `:url` (String) - URL for a running instance of Chrome. If this is set, a
       browser process will not be spawned.
   * `:ws_url` (String) - Websocket url for a running instance of Chrome. If this is set, a
-      browser process will not be spawned.
+    browser process will not be spawned. It's higher priority than `:url`, setting both doesn't make sense.
   * `:process_timeout` (Integer) - How long to wait for the Chrome process to
       respond on startup.
   * `:ws_max_receive_size` (Integer) - How big messages to accept from Chrome
@@ -398,7 +396,7 @@ Saves screenshot on a disk or returns it as base64.
     `:binary` automatically
   * :encoding `Symbol` `:base64` | `:binary` you can set it to return image as
     Base64
-  * :format `String` "jpeg" | "png"
+  * :format `String` "jpeg" ("jpg") | "png" | "webp"
   * :quality `Integer` 0-100 works for jpeg only
   * :full `Boolean` whether you need full page screenshot or a viewport
   * :selector `String` css selector for given element, optional
@@ -419,7 +417,7 @@ 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
+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
@@ -461,6 +459,58 @@ page.go_to("https://google.com/")
 page.mhtml(path: "google.mhtml") # => 87742
 ```
 
+## Screencast
+
+#### start_screencast(\*\*options) { |data, metadata, session_id| ... }
+
+Starts sending frames to record screencast to the given block.
+
+* options `Hash`
+  * :format `Symbol` `:jpeg` | `:png` The format the image should be returned in.
+  * :quality `Integer` The image quality. **Note:** 0-100 works for JPEG only.
+  * :max_width `Integer` Maximum screencast frame width.
+  * :max_height `Integer` Maximum screencast frame height.
+  * :every_nth_frame `Integer` Send every n-th frame.
+
+* Block inputs:
+  * data `String` Base64-encoded compressed image.
+  * metadata `Hash` Screencast frame metadata.
+    * "offsetTop" `Integer` Top offset in DIP.
+    * "pageScaleFactor" `Integer` Page scale factor.
+    * "deviceWidth" `Integer` Device screen width in DIP.
+    * "deviceHeight" `Integer` Device screen height in DIP.
+    * "scrollOffsetX" `Integer` Position of horizontal scroll in CSS pixels.
+    * "scrollOffsetY" `Integer` Position of vertical scroll in CSS pixels.
+    * "timestamp" `Float` (optional) Frame swap timestamp in seconds since Unix epoch.
+  * session_id `Integer` Frame number.
+
+```ruby
+require "base64"
+
+page.go_to("https://apple.com/ipad")
+
+page.start_screencast(format: :jpeg, quality: 75) do |data, metadata|
+  timestamp = (metadata["timestamp"] * 1000).to_i
+  File.binwrite("image_#{timestamp}.jpg", Base64.decode64(data))
+end
+
+sleep 10
+
+page.stop_screencast
+```
+
+> ### 📝 NOTE
+>
+> Chrome only sends new frames while page content is changing. For example, if
+> there is an animation or a video on the page, Chrome sends frames at the rate
+> requested. On the other hand, if the page is nothing but a wall of static text,
+> Chrome sends frames while the page renders. Once Chrome has finished rendering
+> the page, it sends no more frames until something changes (e.g., navigating to
+> another location).
+
+#### stop_screencast
+
+Stops sending frames.
 
 ## Network
 
@@ -504,9 +554,9 @@ page.go_to("https://github.com/")
 page.network.status # => 200
 ```
 
-#### wait_for_idle(\*\*options)
+#### wait_for_idle(\*\*options) : `Boolean`
 
-Waits for network idle or raises `Ferrum::TimeoutError` error
+Waits for network idle, returns `true` in case of success and `false` if there are still connections.
 
 * options `Hash`
   * :connections `Integer` how many connections are allowed for network to be
@@ -519,7 +569,17 @@ Waits for network idle or raises `Ferrum::TimeoutError` error
 ```ruby
 page.go_to("https://example.com/")
 page.at_xpath("//a[text() = 'No UI changes button']").click
-page.network.wait_for_idle
+page.network.wait_for_idle # => true
+```
+
+#### wait_for_idle!(\*\*options)
+
+Waits for network idle or raises `Ferrum::TimeoutError` error. Accepts same arguments as `wait_for_idle`.
+
+```ruby
+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
 ```
 
 #### clear(type)
@@ -872,6 +932,25 @@ Removes all cookies for current page
 page.cookies.clear # => true
 ```
 
+#### store(path) : `Boolean`
+
+Stores all cookies of current page in a file.
+
+```ruby
+# Cookies are saved into cookies.yml
+page.cookies.store # => 15657
+```
+
+#### load(path) : `Boolean`
+
+Loads all cookies from the file and sets them for current page.
+
+```ruby
+# Cookies are loaded from cookies.yml
+page.cookies.load # => true
+```
+
+
 ## Headers
 
 `page.headers`
@@ -1059,9 +1138,17 @@ Frame's unique id.
 
 Parent frame id if this one is nested in another one.
 
+#### parent : `Frame | nil`
+
+Parent frame if this one is nested in another one.
+
+#### frame_element : `Node | nil`
+
+Returns the element in which the window is embedded.
+
 #### execution_id : `Integer`
 
-Execution context id which is used by JS, each frame has it's own context in
+Execution context id which is used by JS, each frame has its own context in
 which JS evaluates.
 
 #### name : `String | nil`
@@ -1243,6 +1330,8 @@ frame.at_css("//a[text() = 'Log in']") # => Node
 #### select
 #### scroll_into_view
 #### in_viewport?(of: `Node | nil`) : `Boolean`
+#### remove
+#### exists?
 
 (chainable) Selects options by passed attribute.
 
@@ -1294,7 +1383,7 @@ Closes browser tabs opened by the `Browser` instance.
 
 ```ruby
 # connect to a long-running Chrome process
-browser = Ferrum::Browser.new(url: 'http://localhost:9222')
+browser = Ferrum::Browser.new(url: "http://localhost:9222")
 
 browser.go_to("https://github.com/")
 

data/lib/ferrum/browser/command.rb

@@ -39,10 +39,6 @@ module Ferrum
         !!options.xvfb
       end
 
-      def headless_new?
-        @flags["headless"] == "new"
-      end
-
       def to_a
         [path] + @flags.map { |k, v| v.nil? ? "--#{k}" : "--#{k}=#{v}" }
       end

data/lib/ferrum/browser/options/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "singleton"
+require "open3"
 
 module Ferrum
   class Browser
@@ -12,6 +13,14 @@ module Ferrum
           instance
         end
 
+        # @return [String, nil]
+        def self.version
+          out, = Open3.capture2(instance.detect_path, "--version")
+          out.strip
+        rescue Errno::ENOENT
+          nil
+        end
+
         def to_h
           self.class::DEFAULT_OPTIONS
         end

data/lib/ferrum/browser/options/chrome.rb

@@ -38,8 +38,9 @@ module Ferrum
           "safebrowsing-disable-auto-update" => nil,
           "password-store" => "basic",
           "no-startup-window" => nil,
-          "remote-allow-origins" => "*"
-          # NOTE: --no-sandbox is not needed if you properly setup a user in the container.
+          "remote-allow-origins" => "*",
+          "disable-blink-features" => "AutomationControlled"
+          # NOTE: --no-sandbox is not needed if you properly set up a user in the container.
           # https://github.com/ebidel/lighthouse-ci/blob/master/builder/Dockerfile#L35-L40
           # "no-sandbox" => nil,
         }.freeze
@@ -75,15 +76,10 @@ module Ferrum
         end
 
         def merge_default(flags, options)
-          defaults = case options.headless
-                     when false
-                       except("headless", "disable-gpu")
-                     when "new"
-                       except("headless").merge("headless" => "new")
-                     end
-
+          defaults = except("headless", "disable-gpu") if options.headless == false
           defaults ||= DEFAULT_OPTIONS
-          # On Windows, the --disable-gpu flag is a temporary work around for a few bugs.
+          defaults.delete("no-startup-window") if options.incognito == false
+          # On Windows, the --disable-gpu flag is a temporary workaround for a few bugs.
           # See https://bugs.chromium.org/p/chromium/issues/detail?id=737678 for more information.
           defaults = defaults.merge("disable-gpu" => nil) if Utils::Platform.windows?
           # Use Metal on Apple Silicon

data/lib/ferrum/browser/options.rb

@@ -14,7 +14,7 @@ module Ferrum
       attr_reader :window_size, :logger, :ws_max_receive_size,
                   :js_errors, :base_url, :slowmo, :pending_connection_errors,
                   :url, :ws_url, :env, :process_timeout, :browser_name, :browser_path,
-                  :save_path, :proxy, :port, :host, :headless, :browser_options,
+                  :save_path, :proxy, :port, :host, :headless, :incognito, :browser_options,
                   :ignore_default_browser_options, :xvfb, :flatten
       attr_accessor :timeout, :default_user_agent
 
@@ -27,6 +27,7 @@ module Ferrum
         @window_size = @options.fetch(:window_size, WINDOW_SIZE)
         @js_errors = @options.fetch(:js_errors, false)
         @headless = @options.fetch(:headless, true)
+        @incognito = @options.fetch(:incognito, true)
         @flatten = @options.fetch(:flatten, true)
         @pending_connection_errors = @options.fetch(:pending_connection_errors, true)
         @process_timeout = @options.fetch(:process_timeout, PROCESS_TIMEOUT)

data/lib/ferrum/browser/process.rb

@@ -9,6 +9,8 @@ require "ferrum/browser/options/base"
 require "ferrum/browser/options/chrome"
 require "ferrum/browser/options/firefox"
 require "ferrum/browser/command"
+require "ferrum/utils/elapsed_time"
+require "ferrum/utils/platform"
 
 module Ferrum
   class Browser
@@ -62,15 +64,11 @@ module Ferrum
       def initialize(options)
         @pid = @xvfb = @user_data_dir = nil
 
-        if options.ws_url
-          response = parse_json_version(options.ws_url)
-          self.ws_url = response&.[]("webSocketDebuggerUrl") || options.ws_url
-          return
-        end
-
-        if options.url
-          response = parse_json_version(options.url)
-          self.ws_url = response&.[]("webSocketDebuggerUrl")
+        if options.ws_url || options.url
+          # `:ws_url` option is higher priority than `:url`, parse versions
+          # and use it as a ws_url, otherwise use what has been parsed.
+          response = parse_json_version(options.ws_url || options.url)
+          self.ws_url = options.ws_url || response&.[]("webSocketDebuggerUrl")
           return
         end
 
@@ -180,7 +178,7 @@ module Ferrum
 
       def close_io(*ios)
         ios.each do |io|
-          io.close unless io.closed?
+          io.close if io && !io.closed?
         rescue IOError
           raise unless RUBY_ENGINE == "jruby"
         end
@@ -207,7 +205,7 @@ module Ferrum
         @protocol_version = response["Protocol-Version"]
 
         response
-      rescue StandardError
+      rescue JSON::ParserError
         # nop
       end
     end

data/lib/ferrum/browser.rb

@@ -23,6 +23,7 @@ module Ferrum
                 headers cookies network downloads
                 mouse keyboard
                 screenshot pdf mhtml viewport_size device_pixel_ratio
+                start_screencast stop_screencast
                 frames frame_by main_frame
                 evaluate evaluate_on evaluate_async execute evaluate_func
                 add_script_tag add_style_tag bypass_csp
@@ -44,6 +45,9 @@ module Ferrum
     # @option options [Boolean] :headless (true)
     #   Set browser as headless or not.
     #
+    # @option options [Boolean] :incognito (true)
+    #   Create an incognito profile for the browser startup window.
+    #
     # @option options [Boolean] :xvfb (false)
     #   Run browser in a virtual framebuffer.
     #
@@ -218,10 +222,22 @@ module Ferrum
       @client = @process = @contexts = nil
     end
 
+    #
+    # Crashes browser.
+    #
     def crash
       command("Browser.crash")
     end
 
+    #
+    # Close browser gracefully.
+    #
+    # You should clean up resources/connections in ruby world manually, it's only a CDP command.
+    #
+    def close
+      command("Browser.close")
+    end
+
     #
     # Gets the version information from the browser.
     #
@@ -233,8 +249,22 @@ module Ferrum
       VersionInfo.new(command("Browser.getVersion"))
     end
 
-    def headless_new?
-      process&.command&.headless_new?
+    #
+    # Opens headless session in the browser devtools frontend.
+    #
+    # @return [void]
+    #
+    # @since 0.16
+    #
+    def debug(bind = nil)
+      ::Process.spawn(process.path, debug_url)
+
+      bind ||= binding
+      if bind.respond_to?(:pry)
+        Pry.start(bind)
+      else
+        bind.irb
+      end
     end
 
     private
@@ -254,5 +284,18 @@ module Ferrum
         raise
       end
     end
+
+    def debug_url
+      response = JSON.parse(Net::HTTP.get(URI(build_remote_debug_url(path: "/json"))))
+
+      devtools_frontend_path = response[0]&.[]("devtoolsFrontendUrl")
+      raise "Could not generate debug url for remote debugging session" unless devtools_frontend_path
+
+      build_remote_debug_url(path: devtools_frontend_path)
+    end
+
+    def build_remote_debug_url(path:)
+      "http://#{process.host}:#{process.port}#{path}"
+    end
   end
 end

data/lib/ferrum/client/subscriber.rb

@@ -8,7 +8,7 @@ module Ferrum
       def initialize
         @regular = Queue.new
         @priority = Queue.new
-        @on = Concurrent::Hash.new { |h, k| h[k] = Concurrent::Array.new }
+        @on = Concurrent::Hash.new
 
         start
       end
@@ -22,7 +22,13 @@ module Ferrum
       end
 
       def on(event, &block)
+        @on[event] ||= Concurrent::Array.new
         @on[event] << block
+        @on[event].index(block)
+      end
+
+      def off(event, id)
+        @on[event].delete_at(id)
         true
       end
 
@@ -65,8 +71,8 @@ module Ferrum
         method, session_id, params = message.values_at("method", "sessionId", "params")
         event = SessionClient.event_name(method, session_id)
 
-        total = @on[event].size
-        @on[event].each_with_index do |block, index|
+        total = @on[event]&.size.to_i
+        @on[event]&.each_with_index do |block, index|
           # In case of multiple callbacks we provide current index and total
           block.call(params, index, total)
         end

data/lib/ferrum/client/web_socket.rb

@@ -50,13 +50,17 @@ module Ferrum
       end
 
       def on_message(event)
-        data = JSON.parse(event.data)
-        @messages.push(data)
+        data = safely_parse_json(event.data)
+        # If we couldn't parse JSON data for some reason (parse error or deeply nested object) we
+        # don't push response to @messages. Worse that could happen we raise timeout error due to command didn't return
+        # anything or skip the background notification, but at least we don't crash the thread that crashes the main
+        # thread and the application.
+        @messages.push(data) if data
 
         output = event.data
-        if SKIP_LOGGING_SCREENSHOTS && @screenshot_commands[data["id"]]
-          @screenshot_commands.delete(data["id"])
-          output.sub!(/{"data":"(.*)"}/, %("Set FERRUM_LOGGING_SCREENSHOTS=true to see screenshots in Base64"))
+        if SKIP_LOGGING_SCREENSHOTS && @screenshot_commands[data&.dig("id")]
+          @screenshot_commands.delete(data&.dig("id"))
+          output.sub!(/{"data":"[^"]*"}/, %("Set FERRUM_LOGGING_SCREENSHOTS=true to see screenshots in Base64"))
         end
 
         @logger&.puts("    ◀ #{Utils::ElapsedTime.elapsed_time} #{output}\n")
@@ -100,6 +104,23 @@ module Ferrum
           @messages.close
         end
       end
+
+      def safely_parse_json(data)
+        JSON.parse(data, max_nesting: false)
+      rescue JSON::NestingError
+        # nop
+      rescue JSON::ParserError
+        safely_parse_escaped_json(data)
+      end
+
+      def safely_parse_escaped_json(data)
+        unescaped_unicode =
+          data.gsub(/\\u([\da-fA-F]{4})/) { |_| [::Regexp.last_match(1)].pack("H*").unpack("n*").pack("U*") }
+        escaped_data = unescaped_unicode.encode("UTF-8", "UTF-8", undef: :replace, invalid: :replace, replace: "?")
+        JSON.parse(escaped_data, max_nesting: false)
+      rescue JSON::ParserError
+        # nop
+      end
     end
   end
 end

data/lib/ferrum/client.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require "concurrent-ruby"
 require "forwardable"
 require "ferrum/client/subscriber"
 require "ferrum/client/web_socket"
+require "ferrum/utils/thread"
 
 module Ferrum
   class SessionClient
@@ -26,6 +28,10 @@ module Ferrum
       @client.on(event_name(event), &block)
     end
 
+    def off(event, id)
+      @client.off(event_name(event), id)
+    end
+
     def subscribed?(event)
       @client.subscribed?(event_name(event))
     end
@@ -34,8 +40,8 @@ module Ferrum
       @client.respond_to?(name, include_private)
     end
 
-    def method_missing(name, ...)
-      @client.send(name, ...)
+    def method_missing(name, *args, **opts, &block)
+      @client.send(name, *args, **opts, &block)
     end
 
     def close
@@ -99,6 +105,10 @@ module Ferrum
       @subscriber.on(event, &block)
     end
 
+    def off(event, id)
+      @subscriber.off(event, id)
+    end
+
     def subscribed?(event)
       @subscriber.subscribed?(event)
     end

data/lib/ferrum/context.rb

@@ -13,7 +13,7 @@ module Ferrum
       @client = client
       @contexts = contexts
       @targets = Concurrent::Map.new
-      @pendings = Concurrent::MVar.new
+      @pendings = Concurrent::Map.new
     end
 
     def default_target
@@ -25,11 +25,11 @@ module Ferrum
     end
 
     def pages
-      @targets.values.map(&:page)
+      @targets.values.reject(&:iframe?).map(&:page)
     end
 
     # When we call `page` method on target it triggers ruby to connect to given
-    # page by WebSocket, if there are many opened windows but we need only one
+    # page by WebSocket, if there are many opened windows, but we need only one
     # it makes more sense to get and connect to the needed one only which
     # usually is the last one.
     def windows(pos = nil, size = 1)
@@ -46,19 +46,27 @@ module Ferrum
     end
 
     def create_target
-      @client.command("Target.createTarget", browserContextId: @id, url: "about:blank")
-      target = @pendings.take(@client.timeout)
-      raise NoSuchTargetError unless target.is_a?(Target)
+      target_id = @client.command("Target.createTarget", browserContextId: @id, url: "about:blank")["targetId"]
 
-      target
+      new_pending = Concurrent::IVar.new
+      pending = @pendings.put_if_absent(target_id, new_pending) || new_pending
+      resolved = pending.value(@client.timeout)
+      raise NoSuchTargetError unless resolved
+
+      @pendings.delete(target_id)
+      @targets[target_id]
     end
 
     def add_target(params:, session_id: nil)
       new_target = Target.new(@client, session_id, params)
-      target = @targets.put_if_absent(new_target.id, new_target)
-      target ||= new_target # `put_if_absent` returns nil if added a new value or existing if there was one already
-      @pendings.put(target, @client.timeout) if @pendings.empty?
-      target
+      # `put_if_absent` returns nil if added a new value or existing if there was one already
+      target = @targets.put_if_absent(new_target.id, new_target) || new_target
+      @default_target ||= target
+
+      new_pending = Concurrent::IVar.new
+      pending = @pendings.put_if_absent(target.id, new_pending) || new_pending
+      pending.try_set(true)
+      true
     end
 
     def update_target(target_id, params)
@@ -69,6 +77,21 @@ module Ferrum
       @targets.delete(target_id)
     end
 
+    def attach_target(target_id)
+      target = @targets[target_id]
+      raise NoSuchTargetError unless target
+
+      session = @client.command("Target.attachToTarget", targetId: target_id, flatten: true)
+      target.session_id = session["sessionId"]
+      true
+    end
+
+    def find_target
+      @targets.each_value { |t| return t if yield(t) }
+
+      nil
+    end
+
     def close_targets_connection
       @targets.each_value do |target|
         next unless target.connected?