ferrum-har 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 414fff66d2b47e26b96047c18388bde8a698c01809454be9b01f213dcf33de82
+  data.tar.gz: be6b275d34536d3220859ad031a8abf952140a8699211fc48124dbbbafe673f3
+SHA512:
+  metadata.gz: a617c9a354448656f0ca8fe3b5a8c58b889b009f3db3535eb0b0f19ac844806141cd3f9d19e3ea84e16fa2d4580abcd86dc851da20d41258606d252cf8055224
+  data.tar.gz: f8e60c45799a5b0654994df861e7890d65ce20871cfccdc343d5449092e1d2d13b37fdb05e1e9c54add2904c53602e1b5bea1ee6c7c9e82252bc52d4145ff552

data/README.md

@@ -0,0 +1,80 @@
+ferrum-har
+================
+
+[![Gem Version](https://img.shields.io/gem/v/ferrum-har?color=green)](https://img.shields.io/gem/v/ferrum-har?color=green)
+
+[ferrum-har](https://github.com/hlascelles/ferrum-har) is a gem that adds the ability to capture
+HAR files while running tests using [ferrum](https://github.com/rubycdp/ferrum)
+
+### Installation
+
+Add ferrum-har to your Gemfile and `bundle install`:
+
+```ruby
+gem "ferrum-har"
+```
+
+### Usage
+
+Use [ferrum](https://github.com/rubycdp/ferrum) as normal and call the `har` method on
+the `page` (or `browser`) object. Note, you will have to use some of the required browser options
+by using the `Ferrum::Har::REQUIRED_BROWSER_OPTIONS` constant. 
+
+Note, the devtools window in Chrome will be opened. This is mandatory to obtain the HAR from Chrome.
+
+```ruby
+browser = Ferrum::Browser.new(
+  browser_options: Ferrum::Har::REQUIRED_BROWSER_OPTIONS,
+)
+page = browser.create_page
+page.go_to("https://www.bbc.co.uk")
+
+# Returns the HAR as a JSON string
+puts page.har
+```
+
+### How it works
+
+Creating a HAR file from [ferrum](https://github.com/rubycdp/ferrum) network objects is complex and
+potentially incompatible with the HAR generated
+by other tools (including Chrome).
+
+Instead, ferrum-har contains a small Chrome extension that
+is automatically loaded into the test browser. When the `har` method is called, this extension
+asks the Chrome devtools Network panel for the HAR file and returns it to the Ruby process. This 
+means the HAR is always a valid version of exactly what Chrome would produce.
+
+The JS method that is ultimately called is `chrome.devtools.network.getHAR()` and you can read more 
+about it [here](https://developer.chrome.com/docs/extensions/reference/api/devtools/network#method-getHAR).
+
+One ramification of this is that the Chrome devtools must be open for the extension to work.
+
+To get the extension to be loaded we must pass some switches to the Chrome process via ferrum,
+specifically the `--auto-open-devtools-for-tabs` and `--load-extension` switches. This is done
+by the `Ferrum::Har::REQUIRED_BROWSER_OPTIONS` constant.
+
+For further reading, a full list of Chrome switches can be found
+[here](https://peter.sh/experiments/chromium-command-line-switches/).
+
+### Further work
+
+Some ideas for improvements.
+
+1. Add functionality to minimise the devtools sidepanel size.
+   To do this we would have to pass in a "profile" to the ferrum start switches like this:
+   ```ruby
+   "user-data-dir=profile" => "somedir"
+   ```
+   And have a "Default/Preferences" file in there that contains a sizing element like this:
+   ```json
+   {
+     "devtools": {
+       "preferences": {
+         "inspector-view.split-view-state": "{\"vertical\":{\"size\":1},\"horizontal\":{\"size\":0}}"
+       }
+     }
+   }
+   ```
+   However, that doesn't work as it stands as it is just a partial profile. We could add an entire
+   Chrome profile but that would be hundreds of files.
+2. Add GitHub Actions tests.

data/lib/ferrum/har/page_extension.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# This module is prepended to Ferrum::Page to add the #har method.
+module Ferrum
+  module Har
+    module PageExtension
+      class HarNotReadyError < RuntimeError
+        # Used to loop until the HAR is ready.
+      end
+
+      # This method waits until the page is idle, then fetches the HAR and decodes it.
+      def har
+        network.wait_for_idle
+        execute("document.ferrumHarRequested = true;")
+        base64_encoded_har = Ferrum::Utils::Attempt.with_retry(
+          errors: [HarNotReadyError],
+          max: 200,
+          wait: 0.5
+        ) do
+          found = evaluate("document.ferrumHar;")
+          raise HarNotReadyError unless found
+
+          found
+        end
+        inlined_har = Base64.decode64(base64_encoded_har)
+        har_hash = JSON.parse(inlined_har)
+        raise "Result does not appear to be a HAR" unless har_hash.key?("log")
+
+        JSON.pretty_generate(har_hash)
+      end
+    end
+  end
+end

data/lib/ferrum/har/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ferrum
+  module Har
+    VERSION = "0.1.0"
+  end
+end

data/lib/ferrum/har.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "ferrum"
+require "ferrum/har/version"
+require "ferrum/har/page_extension"
+
+module Ferrum
+  module Har
+    GEM_DIR = File.expand_path("../..", __dir__)
+    REQUIRED_BROWSER_OPTIONS = {
+      "auto-open-devtools-for-tabs" => nil, # The chrome devtools must be open to invoke getHAR
+      "load-extension" => "#{Ferrum::Har::GEM_DIR}/extension", # The extension that gets the HAR
+    }.freeze
+  end
+end
+
+# We have to remove the "disable-extensions" option from the default browser extension list because
+# the ferrum-har gem requires an (internal) extension to work.
+Ferrum::Browser::Options::Chrome::DEFAULT_OPTIONS =
+  Ferrum::Browser::Options::Chrome::DEFAULT_OPTIONS.except("disable-extensions")
+
+# Add the #har method to Ferrum::Page
+Ferrum::Page.prepend(Ferrum::Har::PageExtension)

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: ferrum-har
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Harry Lascelles
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-04-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Rubygem to convert ferrum traffic to HAR files
+email:
+- harry@harrylascelles.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ferrum/har.rb
+- lib/ferrum/har/page_extension.rb
+- lib/ferrum/har/version.rb
+homepage: https://github.com/hlascelles/ferrum-har
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hlascelles/ferrum-har
+  documentation_uri: https://github.com/hlascelles/ferrum-har
+  changelog_uri: https://github.com/hlascelles/ferrum-har/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/hlascelles/ferrum-har/
+  bug_tracker_uri: https://github.com/hlascelles/ferrum-har/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Rubygem to convert ferrum traffic to HAR files
+test_files: []