Merge pull request #189 from rubycdp/issue_171/implement_tracing

Implement Tracing

Author: route

CHANGELOG.md

@@ -22,6 +22,8 @@ a block with this page, after which the page is closed.
 - `Ferrum::Cookies#set` ability to set cookie using `Ferrum::Cookies::Cookie` object
 - `Ferrum::Network#emulate_network_conditions` activates emulation of network conditions
 - `Ferrum::Network#offline_mode` puts browser into offline mode
+- `Ferrum::Page#tracing` - instance of `Ferrum::Page::Tracing` for trace capabilities.
+- `Ferrum::Page::Tracing#record(&block)` start/stop tracing for steps provided in passed block
 
 ### Changed
 

README.md

@@ -48,6 +48,7 @@ based on Ferrum and Mechanize.
 * [Dialogs](https://github.com/rubycdp/ferrum#dialogs)
 * [Animation](https://github.com/rubycdp/ferrum#animation)
 * [Node](https://github.com/rubycdp/ferrum#node)
+* [Tracing](https://github.com/rubycdp/ferrum#tracing)
 * [Thread safety](https://github.com/rubycdp/ferrum#thread-safety)
 * [Development](https://github.com/rubycdp/ferrum#development)
 * [Contributing](https://github.com/rubycdp/ferrum#contributing)
@@ -1148,6 +1149,33 @@ browser.at_xpath("//*[select]").select(["1", "2"])
 ```
 
 
+## Tracing
+
+You can use `tracing.record` to create a trace file which can be opened in Chrome DevTools or
+[timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
+
+```ruby
+page.tracing.record(path: "trace.json") do
+  page.go_to("https://www.google.com")
+end
+```
+
+#### tracing.record(\*\*options) : `String`
+
+Accepts block, records trace and by default returns trace data from `Tracing.tracingComplete` event as output. When
+`path` is specified returns `true` and stores trace data into file.
+
+* options `Hash`
+  * :path `String` save data on the disk, `nil` by default
+  * :encoding `Symbol` `:base64` | `:binary` encode output as Base64 or plain text. `:binary` by default
+  * :timeout `Float` wait until file streaming finishes in the specified time or raise error, defaults to `nil`
+  * :screenshots `Boolean` capture screenshots in the trace, `false` by default
+  * :trace_config `Hash<String, Object>` 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.
+
+
 ## Thread safety ##
 
 Ferrum is fully thread-safe. You can create one browser or a few as you wish and

lib/ferrum/page.rb

@@ -10,6 +10,8 @@
 require "ferrum/page/frames"
 require "ferrum/page/screenshot"
 require "ferrum/page/animation"
+require "ferrum/page/tracing"
+require "ferrum/page/stream"
 require "ferrum/browser/client"
 
 module Ferrum
@@ -39,11 +41,13 @@ def reset
     include Animation
     include Screenshot
     include Frames
+    include Stream
 
     attr_accessor :referrer
     attr_reader :target_id, :browser,
                 :headers, :cookies, :network,
-                :mouse, :keyboard, :event
+                :mouse, :keyboard, :event,
+                :tracing
 
     def initialize(target_id, browser)
       @frames = {}
@@ -62,6 +66,7 @@ def initialize(target_id, browser)
       @headers = Headers.new(self)
       @cookies = Cookies.new(self)
       @network = Network.new(self)
+      @tracing = Tracing.new(self)
 
       subscribe
       prepare_page

lib/ferrum/page/screenshot.rb

@@ -26,8 +26,6 @@ module Screenshot
         A6: { width:  4.13, height:  5.83 }
       }.freeze
 
-      STREAM_CHUNK = 128 * 1024
-
       def screenshot(**opts)
         path, encoding = common_options(**opts)
         options = screenshot_options(path, **opts)
@@ -42,12 +40,7 @@ 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
 
       def mhtml(path: nil)
@@ -78,29 +71,6 @@ def save_file(path, data)
         File.binwrite(path.to_s, 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
-      end
-
       def common_options(encoding: :base64, path: nil, **_)
         encoding = encoding.to_sym
         encoding = :binary if path

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

lib/ferrum/page/tracing.rb

@@ -0,0 +1,71 @@
+# 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
+
+      def record(path: nil, encoding: :binary, timeout: nil, trace_config: nil, screenshots: false)
+        @path = path
+        @encoding = encoding
+        @result = Concurrent::Promises.resolvable_future
+        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
+
+        @result.value!(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
+
+          @result.fulfill(stream_handle(event["stream"]))
+        rescue StandardError => e
+          @result.reject(e)
+        end
+
+        @subscribed_tracing_complete = true
+      end
+
+      def stream_handle(handle)
+        @page.stream_to(path: @path, encoding: @encoding, handle: handle)
+      end
+    end
+  end
+end

spec/page/tracing_spec.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Ferrum
+  describe Page::Tracing do
+    let(:file_path) { "#{PROJECT_ROOT}/spec/tmp/trace.json" }
+    let(:file_path2) { "#{PROJECT_ROOT}/spec/tmp/trace2.json" }
+    let(:file_path3) { "#{PROJECT_ROOT}/spec/tmp/trace3.json" }
+    let(:content) { JSON.parse(File.read(file_path)) }
+    let(:trace_config) { JSON.parse(content["metadata"]["trace-config"]) }
+
+    it "outputs a trace" do
+      page.tracing.record(path: file_path) { page.go_to }
+
+      expect(File.exist?(file_path)).to be(true)
+    ensure
+      FileUtils.rm_f(file_path)
+    end
+
+    it "runs with custom options" do
+      page.tracing.record(
+        path: file_path,
+        trace_config: {
+          includedCategories: ["disabled-by-default-devtools.timeline"],
+          excludedCategories: ["*"]
+        }
+      ) { page.go_to }
+
+      expect(File.exist?(file_path)).to be(true)
+      expect(trace_config["excluded_categories"]).to eq(["*"])
+      expect(trace_config["included_categories"]).to eq(["disabled-by-default-devtools.timeline"])
+      expect(content["traceEvents"].any? { |o| o["cat"] == "toplevel" }).to eq(false)
+    ensure
+      FileUtils.rm_f(file_path)
+    end
+
+    it "runs with default categories" do
+      page.tracing.record(path: file_path) { page.go_to }
+
+      expect(File.exist?(file_path)).to be(true)
+      expect(trace_config["excluded_categories"]).to eq(["*"])
+      expect(trace_config["included_categories"])
+        .to match_array(%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])
+      expect(content["traceEvents"].any? { |o| o["cat"] == "toplevel" }).to eq(true)
+    ensure
+      FileUtils.rm_f(file_path)
+    end
+
+    it "throws an exception if tracing is on two pages" do
+      page.tracing.record(path: file_path) do
+        page.go_to
+
+        expect do
+          another = browser.create_page
+          another.tracing.record(path: file_path2) { another.go_to }
+        end.to raise_exception(Ferrum::BrowserError, "Tracing has already been started (possibly in another tab).")
+        expect(File.exist?(file_path2)).to be(false)
+      end
+
+      expect(File.exist?(file_path)).to be(true)
+    end
+
+    it "handles tracing complete event once" do
+      expect(page.tracing).to receive(:stream_handle).exactly(3).times.and_call_original
+
+      page.tracing.record(path: file_path) { page.go_to }
+      expect(File.exist?(file_path)).to be(true)
+
+      page.tracing.record(path: file_path2) { page.go_to }
+      expect(File.exist?(file_path2)).to be(true)
+
+      page.tracing.record(path: file_path3) { page.go_to }
+      expect(File.exist?(file_path3)).to be(true)
+    ensure
+      FileUtils.rm_f(file_path)
+      FileUtils.rm_f(file_path2)
+      FileUtils.rm_f(file_path3)
+    end
+
+    it "returns base64 encoded string" do
+      trace = page.tracing.record(encoding: :base64) { page.go_to }
+
+      decoded = Base64.decode64(trace)
+      content = JSON.parse(decoded)
+      expect(content["traceEvents"].any?).to eq(true)
+    end
+
+    it "returns buffer with no encoding" do
+      trace = page.tracing.record { page.go_to }
+
+      content = JSON.parse(trace)
+      expect(content["traceEvents"].any?).to eq(true)
+    end
+
+    context "screenshots enabled" do
+      it "fills file with screenshot data" do
+        page.tracing.record(path: file_path, screenshots: true) { page.go_to("/ferrum/grid") }
+
+        expect(File.exist?(file_path)).to be(true)
+        expect(trace_config["included_categories"]).to include("disabled-by-default-devtools.screenshot")
+        expect(content["traceEvents"].any? { |o| o["name"] == "Screenshot" }).to eq(true)
+      ensure
+        FileUtils.rm_f(file_path)
+      end
+
+      it "returns a buffer with screenshot data" do
+        trace = page.tracing.record(screenshots: true) { page.go_to("/ferrum/grid") }
+
+        expect(File.exist?(file_path)).to be(false)
+        content = JSON.parse(trace)
+        trace_config = JSON.parse(content["metadata"]["trace-config"])
+        expect(trace_config["included_categories"]).to include("disabled-by-default-devtools.screenshot")
+        expect(content["traceEvents"].any? { |o| o["name"] == "Screenshot" }).to eq(true)
+      end
+    end
+
+    it "waits for promise fill with timeout when it provided" do
+      expect(page.tracing).to receive(:subscribe_tracing_complete).with(no_args)
+      trace = page.tracing.record(timeout: 1) { page.go_to }
+      expect(trace).to be_nil
+    end
+  end
+end