adding regions support for sdk (#156)

* added regions

* verson fix

* testing

* testing

* updated cli

* updated readme

* readme

* updated ubantu

* added for python

* lint

Author: amandeepsingh333

.github/workflows/test.yml

@@ -13,8 +13,8 @@ jobs:
     name: Test
     strategy:
       matrix:
-        python: [3.6, 3.7, 3.8, 3.9]
-    runs-on: ${{ matrix.python == 3.6 && 'ubuntu-20.04' || 'ubuntu-latest' }}
+        python: ["3.8", "3.9", "3.10"]
+    runs-on: ubuntu-latest
 
     steps:
       - uses: actions-ecosystem/action-regex-match@v2

README.md

@@ -116,6 +116,68 @@ percy_screenshot(driver, name = 'Screenshot 1')
         - `bottom` (int): Bottom coordinate of the consider region.
         - `left` (int): Left coordinate of the consider region.
         - `right` (int): Right coordinate of the consider region.
+    - `regions` parameter that allows users to apply snapshot options to specific areas of the page. This parameter is an array where each object defines a custom region with configurations.
+      - Parameters:
+        - `elementSelector` (optional, only one of the following must be provided, if this is not provided then full page will be considered as region)
+            - `boundingBox` (object): Defines the coordinates and size of the region.
+              - `x` (number): X-coordinate of the region.
+              - `y` (number): Y-coordinate of the region.
+              - `width` (number): Width of the region.
+              - `height` (number): Height of the region.
+            - `elementXpath` (string): The XPath selector for the element.
+            - `elementCSS` (string): The CSS selector for the element.
+
+        - `algorithm` (mandatory)
+            - Specifies the snapshot comparison algorithm.
+            - Allowed values: `standard`, `layout`, `ignore`, `intelliignore`.
+
+        - `configuration` (required for `standard` and `intelliignore` algorithms, ignored otherwise)
+            - `diffSensitivity` (number): Sensitivity level for detecting differences.
+            - `imageIgnoreThreshold` (number): Threshold for ignoring minor image differences.
+            - `carouselsEnabled` (boolean): Whether to enable carousel detection.
+            - `bannersEnabled` (boolean): Whether to enable banner detection.
+            - `adsEnabled` (boolean): Whether to enable ad detection.
+
+         - `assertion` (optional)
+            - Defines assertions to apply to the region.
+            - `diffIgnoreThreshold` (number): The threshold for ignoring minor differences.
+
+### Example Usage for regions
+
+```
+obj1 = {
+  "elementSelector": {
+    "elementCSS": ".ad-banner" 
+  },
+  "algorithm": "intelliignore",
+  "configuration": {
+    "diffSensitivity": 2,
+    "imageIgnoreThreshold": 0.2,
+    "carouselsEnabled": true,
+    "bannersEnabled": true,
+    "adsEnabled": true
+  },
+  "assertion": {
+    "diffIgnoreThreshold": 0.4,
+  }
+};
+
+# we can use the createRegion function
+
+from percy import percy_snapshot
+from percy.snapshot import (create_region)
+
+obj2 = create_region(
+    algorithm="intellignore",
+    diffSensitivity=2,
+    imageIgnoreThreshold=0.2,
+    carouselsEnabled=True,
+    adsEnabled=True,
+    diffIgnoreThreshold=0.4
+)
+
+percy_snapshot(page, name="Homepage", regions=[obj1]);
+```
 
 
 ### Creating Percy on automate build

package.json

@@ -4,6 +4,6 @@
     "test": "make test"
   },
   "devDependencies": {
-    "@percy/cli": "1.27.0-beta.0"
+    "@percy/cli": "1.30.9"
   }
 }

percy/snapshot.py

@@ -79,6 +79,58 @@ def fetch_percy_dom():
     response.raise_for_status()
     return response.text
 
+# pylint: disable=too-many-arguments, too-many-branches, too-many-locals
+def create_region(
+    boundingBox=None,
+    elementXpath=None,
+    elementCSS=None,
+    padding=None,
+    algorithm="ignore",
+    diffSensitivity=None,
+    imageIgnoreThreshold=None,
+    carouselsEnabled=None,
+    bannersEnabled=None,
+    adsEnabled=None,
+    diffIgnoreThreshold=None
+    ):
+
+    element_selector = {}
+    if boundingBox:
+        element_selector["boundingBox"] = boundingBox
+    if elementXpath:
+        element_selector["elementXpath"] = elementXpath
+    if elementCSS:
+        element_selector["elementCSS"] = elementCSS
+
+    region = {
+        "algorithm": algorithm,
+        "elementSelector": element_selector
+    }
+
+    if padding:
+        region["padding"] = padding
+
+    if algorithm in ["standard", "intelliignore"]:
+        config_values = {
+            "diffSensitivity": diffSensitivity,
+            "imageIgnoreThreshold": imageIgnoreThreshold,
+            "carouselsEnabled": carouselsEnabled,
+            "bannersEnabled": bannersEnabled,
+            "adsEnabled": adsEnabled,
+        }
+        configuration = {k: v for k, v in config_values.items() if v is not None}
+        if configuration:
+            region["configuration"] = configuration
+
+    assertion = {}
+    if diffIgnoreThreshold is not None:
+        assertion["diffIgnoreThreshold"] = diffIgnoreThreshold
+
+    if assertion:
+        region["assertion"] = assertion
+
+    return region
+
 def get_serialized_dom(driver, cookies, **kwargs):
     dom_snapshot = driver.execute_script(f'return PercyDOM.serialize({json.dumps(kwargs)})')
     dom_snapshot['cookies'] = cookies

tests/test_snapshot.py

@@ -12,6 +12,7 @@
 from selenium.webdriver.remote.webelement import WebElement
 from selenium.webdriver.remote.remote_connection import RemoteConnection
 from selenium.webdriver.safari.remote_connection import SafariRemoteConnection
+from percy.snapshot import create_region
 
 from percy import percy_snapshot, percySnapshot, percy_screenshot
 import percy.snapshot as local
@@ -562,6 +563,120 @@ def test_posts_snapshots_to_the_local_percy_server(self):
         self.assertEqual(s2['name'], 'Snapshot 2')
         self.assertEqual(s2['enable_javascript'], True)
 
+class TestCreateRegion(unittest.TestCase):
+
+    def test_create_region_with_all_params(self):
+        result = create_region(
+            boundingBox={"x": 10, "y": 20, "width": 100, "height": 200},
+            elementXpath="//*[@id='test']",
+            elementCSS=".test-class",
+            padding=10,
+            algorithm="intelliignore",
+            diffSensitivity=0.8,
+            imageIgnoreThreshold=0.5,
+            carouselsEnabled=True,
+            bannersEnabled=False,
+            adsEnabled=True,
+            diffIgnoreThreshold=0.2
+        )
+
+        expected_result = {
+            "algorithm": "intelliignore",
+            "elementSelector": {
+                "boundingBox": {"x": 10, "y": 20, "width": 100, "height": 200},
+                "elementXpath": "//*[@id='test']",
+                "elementCSS": ".test-class"
+            },
+            "padding": 10,
+            "configuration": {
+                "diffSensitivity": 0.8,
+                "imageIgnoreThreshold": 0.5,
+                "carouselsEnabled": True,
+                "bannersEnabled": False,
+                "adsEnabled": True
+            },
+            "assertion": {
+                "diffIgnoreThreshold": 0.2
+            }
+        }
+
+        self.assertEqual(result, expected_result)
+
+    def test_create_region_with_minimal_params(self):
+        result = create_region(
+            algorithm="standard",
+            boundingBox={"x": 10, "y": 20, "width": 100, "height": 200}
+        )
+
+        expected_result = {
+            "algorithm": "standard",
+            "elementSelector": {
+                "boundingBox": {"x": 10, "y": 20, "width": 100, "height": 200}
+            }
+        }
+
+        self.assertEqual(result, expected_result)
+
+    def test_create_region_with_padding(self):
+        result = create_region(
+            algorithm="ignore",
+            padding=15
+        )
+
+        expected_result = {
+            "algorithm": "ignore",
+            "elementSelector": {},
+            "padding": 15
+        }
+
+        self.assertEqual(result, expected_result)
+
+    def test_create_region_with_configuration_only_for_valid_algorithms(self):
+        result = create_region(
+            algorithm="intelliignore",
+            diffSensitivity=0.9,
+            imageIgnoreThreshold=0.7
+        )
+
+        expected_result = {
+            "algorithm": "intelliignore",
+            "elementSelector": {},
+            "configuration": {
+                "diffSensitivity": 0.9,
+                "imageIgnoreThreshold": 0.7
+            }
+        }
+
+        self.assertEqual(result, expected_result)
+
+    def test_create_region_with_diffIgnoreThreshold_in_assertion(self):
+        result = create_region(
+            algorithm="standard",
+            diffIgnoreThreshold=0.3
+        )
+
+        expected_result = {
+            "algorithm": "standard",
+            "elementSelector": {},
+            "assertion": {
+                "diffIgnoreThreshold": 0.3
+            }
+        }
+
+        self.assertEqual(result, expected_result)
+
+    def test_create_region_with_invalid_algorithm(self):
+        result = create_region(
+            algorithm="invalid_algorithm"
+        )
+
+        expected_result = {
+            "algorithm": "invalid_algorithm",
+            "elementSelector": {}
+        }
+
+        self.assertEqual(result, expected_result)
+
 
 if __name__ == '__main__':
     unittest.main()