ui-delta 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f63d66c2d5cef64287cc988cf52a98b42d429ea7c7069cf1dc307962526e97eb
+  data.tar.gz: 453388fb69e832e4c1edd49dd2fd2c5e90e6e280530868db8740b48ea0b6c315
+SHA512:
+  metadata.gz: 3a17e3efdac19225c5ed36e70048eee2a24d6134d067cc8fcc694e020012894eb7767f234cc9839f115ec1c141a483c6045de09d6f78177a44ea2c1ce26925ed
+  data.tar.gz: 8bf9d6b4bd7304bce8c44b69a6ae11c2182e6aa4a1660c6b82f35ff6400b2e17aabcfd701f6167e3dc4b0077fdbab3ae360d103a0194a3af4aff36dba3fa0451

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015-2024 Codemancers
+
+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/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'UI Delta'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/Readme.md

@@ -0,0 +1,124 @@
+# UI Delta
+
+Currently this supports only RSpec.
+
+### Installation
+
+```rb
+gem 'ui-delta'
+```
+
+### Configuration
+
+Include `ui-delta` in your rspec `spec_helper` and configure 6 variables
+which will be used while taking screenshots. Make sure that `enable_service` is
+set to true if images need to be uploaded.
+
+**NOTE:** Make sure that that project exists in service with `project_name`. Also
+api key can be obtained by loggin into service and visiting `/api_key`.
+
+
+```rb
+UiDelta.configure do |config|
+  # configure domain to which all images have to be uploaded.
+  config.base_uri = "http://idf.dev"
+
+  # configure project name to which images belong to.
+  config.project_name = "idf"
+
+  # configure api_key required to authorize api access
+  config.api_key = ENV["UI_DELTA_API_KEY"]
+
+  # configure js driver which is used for taking screenshots.
+  config.javascript_driver = "poltergeist"
+
+  # configure service to mock capturing and uploading screenshots
+  config.enable_service = !!ENV["UI_DELTA_ENABLE"]
+
+  # configure logger to log messages. optional.
+  config.logger = Rails.logger
+end
+```
+
+After configuration, include `UiDelta::Dsl` in your `spec_helper` and
+configure before and after suite so that suite interacts with the service.
+
+
+```rb
+RSpec.configure do |config|
+  config.include UiDelta::Dsl
+
+  config.before(:suite) do
+    UiDelta.start_run
+  end
+
+  config.after(:suite) do
+    UiDelta.wrap_run
+  end
+end
+```
+
+### Usage
+
+In your specs, simply use `ui-delta` helper which has bunch of config utilities.
+
+First, you should specify environment details under which screenshots are
+taken. There are 6 parameters which can be configured.
+
+Parameter|Explanation
+---------|-----------
+browser  | which browser is used to take screenshots. default: 'firefox'
+         | supported: firefox, chrome, safari, ie, opera
+device   | which device is used to take screenshots. default: 'desktop'
+         | supported: desktop, laptop, tablet, phone
+os       | which os is used to take screenshots. default: 'linux'
+         | supported: android, ios, windows, osx, linux
+browser_version | (optional) version of browser used, for eg: '46' for firefox
+device_name     | (optional) name of device, for eg: 'MacBook Air'
+os_version      | (optional) version of os used, for eg: '10.11'
+
+
+They can be configured using `ui-delta` helper while running specs. For eg:
+
+```rb
+ui_delta.browser = 'firefox'
+ui_delta.device = 'laptop'
+ui_delta.os = 'osx'
+ui_delta.browser_version = '46'
+ui_delta.device_name = 'MBA'
+ui_delta.os_version = '10.11.5'
+```
+
+Also, `ui-delta` can used to take screenshots also. Make sure that you pass
+unique identifier to screenshots that you take. unique identifier helps
+in differentiating this screenshot taken from other screenshots for a
+given set of `browser`, `device`, and `os`.
+
+
+```rb
+describe "Landing page" do
+  it "has a big banner" do
+    visit root_path
+
+    ui_delta.browser = 'chrome'
+    ui_delta.screenshot("unique-identifier")
+  end
+end
+```
+
+Since there is flexibility to specify `browser`, `device`, and `os` while
+running specs dynamically (unlike specifying `project_name`), you can run
+all your specs in a loop by changing `browser`, `device` and `os` by
+changing selenium driver, or changing viewport etc. Flexibility for your
+service!
+
+
+### Concurrency
+
+By default, when all the screenshots are collected, and before suite ends, this
+gem will upload all the screenshots taken. `UiDelta.wrap_run` is the method
+responsible for the same.
+
+However, if you want to upload screenshots as and when they are taken, this gem
+has soft dependency on `concurrent-ruby` gem. Make sure that this gem is
+**required** before capturing screenshots, and see the magic yourself :)

data/lib/ui-delta.rb

@@ -0,0 +1 @@
+require 'ui_delta'

data/lib/ui_delta/dsl.rb

@@ -0,0 +1,22 @@
+module UiDelta
+  module Dsl
+    def self.ui_delta
+      @ui_delta ||=
+        begin
+          klass =
+            if UiDelta.enable_service
+              UiDelta::Runner
+            else
+              UiDelta::DummyRunner
+            end
+
+          UiDelta.logger.info "Using runner #{klass}"
+          klass.instance
+        end
+    end
+
+    def ui_delta
+      UiDelta::Dsl.ui_delta
+    end
+  end
+end

data/lib/ui_delta/dummy_runner.rb

@@ -0,0 +1,19 @@
+module UiDelta
+  class DummyRunner
+    def self.instance
+      @runner ||= DummyRunner.new
+    end
+
+    attr_accessor :browser, :device, :os
+    attr_accessor :browser_version, :device_name, :os_version
+
+    def start_run
+    end
+
+    def wrap_run
+    end
+
+    def screenshot(_)
+    end
+  end
+end

data/lib/ui_delta/run_details.rb

@@ -0,0 +1,55 @@
+module UiDelta
+  class RunDetails
+    class Jenkins
+      def branch
+        ENV.fetch('GIT_BRANCH').split('/').last
+      end
+
+      def author
+        'Jenkins'.freeze
+      end
+    end
+
+    class Travis
+      def branch
+        ENV.fetch('TRAVIS_BRANCH')
+      end
+
+      def author
+        'Travis'.freeze
+      end
+    end
+
+    class GitRepo
+      def branch
+        `git rev-parse --abbrev-ref HEAD`.strip
+      end
+
+      def author
+        `git config user.name`.strip
+      end
+    end
+
+    class Default
+      def branch
+        'HEAD'.freeze
+      end
+
+      def author
+        'None'.freeze
+      end
+    end
+
+    def details
+      if !!ENV['JENKINS_HOME']
+        Jenkins.new
+      elsif !!ENV['TRAVIS']
+        Travis.new
+      elsif system('git branch')
+        GitRepo.new
+      else
+        Default.new
+      end
+    end
+  end
+end

data/lib/ui_delta/runner.rb

@@ -0,0 +1,95 @@
+require 'time'
+require 'json'
+require 'ui_delta/run_details'
+require 'ui_delta/uploader'
+require 'ui_delta/utils'
+
+module UiDelta
+  class Runner
+    include Capybara::DSL
+
+    def self.instance
+      @runner ||= Runner.new(UiDelta.project_name,
+                             UiDelta.javascript_driver)
+    end
+
+    attr_accessor :browser, :device, :os
+    attr_accessor :browser_version, :device_name, :os_version
+
+    def initialize(project_name, javascript_driver)
+      @project_name = project_name
+      @javascript_driver = javascript_driver
+
+      dir = UiDelta::Utils.images_dir
+      Dir.mkdir('tmp') unless Dir.exist?('tmp')
+      Dir.mkdir(dir) unless Dir.exist?(dir)
+
+      self.browser = 'firefox'
+      self.device = 'desktop'
+      self.os = 'linux'
+    end
+
+    # TODO: Improve error handling here for network timeouts
+    def start_run
+      draft_run
+      @uploader = UiDelta::Uploader.build(@run_id)
+    rescue StandardError => e
+      UiDelta.logger.fatal e.message
+      raise e
+    end
+
+    # TODO: Improve error handling here for network timeouts
+    def wrap_run
+      @uploader.wrapup
+
+      complete_run if @run_id
+    rescue StandardError => e
+      UiDelta.logger.fatal e.message
+      raise e
+    end
+
+    def screenshot(identifier)
+      raise 'no browser information provided' if browser.nil?
+      raise 'no device information provided' if device.nil?
+      raise 'no os information provided' if os.nil?
+
+      screenshot_name = UiDelta::Utils.image_file(identifier)
+      # set windows size equal to page width and height
+      # TODO: may support portrait resolutions
+      # assuming the device is in landscape orientation
+      width = page.driver.execute_script('return document.body.parentNode.scrollWidth')
+      height = page.driver.execute_script('return document.body.parentNode.scrollHeight')
+      page.driver.browser.manage.window.resize_to(width, height)
+
+      # save the screenshot
+      page.save_screenshot(screenshot_name, full_page: true)
+      @uploader.enqueue(identifier, browser, device, os, browser_version,
+                        device_name, os_version, width, height)
+    end
+
+    private
+
+    def draft_run
+      run_name = @project_name + "-" + Time.now.iso8601
+
+      details = Ui-Delta::RunDetails.new.details
+      branch = details.branch
+      author = details.author
+      project = @project_name
+
+      response = connection.post('/api/v1/runs',
+                                 name: run_name, project: project, group: branch,
+                                 author: author, js_driver: @javascript_driver)
+
+      @run_id = JSON.parse(response.body)["id"]
+    end
+
+    def complete_run
+      connection.put("/api/v1/runs/#{@run_id}/status", status: "completed")
+    end
+
+    def connection
+      @connection ||= Ui-Delta::Utils.connection
+    end
+  end
+end

data/lib/ui_delta/uploader.rb

@@ -0,0 +1,13 @@
+module UiDelta
+  class Uploader
+    def self.build(run_id)
+      if defined?(::Concurrent)
+        require 'ui_delta/uploaders/concurrent'
+        UiDelta::Uploaders::Concurrent.new(run_id)
+      else
+        require 'ui_delta/uploaders/sequential'
+        UiDelta::Uploaders::Sequential.new(run_id)
+      end
+    end
+  end
+end

data/lib/ui_delta/uploaders/concurrent.rb

@@ -0,0 +1,41 @@
+require 'uidelta/utils'
+
+module UiDelta
+  module Uploaders
+    class Concurrent
+      MAX_NO_OF_THREADS = 20
+
+      def initialize(run_id)
+        @run_id = run_id
+        @pool = ::Concurrent::FixedThreadPool.new(MAX_NO_OF_THREADS)
+        @screenshots_taken = 0
+      end
+
+      def enqueue(identifier, browser, device, os, browser_version,
+                  device_name, os_version, image_width, image_height)
+        @screenshots_taken += 1
+
+        @pool.post do
+          UiDelta::Utils
+            .upload_image(@run_id, identifier, browser, device, os,
+                          browser_version, device_name, os_version, image_width, image_height)
+        end
+      end
+
+      def wrapup
+        retries = 180           # 30 mins
+
+        # if all screenshots are not uploaded, wait.
+        until @screenshots_taken == @pool.completed_task_count
+          retries -= 1
+          break if retries.zero?
+
+          sleep 10
+        end
+
+        @pool.shutdown
+        @pool.wait_for_termination
+      end
+    end
+  end
+end

data/lib/ui_delta/uploaders/sequential.rb

@@ -0,0 +1,28 @@
+require 'ui_delta/utils'
+
+module UiDelta
+  module Uploaders
+    class Sequential
+      def initialize(run_id)
+        @run_id = run_id
+        @identifiers_with_env = []
+      end
+
+      def enqueue(identifier, browser, device, os, browser_version,
+                  device_name, os_version, image_width, image_height)
+        @identifiers_with_env << [identifier, browser, device, os,
+                                  browser_version, device_name,
+                                  os_version, image_width, image_height]
+      end
+
+      def wrapup
+        @identifiers_with_env
+          .each do |identifier, browser, device, os, browser_version, device_name, os_version, image_width, image_height|
+          UiDelta::Utils
+            .upload_image(@run_id, identifier, browser, device, os,
+                          browser_version, device_name, os_version, image_width, image_height)
+        end
+      end
+    end
+  end
+end

data/lib/ui_delta/utils.rb

@@ -0,0 +1,49 @@
+module UiDelta
+  module Utils
+    # http connection that will be used for uploading images
+    def self.connection
+      base_uri = UiDelta.base_uri
+      Faraday.new(base_uri, request: { timeout: 120, open_timeout: 120 }) do |f|
+        f.request :basic_auth, UiDelta.api_key, 'X'
+        f.request :multipart
+        f.request :url_encoded
+        f.adapter :net_http
+      end
+    end
+
+    def self.images_dir
+      'tmp/ui_delta'.freeze
+    end
+
+    def self.upload_image(run_id, identifier, browser, device, os, browser_version,
+                          device_name, os_version, image_width, image_height)
+      image_content = File.open(image_file(identifier), 'rb').read
+      data = get_presigned_url(run_id, identifier)
+
+      # upload to S3 directly
+      resp = Faraday.put(data["presign_url"], image_content)
+      unless resp.status == 200
+        raise "Failed to complete UiDelta image [#{identifier}.png] upload"
+      end
+
+      # create the run image on UiDelta
+      connection.post("/api/v1/runs/#{run_id}/run_images",
+                      image: data["image_url"], image_width: image_width, image_height: image_height,
+                      identifier: identifier, browser: browser,
+                      device: device, os: os, browser_version: browser_version,
+                      device_name: device_name, os_version: os_version)
+    end
+
+    def self.image_file(identifier)
+      "#{Dir.pwd}/#{images_dir}/#{identifier}.png"
+    end
+
+    def self.get_presigned_url(run_id, identifier)
+      resp = connection.post(
+        "/api/v1/runs/#{run_id}/run_images/presigned-url",
+        filename: "#{identifier}.png"
+      )
+      JSON.parse resp.body
+    end
+  end
+end

data/lib/ui_delta/version.rb

@@ -0,0 +1,3 @@
+module UiDelta
+  VERSION = "0.5.0"
+end

data/lib/ui_delta.rb

@@ -0,0 +1,77 @@
+require 'faraday'
+require 'ui_delta/dummy_runner'
+require 'ui_delta/runner'
+require 'ui_delta/dsl'
+require 'logger'
+
+module UiDelta
+  # configure domain to which all images have to be uploaded.
+  @@base_uri = "https://ui-delta.fly.dev"
+  def self.base_uri=(uri)
+    @@base_uri = uri
+  end
+  def self.base_uri
+    @@base_uri
+  end
+
+  # configure project name to which images belong to.
+  @@project_name = "idf"
+  def self.project_name=(name)
+    @@project_name = name
+  end
+  def self.project_name
+    @@project_name
+  end
+
+  # configure api_key required to authorize api access
+  @@api_key = ''
+  def self.api_key=(key)
+    @@api_key = key
+  end
+  def self.api_key
+    @@api_key
+  end
+
+  # configure js driver which is used for taking screenshots.
+  @@javascript_driver = "poltergeist"
+  def self.javascript_driver=(driver)
+    @@javascript_driver = driver
+  end
+  def self.javascript_driver
+    @@javascript_driver
+  end
+
+  # configure service to be mocked so that no screenshots are
+  # taken, and uploaded to service.
+  @@enable_service = false
+  def self.enable_service=(enable)
+    @@enable_service = enable
+  end
+  def self.enable_service
+    @@enable_service
+  end
+
+  # configure logger, which will be used to log issues if any
+  @@logger = Logger.new(STDOUT)
+  def self.logger=(new_logger)
+    @@logger = new_logger
+  end
+  def self.logger
+    @@logger
+  end
+
+  # helper to configure above variables.
+  def self.configure
+    yield(self)
+  end
+
+  # helps in setting up the run
+  def self.start_run
+    UiDelta::Dsl.ui_delta.start_run
+  end
+
+  # helps in wrapping up run by uploading images
+  def self.wrap_run
+    UiDelta::Dsl.ui_delta.wrap_run
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: ui-delta
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Yuva
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-02-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  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: Rails integration for ui-delta service
+email:
+- yuva@codemancers.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- Rakefile
+- Readme.md
+- lib/ui-delta.rb
+- lib/ui_delta.rb
+- lib/ui_delta/dsl.rb
+- lib/ui_delta/dummy_runner.rb
+- lib/ui_delta/run_details.rb
+- lib/ui_delta/runner.rb
+- lib/ui_delta/uploader.rb
+- lib/ui_delta/uploaders/concurrent.rb
+- lib/ui_delta/uploaders/sequential.rb
+- lib/ui_delta/utils.rb
+- lib/ui_delta/version.rb
+homepage: https://ui-delta.fly.dev
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Rails integration for ui-delta service
+test_files: []