percy-appium-app 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 977a7a790f27d4907f95f7fe43de80d9b22e755320f159a491615a642a836a1d
-  data.tar.gz: e9eb127a4f084f12bffc64aa4263928bf0931352a5ff60d408f91f9e955b0204
+  metadata.gz: a7a335595865863cc2116b953c51d39b8665116c6f05589273f3211e4bf5fef8
+  data.tar.gz: 468688dfe18390bb7068e8fa479e5e9a7ff7b739ef5759e2ddc1a5641c9a59c1
 SHA512:
-  metadata.gz: e50bd2ad6f3fda122ef560e6e264bb2eb1bde38d48d6fcef7a3a53193d1af021d19bd60e04c8785e29cbeb0b5db4372b86ef43779d4716fb6c1006e60c5ab1ed
-  data.tar.gz: 1ce875348fe37874f4fa9d2089a7a9159aedd0977b7f9e5aa1c3042218b0778b098becdcc0fcd5aeb3767c3f0284276dbe170221d7b2beef797fe39a9ed32863
+  metadata.gz: b9beee657ec15a65ee967f60295dac3d5caebc8f6355c5ee1f026dc2faba2056a7ccade079a88f0d81c51d3efeada4b178ac249415cb5fb7ee26f38c05dc2995
+  data.tar.gz: 3ba4e693b137e7d84109408d22b7ff6372f888a6b30ef4295a9a61974d8f674d746e8989209c4c7eb887a524b866a0be0810fb10ebf120f430ac10ffecb256d3

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/lib/app_percy.rb

@@ -49,7 +49,6 @@ module Percy
       end
 
       @provider.screenshot(name, **kwargs)
-      nil
     end
 
     attr_reader :percy_options

data/percy/lib/cli_wrapper.rb

@@ -49,13 +49,14 @@ module Percy
     end
 
     def post_screenshots(name, tag, tiles, external_debug_url = nil, ignored_elements_data = nil,
-                        considered_elements_data = nil)
-      body = request_body(name, tag, tiles, external_debug_url, ignored_elements_data, considered_elements_data)
+                        considered_elements_data = nil, sync = nil)
+      body = request_body(name, tag, tiles, external_debug_url, ignored_elements_data, considered_elements_data, sync)
       body['client_info'] = Percy::Environment.get_client_info
       body['environment_info'] = Percy::Environment.get_env_info
 
       uri = URI("#{PERCY_CLI_API}/percy/comparison")
       http = Net::HTTP.new(uri.host, uri.port)
+      http.read_timeout = 600 # seconds
       request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
       request.body = body.to_json
 
@@ -104,7 +105,11 @@ module Percy
       body['environment_info'] = Percy::Environment.get_env_info
 
       uri = URI("#{PERCY_CLI_API}/percy/automateScreenshot")
-      response = Net::HTTP.post(uri, body.to_json, 'Content-Type' => 'application/json')
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.read_timeout = 600 # seconds
+      request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
+      request.body = body.to_json
+      response = http.request(request)
 
       # Handle errors
       raise CLIException, "Error: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
@@ -119,7 +124,7 @@ module Percy
       data
     end
 
-    def request_body(name, tag, tiles, external_debug_url, ignored_elements_data, considered_elements_data)
+    def request_body(name, tag, tiles, external_debug_url, ignored_elements_data, considered_elements_data, sync)
       tiles = tiles.map(&:to_h)
       {
         'name' => name,
@@ -127,7 +132,8 @@ module Percy
         'tiles' => tiles,
         'ignored_elements_data' => ignored_elements_data,
         'external_debug_url' => external_debug_url,
-        'considered_elements_data' => considered_elements_data
+        'considered_elements_data' => considered_elements_data,
+        'sync' => sync
       }
     end
   end

data/percy/lib/percy_automate.rb

@@ -43,7 +43,7 @@ module Percy
           'consider_region_elements' => consider_region_elements
         }
 
-        Percy::CLIWrapper.new.post_poa_screenshots(
+        response = Percy::CLIWrapper.new.post_poa_screenshots(
           name,
           metadata.session_id,
           metadata.command_executor_url,
@@ -51,11 +51,12 @@ module Percy
           metadata.session_capabilities,
           options.merge(additional_options)
         )
+
+        response['data']
       rescue StandardError => e
         log("Could not take Screenshot '#{name}'")
         log(e.message, on_debug: true)
       end
-      nil
     end
   end
 end

data/percy/providers/app_automate.rb

@@ -29,9 +29,10 @@ module Percy
       begin
         response = super(name, **kwargs)
         percy_screenshot_url = response.fetch('link', '')
-        execute_percy_screenshot_end(name, percy_screenshot_url, 'success')
+        execute_percy_screenshot_end(name, percy_screenshot_url, 'success', kwargs.fetch('sync', nil))
+        response['data']
       rescue StandardError => e
-        execute_percy_screenshot_end(name, percy_screenshot_url, 'failure', e.message)
+        execute_percy_screenshot_end(name, percy_screenshot_url, 'failure', kwargs.fetch('sync', nil), e.message)
         raise e
       end
     end
@@ -104,14 +105,15 @@ module Percy
       end
     end
 
-    def execute_percy_screenshot_end(name, percy_screenshot_url, status, status_message = nil)
+    def execute_percy_screenshot_end(name, percy_screenshot_url, status, sync = nil, status_message = nil)
       request_body = {
         action: 'percyScreenshot',
         arguments: {
           state: 'end',
           percyScreenshotUrl: percy_screenshot_url,
           name: name,
-          status: status
+          status: status,
+          sync: sync
         }
       }
       request_body[:arguments][:statusMessage] = status_message if status_message
@@ -158,4 +160,4 @@ module Percy
       end
     end
   end
-end
+end

data/percy/providers/generic_provider.rb

@@ -42,8 +42,9 @@ module Percy
           custom_locations: kwargs.fetch(:custom_consider_regions, [])
         )
       }
+      sync = kwargs.fetch(:sync, nil)
 
-      _post_screenshots(name, tag, tiles, get_debug_url, ignore_regions, consider_regions)
+      _post_screenshots(name, tag, tiles, get_debug_url, ignore_regions, consider_regions, sync)
     end
 
     def _get_tag(**kwargs)
@@ -93,8 +94,8 @@ module Percy
       elements_array
     end
 
-    def _post_screenshots(name, tag, tiles, debug_url, ignored_regions, considered_regions)
-      Percy::CLIWrapper.new.post_screenshots(name, tag, tiles, debug_url, ignored_regions, considered_regions)
+    def _post_screenshots(name, tag, tiles, debug_url, ignored_regions, considered_regions, sync)
+      Percy::CLIWrapper.new.post_screenshots(name, tag, tiles, debug_url, ignored_regions, considered_regions, sync)
     end
 
     def _write_screenshot(png_bytes, directory)

data/percy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Percy
-  VERSION = '0.0.2'.freeze
+  VERSION = '0.0.4'.freeze
 end

data/specs/screenshot.rb

@@ -6,7 +6,7 @@ require 'webmock/minitest'
 require 'appium_lib'
 require 'webrick'
 
-require_relative '../percy/screenshot'
+require_relative '../percy/percy-appium-app'
 require_relative '../percy/lib/app_percy'
 require_relative 'mocks/mock_methods'
 
@@ -54,14 +54,14 @@ def mock_healthcheck(fail: false, fail_how: 'error', type: 'Percy::AppPercy')
     .to_return(status: health_status, body: health_body, headers: health_headers)
 end
 
-def mock_screenshot(fail: false)
+def mock_screenshot(fail: false, data: false)
   stub_request(:post, 'http://localhost:5338/percy/comparison')
-    .to_return(body: "{\"success\": #{fail ? 'false, "error": "test"' : 'true'}}", status: (fail ? 500 : 200))
+    .to_return(body: "{\"success\": #{fail ? 'false, "error": "test"' : 'true'} #{data ? ',"data": "sync-data"' : ""}}", status: (fail ? 500 : 200))
 end
 
-def mock_poa_screenshot(fail: false)
+def mock_poa_screenshot(fail: false, data: false)
   stub_request(:post, 'http://localhost:5338/percy/automateScreenshot')
-    .to_return(body: "{\"success\": #{fail ? 'false, "error": "test"' : 'true'}}", status: (fail ? 500 : 200))
+    .to_return(body: "{\"success\": #{fail ? 'false, "error": "test"' : 'true'} #{data ? ',"data": "sync-data"' : ""}}", status: (fail ? 500 : 200))
 end
 
 def mock_session_request
@@ -204,6 +204,37 @@ class TestPercyScreenshot < Minitest::Test
     assert_equal(['Consider_Dummy_id'], s2['options']['consider_region_elements'])
   end
 
+  def test_posts_screenshot_poa_with_sync
+    mock_healthcheck(type: 'automate')
+    mock_poa_screenshot(data: true)
+    mock_session_request
+
+    driver = Minitest::Mock.new
+    @bridge = Minitest::Mock.new
+    @http = Minitest::Mock.new
+    @server_url = Minitest::Mock.new
+
+    driver.expect(:is_a?, true, [Appium::Core::Base::Driver])
+    driver.expect(:desired_capabilities, { 'key' => 'value' })
+    driver.expect(:instance_variable_get, @bridge, [:@bridge])
+    @http.expect(:instance_variable_get, @server_url, [:@server_url])
+    @bridge.expect(:instance_variable_get, @http, [:@http])
+    @server_url.expect(:to_s, 'https://hub-cloud.browserstack.com/wd/hub')
+
+    10.times do
+      driver.expect(:session_id, 'Dummy_session_id')
+    end
+    2.times do
+      driver.expect(:capabilities, { 'key' => 'value' })
+    end
+    @mock_webdriver.expect(:capabilities, { 'key' => 'value' })
+
+    res = percy_screenshot(driver, 'Snapshot 1', options: { sync: true })
+
+    assert_equal('sync-data', res)
+    assert_equal('/percy/automateScreenshot', @requests.last.uri.path)
+  end
+
   def test_posts_multiple_screenshots_to_the_local_percy_server
     mock_healthcheck
     mock_screenshot
@@ -256,6 +287,53 @@ class TestPercyScreenshot < Minitest::Test
     assert_match(%r{ruby/\d+\.\d+\.\d+}, body['environment_info'][1])
   end
 
+  def test_post_screenshot_with_sync
+    mock_healthcheck
+    mock_screenshot(data: true)
+
+    driver = Minitest::Mock.new
+
+    driver.expect(:is_a?, true, [Appium::Core::Base::Driver])
+    driver.expect(:instance_variable_get, @bridge, [:@bridge])
+    @http.expect(:instance_variable_get, @server_url, [:@server_url])
+    @bridge.expect(:instance_variable_get, @http, [:@http])
+    @server_url.expect(:to_s, 'https://hub-cloud.browserstack.com/wd/hub')
+
+    5.times do
+      driver.expect(:session_id, 'Dummy_session_id')
+    end
+
+    13.times do
+      driver.expect(:capabilities, get_android_capabilities)
+    end
+
+    3.times do
+      driver.expect(
+        :execute_script,
+        '{"success":true,"result":"[{\"sha\":\"sha-something\",\"status_bar\":null'\
+        ',\"nav_bar\":null,\"header_height\":0,\"footer_height\":0,\"index\":0}]"}',
+        [String]
+      )
+    end
+
+    2.times do
+      driver.expect(:get_system_bars, {
+                      'statusBar' => { 'height' => 10, 'width' => 20 },
+                      'navigationBar' => { 'height' => 10, 'width' => 20 }
+                    })
+    end
+
+    res = percy_screenshot(driver, 'screenshot 2', sync: true)
+
+    assert_equal('sync-data', res)
+    assert_equal('/percy/comparison', @requests.last.uri.path)
+
+    body = JSON.parse(@requests[-1].body)
+    assert_match(%r{percy-appium-app/\d+}, body['client_info'])
+    assert_match(%r{appium/\d+}, body['environment_info'][0])
+    assert_match(%r{ruby/\d+\.\d+\.\d+}, body['environment_info'][1])
+  end
+
   def test_ignore_region_screenshots_to_the_local_percy_server
     mock_healthcheck
     mock_screenshot

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: percy-appium-app
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - BroswerStack
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-01 00:00:00.000000000 Z
+date: 2024-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appium_lib
@@ -201,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Percy visual testing for Ruby Appium Mobile Apps