ferrum 0.11 → 0.13

data/lib/ferrum/page/frames.rb

@@ -5,41 +5,124 @@ require "ferrum/frame"
 module Ferrum
   class Page
     module Frames
+      # The page's main frame, the top of the tree and the parent of all frames.
+      #
+      # @return [Frame]
       attr_reader :main_frame
 
+      #
+      # Returns all the frames current page have.
+      #
+      # @return [Array<Frame>]
+      #
+      # @example
+      #   browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+      #   browser.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>,
+      #   #   ...
+      #   # ]
+      #
       def frames
         @frames.values
       end
 
-      def frame_by(id: nil, name: nil)
+      #
+      # Find frame by given options.
+      #
+      # @param [String] id
+      #   Unique frame's id that browser provides.
+      #
+      # @param [String] name
+      #   Frame's name if there's one.
+      #
+      # @param [String] execution_id
+      #   Frame's context execution id.
+      #
+      # @return [Frame, nil]
+      #   The matching frame.
+      #
+      # @example
+      #   browser.frame_by(id: "C6D104CE454A025FBCF22B98DE612B12")
+      #
+      def frame_by(id: nil, name: nil, execution_id: nil)
         if id
           @frames[id]
         elsif name
           frames.find { |f| f.name == name }
+        elsif execution_id
+          frames.find { |f| f.execution_id == execution_id }
         else
           raise ArgumentError
         end
       end
 
       def frames_subscribe
+        subscribe_frame_attached
+        subscribe_frame_detached
+        subscribe_frame_started_loading
+        subscribe_frame_navigated
+        subscribe_frame_stopped_loading
+
+        subscribe_navigated_within_document
+
+        subscribe_request_will_be_sent
+
+        subscribe_execution_context_created
+        subscribe_execution_context_destroyed
+        subscribe_execution_contexts_cleared
+      end
+
+      private
+
+      def subscribe_frame_attached
         on("Page.frameAttached") do |params|
           parent_frame_id, frame_id = params.values_at("parentFrameId", "frameId")
-          @frames[frame_id] = Frame.new(frame_id, self, parent_frame_id)
+          @frames.put_if_absent(frame_id, Frame.new(frame_id, self, parent_frame_id))
         end
+      end
+
+      def subscribe_frame_detached
+        on("Page.frameDetached") do |params|
+          frame = @frames[params["frameId"]]
+
+          if frame&.main?
+            frame.execution_id = nil
+          else
+            @frames.delete(params["frameId"])
+          end
+        end
+      end
 
+      def subscribe_frame_started_loading
         on("Page.frameStartedLoading") do |params|
           frame = @frames[params["frameId"]]
-          frame.state = :started_loading
+          frame.state = :started_loading if frame
           @event.reset
         end
+      end
 
+      def subscribe_frame_navigated
         on("Page.frameNavigated") do |params|
           frame_id, name = params["frame"]&.values_at("id", "name")
           frame = @frames[frame_id]
-          frame.state = :navigated
-          frame.name = name unless name.to_s.empty?
+
+          if frame
+            frame.state = :navigated
+            frame.name = name
+          end
         end
+      end
 
+      def subscribe_frame_stopped_loading
         on("Page.frameStoppedLoading") do |params|
           # `DOM.performSearch` doesn't work without getting #document node first.
           # It returns node with nodeId 1 and nodeType 9 from which descend the
@@ -47,7 +130,7 @@ module Ferrum
           # node will change the id and all subsequent nodes have to change id too.
           if @main_frame.id == params["frameId"]
             @event.set if idling?
-            get_document_id
+            document_node_id
           end
 
           frame = @frames[params["frameId"]]
@@ -55,60 +138,58 @@ module Ferrum
 
           @event.set if idling?
         end
+      end
 
+      def subscribe_navigated_within_document
         on("Page.navigatedWithinDocument") do
           @event.set if idling?
         end
+      end
 
+      def subscribe_request_will_be_sent
         on("Network.requestWillBeSent") do |params|
-          if params["frameId"] == @main_frame.id
-            # Possible types:
-            # Document, Stylesheet, Image, Media, Font, Script, TextTrack, XHR,
-            # Fetch, EventSource, WebSocket, Manifest, SignedExchange, Ping,
-            # CSPViolationReport, Other
-            @event.reset if params["type"] == "Document"
-          end
+          # Possible types:
+          # Document, Stylesheet, Image, Media, Font, Script, TextTrack, XHR,
+          # Fetch, EventSource, WebSocket, Manifest, SignedExchange, Ping,
+          # CSPViolationReport, Other
+          @event.reset if params["frameId"] == @main_frame.id && params["type"] == "Document"
         end
+      end
 
+      def subscribe_execution_context_created
         on("Runtime.executionContextCreated") do |params|
-          setting_up_main_frame = false
           context_id = params.dig("context", "id")
           frame_id = params.dig("context", "auxData", "frameId")
 
           unless @main_frame.id
             root_frame = command("Page.getFrameTree").dig("frameTree", "frame", "id")
             if frame_id == root_frame
-              setting_up_main_frame = true
               @main_frame.id = frame_id
-              @frames[frame_id] = @main_frame
+              @frames.put_if_absent(frame_id, @main_frame)
             end
           end
 
-          frame = @frames[frame_id] || Frame.new(frame_id, self)
-          frame.set_execution_id(context_id)
-
-          # Set event because `execution_id` might raise NoExecutionContextError
-          @event.set if setting_up_main_frame
-
-          @frames[frame_id] ||= frame
+          frame = @frames.fetch_or_store(frame_id, Frame.new(frame_id, self))
+          frame.execution_id = context_id
         end
+      end
 
+      def subscribe_execution_context_destroyed
         on("Runtime.executionContextDestroyed") do |params|
           execution_id = params["executionContextId"]
-          frame = frames.find { |f| f.execution_id?(execution_id) }
-          frame.reset_execution_id
+          frame = frame_by(execution_id: execution_id)
+          frame&.execution_id = nil
         end
+      end
 
+      def subscribe_execution_contexts_cleared
         on("Runtime.executionContextsCleared") do
-          @frames.delete_if { |_, f| !f.main? }
-          @main_frame.reset_execution_id
+          @frames.each_value { |f| f.execution_id = nil }
         end
       end
 
-      private
-
       def idling?
-        @frames.all? { |_, f| f.state == :stopped_loading }
+        @frames.values.all? { |f| f.state == :stopped_loading }
       end
     end
   end

data/lib/ferrum/page/screenshot.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "ferrum/rbga"
+require "ferrum/rgba"
 
 module Ferrum
   class Page
@@ -13,21 +13,64 @@ module Ferrum
       }.freeze
 
       PAPER_FORMATS = {
-        letter:   { width:  8.50, height: 11.00 },
-        legal:    { width:  8.50, height: 14.00 },
-        tabloid:  { width: 11.00, height: 17.00 },
-        ledger:   { width: 17.00, height: 11.00 },
-        A0:       { width: 33.10, height: 46.80 },
-        A1:       { width: 23.40, height: 33.10 },
-        A2:       { width: 16.54, height: 23.40 },
-        A3:       { width: 11.70, height: 16.54 },
-        A4:       { width:  8.27, height: 11.70 },
-        A5:       { width:  5.83, height:  8.27 },
-        A6:       { width:  4.13, height:  5.83 },
+        letter: { width: 8.50, height: 11.00 },
+        legal: { width: 8.50, height: 14.00 },
+        tabloid: { width: 11.00, height: 17.00 },
+        ledger: { width: 17.00, height: 11.00 },
+        A0: { width: 33.10, height: 46.80 },
+        A1: { width: 23.40, height: 33.10 },
+        A2: { width: 16.54, height: 23.40 },
+        A3: { width: 11.70, height: 16.54 },
+        A4: { width:  8.27, height: 11.70 },
+        A5: { width:  5.83, height:  8.27 },
+        A6: { width:  4.13, height:  5.83 }
       }.freeze
 
-      STREAM_CHUNK = 128 * 1024
-
+      #
+      # Saves screenshot on a disk or returns it as base64.
+      #
+      # @param [Hash{Symbol => Object}] opts
+      #
+      # @option opts [String] :path
+      #  The path to save a screenshot on the disk. `:encoding` will be set to
+      #  `:binary` automatically.
+      #
+      # @option opts [:base64, :binary] :encoding
+      #   The encoding the image should be returned in.
+      #
+      # @option opts ["jpeg", "png"] :format
+      #   The format the image should be returned in.
+      #
+      # @option opts [Integer] :quality
+      #   The image quality. **Note:** 0-100 works for jpeg only.
+      #
+      # @option opts [Boolean] :full
+      #   Whether you need full page screenshot or a viewport.
+      #
+      # @option opts [String] :selector
+      #   CSS selector for the given element.
+      #
+      # @option opts [Float] :scale
+      #   Zoom in/out.
+      #
+      # @option opts [Ferrum::RGBA] :background_color
+      #   Sets the background color.
+      #
+      # @example
+      #   browser.go_to("https://google.com/")
+      #
+      # @example Save on the disk in PNG:
+      #   browser.screenshot(path: "google.png") # => 134660
+      #
+      # @example Save on the disk in JPG:
+      #   browser.screenshot(path: "google.jpg") # => 30902
+      #
+      # @example Save to Base64 the whole page not only viewport and reduce quality:
+      #   browser.screenshot(full: true, quality: 60) # "iVBORw0KGgoAAAANS...
+      #
+      # @example Save with specific background color:
+      #   browser.screenshot(background_color: Ferrum::RGBA.new(0, 0, 0, 0.0))
+      #
       def screenshot(**opts)
         path, encoding = common_options(**opts)
         options = screenshot_options(path, **opts)
@@ -38,21 +81,63 @@ module Ferrum
         save_file(path, bin)
       end
 
+      #
+      # Saves PDF on a disk or returns it as Base64.
+      #
+      # @param [Hash{Symbol => Object}] opts
+      #
+      # @option opts [String] :path
+      #  The path to save a screenshot on the disk. `:encoding` will be set to
+      #  `:binary` automatically.
+      #
+      # @option opts [:base64, :binary] :encoding
+      #   The encoding the image should be returned in.
+      #
+      # @option opts [Boolean] :landscape (false)
+      #   Page orientation.
+      #
+      # @option opts [Float] :scale
+      #   Zoom in/out.
+      #
+      # @option opts [:letter, :legal, :tabloid, :ledger, :A0, :A1, :A2, :A3, :A4, :A5, :A6] :format
+      #   The standard paper size.
+      #
+      # @option opts [Float] :paper_width
+      #   Sets the paper's width.
+      #
+      # @option opts [Float] :paper_height
+      #   Sets the paper's height.
+      #
+      # @note
+      #   See other [native options](https://chromedevtools.github.io/devtools-protocol/tot/Page#method-printToPDF) you
+      #   can pass.
+      #
+      # @example
+      #   browser.go_to("https://google.com/")
+      #   # Save to disk as a PDF
+      #   browser.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => true
+      #
       def pdf(**opts)
         path, encoding = common_options(**opts)
         options = pdf_options(**opts).merge(transferMode: "ReturnAsStream")
         handle = command("Page.printToPDF", **options).fetch("stream")
-
-        if path
-          stream_to_file(handle, path: path)
-        else
-          stream_to_memory(handle, encoding: encoding)
-        end
+        stream_to(path: path, encoding: encoding, handle: handle)
       end
 
+      #
+      # Saves MHTML on a disk or returns it as a string.
+      #
+      # @param [String, nil] path
+      #   The path to save a file on the disk.
+      #
+      # @example
+      #   browser.go_to("https://google.com/")
+      #   browser.mhtml(path: "google.mhtml") # => 87742
+      #
       def mhtml(path: nil)
         data = command("Page.captureSnapshot", format: :mhtml).fetch("data")
         return data if path.nil?
+
         save_file(path, data)
       end
 
@@ -73,30 +158,8 @@ module Ferrum
 
       def save_file(path, data)
         return data unless path
-        File.open(path.to_s, "wb") { |f| f.write(data) }
-      end
 
-      def stream_to_file(handle, path:)
-        File.open(path, "wb") { |f| stream_to(handle, f) }
-        true
-      end
-
-      def stream_to_memory(handle, encoding:)
-        data = String.new("") # Mutable string has << and compatible to File
-        stream_to(handle, data)
-        encoding == :base64 ? Base64.encode64(data) : data
-      end
-
-      def stream_to(handle, output)
-        loop do
-          result = command("IO.read", handle: handle, size: STREAM_CHUNK)
-
-          data_chunk = result["data"]
-          data_chunk = Base64.decode64(data_chunk) if result["base64Encoded"]
-          output << data_chunk
-
-          break if result["eof"]
-        end
+        File.binwrite(path.to_s, data)
       end
 
       def common_options(encoding: :base64, path: nil, **_)
@@ -119,44 +182,57 @@ module Ferrum
                          paper_height: dimension[:height])
         end
 
-        options.map { |k, v| [to_camel_case(k), v] }.to_h
+        options.transform_keys { |k| to_camel_case(k) }
       end
 
-      def screenshot_options(path = nil, format: nil, scale: 1.0, **opts)
-        options = {}
+      def screenshot_options(path = nil, format: nil, scale: 1.0, **options)
+        screenshot_options = {}
+
+        format, quality = format_options(format, path, options[:quality])
+        screenshot_options.merge!(quality: quality) if quality
+        screenshot_options.merge!(format: format)
+
+        clip = area_options(options[:full], options[:selector], scale)
+        screenshot_options.merge!(clip: clip) if clip
+
+        screenshot_options
+      end
 
+      def format_options(format, path, quality)
         format ||= path ? File.extname(path).delete(".") : "png"
         format = "jpeg" if format == "jpg"
         raise "Not supported options `:format` #{format}. jpeg | png" if format !~ /jpeg|png/i
-        options.merge!(format: format)
 
-        options.merge!(quality: opts[:quality] ? opts[:quality] : 75) if format == "jpeg"
+        quality ||= 75 if format == "jpeg"
 
-        if !!opts[:full] && opts[:selector]
-          warn "Ignoring :selector in #screenshot since full: true was given at #{caller(1..1).first}"
-        end
+        [format, quality]
+      end
 
-        if !!opts[:full]
-          width, height = document_size
-          options.merge!(clip: { x: 0, y: 0, width: width, height: height, scale: scale }) if width > 0 && height > 0
-        elsif opts[:selector]
-          options.merge!(clip: get_bounding_rect(opts[:selector]).merge(scale: scale))
-        end
+      def area_options(full, selector, scale)
+        message = "Ignoring :selector in #screenshot since full: true was given at #{caller(1..1).first}"
+        warn(message) if full && selector
 
-        if scale != 1.0
-          if !options[:clip]
+        clip = if full
+                 width, height = document_size
+                 { x: 0, y: 0, width: width, height: height, scale: scale } if width.positive? && height.positive?
+               elsif selector
+                 bounding_rect(selector).merge(scale: scale)
+               end
+
+        if scale != 1
+          unless clip
             width, height = viewport_size
-            options[:clip] = { x: 0, y: 0, width: width, height: height }
+            clip = { x: 0, y: 0, width: width, height: height }
           end
 
-          options[:clip].merge!(scale: scale)
+          clip.merge!(scale: scale)
         end
 
-        options
+        clip
       end
 
-      def get_bounding_rect(selector)
-        rect = evaluate_async(%Q(
+      def bounding_rect(selector)
+        rect = evaluate_async(%(
           const rect = document
                          .querySelector('#{selector}')
                          .getBoundingClientRect();
@@ -169,7 +245,8 @@ module Ferrum
 
       def to_camel_case(option)
         return :preferCSSPageSize if option == :prefer_css_page_size
-        option.to_s.gsub(/(?:_|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" }.to_sym
+
+        option.to_s.gsub(%r{(?:_|(/))([a-z\d]*)}) { "#{Regexp.last_match(1)}#{Regexp.last_match(2).capitalize}" }.to_sym
       end
 
       def capture_screenshot(options, full, background_color)

data/lib/ferrum/page/stream.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ferrum
+  class Page
+    module Stream
+      STREAM_CHUNK = 128 * 1024
+
+      def stream_to(path:, encoding:, handle:)
+        if path.nil?
+          stream_to_memory(encoding: encoding, handle: handle)
+        else
+          stream_to_file(path: path, handle: handle)
+        end
+      end
+
+      def stream_to_file(path:, handle:)
+        File.open(path, "wb") { |f| stream(output: f, handle: handle) }
+        true
+      end
+
+      def stream_to_memory(encoding:, handle:)
+        data = String.new # Mutable string has << and compatible to File
+        stream(output: data, handle: handle)
+        encoding == :base64 ? Base64.encode64(data) : data
+      end
+
+      def stream(output:, handle:)
+        loop do
+          result = command("IO.read", handle: handle, size: STREAM_CHUNK)
+          chunk = result.fetch("data")
+          chunk = Base64.decode64(chunk) if result["base64Encoded"]
+          output << chunk
+          break if result["eof"]
+        end
+      end
+    end
+  end
+end

data/lib/ferrum/page/tracing.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Ferrum
+  class Page
+    class Tracing
+      EXCLUDED_CATEGORIES = %w[*].freeze
+      SCREENSHOT_CATEGORIES = %w[disabled-by-default-devtools.screenshot].freeze
+      INCLUDED_CATEGORIES = %w[devtools.timeline v8.execute disabled-by-default-devtools.timeline
+                               disabled-by-default-devtools.timeline.frame toplevel blink.console
+                               blink.user_timing latencyInfo disabled-by-default-devtools.timeline.stack
+                               disabled-by-default-v8.cpu_profiler disabled-by-default-v8.cpu_profiler.hires].freeze
+      DEFAULT_TRACE_CONFIG = {
+        includedCategories: INCLUDED_CATEGORIES,
+        excludedCategories: EXCLUDED_CATEGORIES
+      }.freeze
+
+      def initialize(page)
+        @page = page
+        @subscribed_tracing_complete = false
+      end
+
+      #
+      # Accepts block, records trace and by default returns trace data from `Tracing.tracingComplete` event as output.
+      #
+      # @param [String, nil] path
+      #   Save data on the disk.
+      #
+      # @param [:binary, :base64] encoding
+      #   Encode output as Base64 or plain text.
+      #
+      # @param [Float, nil] timeout
+      #   Wait until file streaming finishes in the specified time or raise
+      #   error.
+      #
+      # @param [Boolean] screenshots
+      #   capture screenshots in the trace.
+      #
+      # @param [Hash{String => Object}] trace_config
+      #   config for [trace](https://chromedevtools.github.io/devtools-protocol/tot/Tracing/#type-TraceConfig),
+      #   for categories see [getCategories](https://chromedevtools.github.io/devtools-protocol/tot/Tracing/#method-getCategories),
+      #   only one trace config can be active at a time per browser.
+      #
+      # @return [String, true]
+      #   The trace data from the `Tracing.tracingComplete` event.
+      #   When `path` is specified returns `true` and stores trace data into
+      #   file.
+      #
+      def record(path: nil, encoding: :binary, timeout: nil, trace_config: nil, screenshots: false)
+        @path = path
+        @encoding = encoding
+        @pending = Concurrent::IVar.new
+        trace_config ||= DEFAULT_TRACE_CONFIG.dup
+
+        if screenshots
+          included = trace_config.fetch(:includedCategories, [])
+          trace_config.merge!(includedCategories: included | SCREENSHOT_CATEGORIES)
+        end
+
+        subscribe_tracing_complete
+
+        start(trace_config)
+        yield
+        stop
+
+        @pending.value!(timeout || @page.timeout)
+      end
+
+      private
+
+      def start(config)
+        @page.command("Tracing.start", transferMode: "ReturnAsStream", traceConfig: config)
+      end
+
+      def stop
+        @page.command("Tracing.end")
+      end
+
+      def subscribe_tracing_complete
+        return if @subscribed_tracing_complete
+
+        @page.on("Tracing.tracingComplete") do |event, index|
+          next if index.to_i != 0
+
+          @pending.set(stream_handle(event["stream"]))
+        rescue StandardError => e
+          @pending.fail(e)
+        end
+
+        @subscribed_tracing_complete = true
+      end
+
+      def stream_handle(handle)
+        @page.stream_to(path: @path, encoding: @encoding, handle: handle)
+      end
+    end
+  end
+end