percy-appium-app 0.0.1 → 0.0.2.pre.beta.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba54dc346521591705be68354e98b25018a98a1af988b9d05c7b3e6d6120b92f
-  data.tar.gz: 5fe4abc08f138a09c1f5c95f327f9bebb8c9d4f7899cd0ffbe233d2d95cb5e86
+  metadata.gz: dc24fb11453d4229be74084dcbf4fd87956c644bea38edf77b841cb154e4e214
+  data.tar.gz: cfdf2bf47fc198a729020862676caf4580a9a40df65c47264e2b614ae9869c4e
 SHA512:
-  metadata.gz: 5434a1ce14329a48bf5411050de8c466ec40e77f3545fa159d566d077d28d88ce027a7ed87ea3a3cf0cc6a851350376a7218d93e6250de93cc165e5ba6179196
-  data.tar.gz: 2a8f9febe81d0490ed25d4f8bca3a2b24851a62d5c51ea33527629e72e810de9a4e0e94593f88727ffe42c25237c43aab785529d1e7bb4d24b5fd81488fedd8e
+  metadata.gz: 49ba2a7afbd146dc3e4c32052f769c7359a79e8e8ec62fd11147da1f950d4dbc4e892c5a63f6d2851848f75e163d4e19eeca5f8c56c21d0db848004d285dcd9f
+  data.tar.gz: 77cb99772da0e0739dcbe64085d138c689981d7d40942363edf6642da81cd96cded01d3614eedd31f682a88bef35dd8d0ec59a69633ace69f9b6cc92e6f42b3a

data/Gemfile

@@ -11,3 +11,4 @@ gem 'tempfile'
 gem 'webmock', '~> 3.18', '>= 3.18.1'
 gem 'webrick', '~> 1.3', '>= 1.3.1'
 gem 'rake', '~> 13.0'
+gem 'rspec-core'

data/README.md

@@ -1 +1,193 @@
-# percy-appium-ruby
+# percy-appium-ruby
+
+[Percy](https://percy.io) visual testing for Ruby Appium.
+
+## Installation
+
+npm install `@percy/cli`:
+
+```sh-session
+$ npm install --save-dev @percy/cli
+```
+
+gem install Percy appium package:
+
+```ssh-session
+$ gem install percy-appium-app
+```
+
+
+## Usage
+
+This is an example test using the `percy_screenshot` function.
+
+``` ruby
+require 'appium_lib'
+require 'percy-appium-app'
+
+username = '<BROWSERSTACK_USERNAME>'
+access_key = '<ACCESS_KEY>'
+
+capabilities = {
+  'platformName' => 'android',
+  'platformVersion' => '13.0',
+  'deviceName' => 'Google Pixel 7',
+  'bstack:options' => {
+    'appiumVersion' => '2.0.1'
+  },
+  'app' => '<APP LINK>',
+  'appium:percyOptions' => {
+    # enabled is default True. This can be used to disable visual testing for certain capabilities
+    'enabled' => true
+  }
+}
+
+appium_driver = Appium::Driver.new(
+  {
+    'caps' => capabilities,
+    'appium_lib' => {
+      server_url: "https://#{username}:#{access_key}@hub-cloud.browserstack.com/wd/hub"
+    }
+  }, true
+)
+driver = appium_driver.start_driver
+
+# take a screenshot
+percy_screenshot(driver, 'here is some name')
+```
+
+Running the test above normally will result in the following log:
+
+```sh-session
+[percy] Percy is not running, disabling screenshots
+```
+
+When running with [`percy
+app:exec`](https://github.com/percy/cli/tree/master/packages/cli-exec#app-exec), and your project's
+`PERCY_TOKEN`, a new Percy build will be created and screenshots will be uploaded to your project.
+
+```sh-session
+$ export PERCY_TOKEN=[your-project-token]
+$ percy app:exec -- [ruby test command]
+[percy] Percy has started!
+[percy] Created build #1: https://percy.io/[your-project]
+[percy] Screenshot taken "Ruby example"
+[percy] Stopping percy...
+[percy] Finalized build #1: https://percy.io/[your-project]
+[percy] Done!
+```
+
+## Configuration
+
+`percy_screenshot(driver, name[, **kwargs])`
+
+- `driver` (**required**) - A appium driver instance
+- `name` (**required**) - The screenshot name; must be unique to each screenshot
+- `device_name` (**optional**) - The device name used for capturing screenshot
+- `orientation` (**optional**) - Orientation of device while capturing screeenshot; Allowed values [`portrait` | `landscape`]
+- `status_bar_height` (**optional**) - Height of status bar; int
+- `nav_bar_height` (**optional**) - Height of navigation bar; int
+- `fullpage` (**optional**) - [Alpha] Only supported on App Automate driver sessions [ needs @percy/cli 1.20.2+ ]; boolean
+  - `screen_lengths` (**optional**) - [Alpha] Max screen lengths for fullPage; int
+  - In case scrollview is overlapping with other app elements. Offsets can be provided to reduce the area which needs to be considered for scrolling:
+    - `top_scrollview_offset`: (**optional**) - [Alpha] Offset from top of scrollview; int
+    - `bottom_scrollview_offset` (**optional**) - [Alpha] Offset from bottom of scrollview; int
+- `full_screen` (**optional**) - Indicate whether app is full screen; boolean [ needs @percy/cli 1.20.2+ ];
+- `sync` (**optional**) - Waits for screenshot to be processed and gives the processed result of screenshot [needs @percy/cli v1.28.0-beta.0+]; boolean
+- `scrollable_xpath` (**optional**) - [Alpha] Scrollable element xpath for fullpage [ needs @percy/cli 1.20.2+ ]; string
+- `scrollable_id` (**optional**) - [Alpha] Scrollable element accessibility id for fullpage [ needs @percy/cli 1.20.2+ ]; string
+- `ignore_regions_xpaths` (**optional**) - Elements xpaths that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ]; list of string
+- `ignore_region_accessibility_ids` (**optional**) - Elements accessibility_ids that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ]; list of string
+- `ignore_region_appium_elements` (**optional**) - Appium elements that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ]; list of appium element object
+- `custom_ignore_regions` (**optional**) - Custom locations that user want to ignore in visual diff [ needs @percy/cli 1.23.0+ ]; list of ignore_region object
+  - IgnoreRegion:-
+    - Description: This class represents a rectangular area on a screen that needs to be ignored for visual diff.
+    - Constructor:
+      ```
+      init(self, top, bottom, left, right)
+      ```
+    - Parameters:
+      - `top` (int): Top coordinate of the ignore region.
+      - `bottom` (int): Bottom coordinate of the ignore region.
+      - `left` (int): Left coordinate of the ignore region.
+      - `right` (int): Right coordinate of the ignore region.
+
+## Running with Hybrid Apps
+
+For a hybrid app, we need to switch to native context before taking screenshot.
+
+- Add a helper method similar to following for say flutter based hybrid app:
+```ruby
+def percy_screenshot_flutter(driver, name: str, **kwargs):
+  driver.switch_to.context('NATIVE_APP')
+  percy_screenshot(driver, name, **kwargs)
+  driver.switch_to.context('FLUTTER')
+end
+```
+
+- Call PercyScreenshotFlutter helper function when you want to take screenshot.
+```ruby
+percy_screenshot_flutter(driver, name, **kwargs)
+```
+
+> Note: 
+>
+> For other hybrid apps the `driver.switch_to.context('FLUTTER')` would change to context that it uses like say WEBVIEW etc.
+>
+
+## Running Percy on Automate
+`percy_screenshot(driver, name, options)` [ needs @percy/cli 1.27.0-beta.0+ ];
+- `driver` (**required**) - A appium driver instance
+- `name` (**required**) - The screenshot name; must be unique to each screenshot
+- `options` (**optional**) - There are various options supported by percy_screenshot to server further functionality.
+    - `sync` - Boolean value by default it falls back to `false`, Gives the processed result around screenshot [From CLI v1.28.0-beta.0+].
+    - `freeze_animated_image` - Boolean value by default it falls back to `false`, you can pass `true` and percy will freeze image based animations.
+    - `freeze_image_by_selectors` -List of selectors. Images will be freezed which are passed using selectors. For this to work `freeze_animated_image` must be set to true.
+    - `freeze_image_by_xpaths` - List of xpaths. Images will be freezed which are passed using xpaths. For this to work `freeze_animated_image` must be set to true.
+    - `percy_css` - Custom CSS to be added to DOM before the screenshot being taken. Note: This gets removed once the screenshot is taken.
+    - `ignore_region_xpaths` - List of xpaths. elements in the DOM can be ignored using xpath
+    - `ignore_region_selectors` - List of selectors. elements in the DOM can be ignored using selectors.
+    - `ignore_region_appium_elements` - List of appium web-element. elements can be ignored using appium_elements.
+    - `custom_ignore_regions` -  List of custom objects. elements can be ignored using custom boundaries. Just passing a simple object for it like below.
+      - example: ```{"top": 10, "right": 10, "bottom": 120, "left": 10}```
+      - In above example it will draw rectangle of ignore region as per given coordinates.
+          - `top` (int): Top coordinate of the ignore region.
+          - `bottom` (int): Bottom coordinate of the ignore region.
+          - `left` (int): Left coordinate of the ignore region.
+          - `right` (int): Right coordinate of the ignore region.
+    - `consider_region_xpaths` - List of xpaths. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using xpaths.
+    - `consider_region_selectors` - List of selectors. elements in the DOM can be considered for diffing and will be ignored by Intelli Ignore using selectors.
+    - `consider_region_appium_elements` - List of appium web-element. elements can be considered for diffing and will be ignored by Intelli Ignore using appium_elements.
+    - `custom_consider_regions` - List of custom objects. elements can be considered for diffing and will be ignored by Intelli Ignore using custom boundaries
+      - example:```{"top": 10, "right": 10, "bottom": 120, "left": 10}```
+      - In above example it will draw rectangle of consider region will be drawn.
+      - Parameters:
+        - `top` (int): Top coordinate of the consider region.
+        - `bottom` (int): Bottom coordinate of the consider region.
+        - `left` (int): Left coordinate of the consider region.
+        - `right` (int): Right coordinate of the consider region.
+
+### Creating Percy on automate build
+Note: Automate Percy Token starts with `auto` keyword. The command can be triggered using `exec` keyword.
+
+```sh-session
+$ export PERCY_TOKEN=[your-project-token]
+$ percy exec -- [ruby test command]
+[percy] Percy has started!
+[percy] [Ruby example] : Starting automate screenshot ...
+[percy] Screenshot taken "Ruby example"
+[percy] Stopping percy...
+[percy] Finalized build #1: https://percy.io/[your-project]
+[percy] Done!
+```
+
+Refer to docs here: [Percy on Automate](https://docs.percy.io/docs/integrate-functional-testing-with-visual-testing)
+
+### Migrating Config
+
+If you have a previous Percy configuration file, migrate it to the newest version with the
+[`config:migrate`](https://github.com/percy/cli/tree/master/packages/cli-config#percy-configmigrate-filepath-output) command:
+
+```sh-session
+$ percy config:migrate
+```

data/percy/environment.rb

@@ -4,22 +4,24 @@ require 'appium_lib'
 require 'appium_lib/version'
 require_relative 'version'
 
-class Environment
-  @percy_build_id = nil
-  @percy_build_url = nil
-  @session_type = nil
+module Percy
+  class Percy::Environment
+    @percy_build_id = nil
+    @percy_build_url = nil
+    @session_type = nil
 
-  class << self
-    attr_accessor :percy_build_id, :percy_build_url, :session_type
+    class << self
+      attr_accessor :percy_build_id, :percy_build_url, :session_type
 
-    def get_client_info(flag = false)
-      sdk_version = SDK_VERSION
-      flag ? "percy-appium-app-ruby/#{sdk_version}" : "percy-appium-app/#{sdk_version}"
-    end
+      def get_client_info(flag = false)
+        sdk_version = Percy::VERSION
+        flag ? "percy-appium-app-ruby/#{sdk_version}" : "percy-appium-app/#{sdk_version}"
+      end
 
-    def get_env_info
-      appium_version = Appium::VERSION # This assumes the 'appium_lib' gem provides a VERSION constant.
-      ["appium/#{appium_version}", "ruby/#{RUBY_VERSION}"]
+      def get_env_info
+        appium_version = Appium::VERSION # This assumes the 'appium_lib' gem provides a VERSION constant.
+        ["appium/#{appium_version}", "ruby/#{RUBY_VERSION}"]
+      end
     end
   end
 end

data/percy/exceptions/exceptions.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 class BaseException < StandardError; end
 
 class UnsupportedDevice < BaseException; end

data/percy/lib/app_percy.rb

@@ -6,50 +6,51 @@ require_relative 'percy_options'
 require_relative '../providers/provider_resolver'
 require_relative '../metadata/metadata_resolver'
 
-class AppPercy
-  attr_accessor :metadata, :provider
+module Percy
+  class AppPercy
+    attr_accessor :metadata, :provider
 
-  def initialize(driver)
-    raise DriverNotSupported unless driver.is_a?(Appium::Core::Base::Driver)
+    def initialize(driver)
+      raise DriverNotSupported unless driver.is_a?(Appium::Core::Base::Driver)
 
-    @driver = driver
-    @metadata = MetadataResolver.resolve(@driver)
-    @provider = ProviderResolver.resolve(@driver)
-    @percy_options = PercyOptions.new(@metadata.capabilities)
-  end
+      @driver = driver
+      @metadata = Percy::MetadataResolver.resolve(@driver)
+      @provider = Percy::ProviderResolver.resolve(@driver)
+      @percy_options = Percy::PercyOptions.new(@metadata.capabilities)
+    end
 
-  def screenshot(name, **kwargs)
-    return nil unless @percy_options.enabled
+    def screenshot(name, **kwargs)
+      return nil unless @percy_options.enabled
 
-    raise TypeError, 'Argument name should be a String' unless name.is_a?(String)
+      raise TypeError, 'Argument name should be a String' unless name.is_a?(String)
 
-    device_name = kwargs[:device_name]
-    raise TypeError, 'Argument device_name should be a String' if device_name && !device_name.is_a?(String)
+      device_name = kwargs[:device_name]
+      raise TypeError, 'Argument device_name should be a String' if device_name && !device_name.is_a?(String)
 
-    fullscreen = kwargs[:full_screen]
-    if fullscreen && !fullscreen.is_a?(TrueClass) && !fullscreen.is_a?(FalseClass)
-      raise TypeError,
-            'Argument fullscreen should be a Boolean'
-    end
+      fullscreen = kwargs[:full_screen]
+      if fullscreen && !fullscreen.is_a?(TrueClass) && !fullscreen.is_a?(FalseClass)
+        raise TypeError,
+              'Argument fullscreen should be a Boolean'
+      end
 
-    status_bar_height = kwargs[:status_bar_height]
-    if status_bar_height && !status_bar_height.is_a?(Integer)
-      raise TypeError,
-            'Argument status_bar_height should be an Integer'
-    end
+      status_bar_height = kwargs[:status_bar_height]
+      if status_bar_height && !status_bar_height.is_a?(Integer)
+        raise TypeError,
+              'Argument status_bar_height should be an Integer'
+      end
+
+      nav_bar_height = kwargs[:nav_bar_height]
+      raise TypeError, 'Argument nav_bar_height should be an Integer' if nav_bar_height && !nav_bar_height.is_a?(Integer)
 
-    nav_bar_height = kwargs[:nav_bar_height]
-    raise TypeError, 'Argument nav_bar_height should be an Integer' if nav_bar_height && !nav_bar_height.is_a?(Integer)
+      orientation = kwargs[:orientation]
+      if orientation && !orientation.is_a?(String)
+        raise TypeError,
+              'Argument orientation should be a String and portrait/landscape'
+      end
 
-    orientation = kwargs[:orientation]
-    if orientation && !orientation.is_a?(String)
-      raise TypeError,
-            'Argument orientation should be a String and portrait/landscape'
+      @provider.screenshot(name, **kwargs)
     end
 
-    @provider.screenshot(name, **kwargs)
-    nil
+    attr_reader :percy_options
   end
-
-  attr_reader :percy_options
 end

data/percy/lib/cache.rb

@@ -1,53 +1,54 @@
 # frozen_string_literal: true
+module Percy
+  class Cache
+    attr_reader :cache
+
+    @@cache = {}
+    CACHE_TIMEOUT = 5 * 60 # 5 * 60 seconds
+    TIMEOUT_KEY = 'last_access_time'
+
+    SESSION_DETAILS = 'session_details'
+    SYSTEM_BARS = 'system_bars'
+    WINDOW_SIZE = 'window_size'
+    VIEWPORT = 'viewport'
+    SESSION_CAPABILITIES = 'session_capabilities'
+    CAPABILITIES = 'capabilities'
+    COMMAND_EXECUTOR_URL = 'command_executor_url'
+
+    def cache
+      @@cache
+    end
 
-class Cache
-  attr_reader :cache
-
-  @@cache = {}
-  CACHE_TIMEOUT = 5 * 60 # 5 * 60 seconds
-  TIMEOUT_KEY = 'last_access_time'
-
-  SESSION_DETAILS = 'session_details'
-  SYSTEM_BARS = 'system_bars'
-  WINDOW_SIZE = 'window_size'
-  VIEWPORT = 'viewport'
-  SESSION_CAPABILITIES = 'session_capabilities'
-  CAPABILITIES = 'capabilities'
-  COMMAND_EXECUTOR_URL = 'command_executor_url'
-
-  def cache
-    @@cache
-  end
+    def self.set_cache(session_id, property, value)
+      raise TypeError, 'Argument session_id should be a String' unless session_id.is_a?(String)
+      raise TypeError, 'Argument property should be a String' unless property.is_a?(String)
 
-  def self.set_cache(session_id, property, value)
-    raise TypeError, 'Argument session_id should be a String' unless session_id.is_a?(String)
-    raise TypeError, 'Argument property should be a String' unless property.is_a?(String)
+      session = @@cache.fetch(session_id, {})
+      session[TIMEOUT_KEY] = Time.now.to_i
+      session[property] = value
+      @@cache[session_id] = session
+    end
 
-    session = @@cache.fetch(session_id, {})
-    session[TIMEOUT_KEY] = Time.now.to_i
-    session[property] = value
-    @@cache[session_id] = session
-  end
+    def self.get_cache(session_id, property)
+      cleanup_cache
 
-  def self.get_cache(session_id, property)
-    cleanup_cache
+      raise TypeError, 'Argument session_id should be a String' unless session_id.is_a?(String)
+      raise TypeError, 'Argument property should be a String' unless property.is_a?(String)
 
-    raise TypeError, 'Argument session_id should be a String' unless session_id.is_a?(String)
-    raise TypeError, 'Argument property should be a String' unless property.is_a?(String)
+      session = @@cache.fetch(session_id, {})
+      session.fetch(property, nil)
+    end
 
-    session = @@cache.fetch(session_id, {})
-    session.fetch(property, nil)
-  end
+    def self.cleanup_cache
+      now = Time.now.to_i
+      session_ids = []
 
-  def self.cleanup_cache
-    now = Time.now.to_i
-    session_ids = []
+      @@cache.each do |session_id, session|
+        timestamp = session[TIMEOUT_KEY]
+        session_ids << session_id if now - timestamp >= CACHE_TIMEOUT
+      end
 
-    @@cache.each do |session_id, session|
-      timestamp = session[TIMEOUT_KEY]
-      session_ids << session_id if now - timestamp >= CACHE_TIMEOUT
+      session_ids.each { |session_id| @@cache.delete(session_id) }
     end
-
-    session_ids.each { |session_id| @@cache.delete(session_id) }
   end
 end