@applitools/eyes-cypress 3.25.7 → 3.26.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@
 
 
 
+
+## 3.26.0 - 2022/5/19
+
+### Features
+- `cy.eyesCheckWindow` now supports passing DOM elements and jQuery object for target and regions.
+### Bug fixes
+- Support `cy.eyesGetAllTestResults` in TypeScript
+
 ## 3.25.7 - 2022/5/6
 
 ### Features

package/README.md

@@ -255,7 +255,7 @@ cy.eyesCheckWindow({ tag: 'Login screen', target: 'your target' })
 <br/> 1. `window` 
   This is the default value. If set then the captured image is of the entire page or the viewport, use [`fully`](#fully) for specifying what `window` mode to use.
 <br/>2. `region` 
-  If set then the captured image is of the parts of the page, use this parameter with [`region`](#region) or [`selector`](#selector) for specifying the areas to captured.
+  If set then the captured image is of the parts of the page, use this parameter with [`region`](#region), [`selector`](#selector), or [`element`](#element) for specifying the areas to captured.
 
 ##### `fully`
 
@@ -310,18 +310,72 @@ cy.eyesCheckWindow({ tag: 'Login screen', target: 'your target' })
   });
   ```
 
+##### `element`
+
+(optional): In case [`target`](#target) is `region`, this should be an instance of either an HTML element or a jQuery object. For example:
+
+  ```js
+// passing a jQuery object
+cy.get('body > div > h1')
+  .then($el => {
+      cy.eyesCheckWindow({
+        target: 'region',
+        element: $el
+      })
+  })
+
+// passing an HTML element
+cy.document()
+  .then(doc => {
+    const el = document.querySelector('div')
+    cy.eyesCheckWindow({
+      target: 'region',
+      element: el
+    })
+  })
+```
+
 ##### `ignore`
 
 (optional): A single or an array of regions to ignore when checking for visual differences. For example:
 
-  ```js
+```js
+// ignore region by coordinates
+cy.eyesCheckWindow({
+  ignore: {top: 100, left: 0, width: 1000, height: 100},
+});
+
+// ignore regions by selector
+cy.eyesCheckWindow({
+  ignore: {selector: '.some-div-to-ignore'} // all elements matching this selector would become ignore regions
+});
+
+// ignore regions by jQuery or DOM elements
+cy.get('.some-div-to-ignore').then($el => {
+  cy.eyesCheckWindow({
+    ignore: $el
+  });
+})
+
+// mix multiple ignore regions with different methods
+cy.eyesCheckWindow({
+  ignore: [
+    {top: 100, left: 0, width: 1000, height: 100},
+    {selector: '.some-div-to-ignore'}
+  ]
+});
+
+// mix multiple ignore regions with different methods including element
+cy.get('.some-div-to-ignore').then($el => {
   cy.eyesCheckWindow({
     ignore: [
       {top: 100, left: 0, width: 1000, height: 100},
       {selector: '.some-div-to-ignore'}
+      $el
     ]
   });
-  ```
+})
+```
 
 ##### `floating`
 
@@ -334,6 +388,15 @@ cy.eyesCheckWindow({
     {selector: '.some-div-to-float', maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20}
   ]
 });
+
+// use jQuery or DOM elements
+cy.get('.some-div-to-float').then($el => {
+  cy.eyesCheckWindow({
+    floating: [
+        {element: $el, maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20},
+    ]
+  })
+})
 ```
 
 ##### `layout`
@@ -347,6 +410,13 @@ cy.eyesCheckWindow({
       {selector: '.some-div-to-test-as-layout'}
     ]
   });
+
+    // use jQuery or DOM elements
+  cy.get('.some-div-to-test-as-layout').then($el => {
+      cy.eyesCheckWindow({
+        layout: $el
+    });
+  })
   ```
 
 ##### `strict`
@@ -360,6 +430,13 @@ cy.eyesCheckWindow({
       {selector: '.some-div-to-test-as-strict'}
     ]
   });
+
+  // use jQuery or DOM elements
+  cy.get('.some-div-to-test-as-strict').then($el => {
+      cy.eyesCheckWindow({
+        strict: $el
+    });
+  })
   ```
 
 ##### `content`
@@ -373,6 +450,13 @@ cy.eyesCheckWindow({
       {selector: '.some-div-to-test-as-content'}
     ]
   });
+
+  // use jQuery or DOM elements
+  cy.get('.some-div-to-test-as-content').then($el => {
+      cy.eyesCheckWindow({
+        content: $el
+    });
+  })
   ```
 
 ##### `accessibility`
@@ -387,6 +471,16 @@ cy.eyesCheckWindow({
       {accessibilityType: 'BoldText', top: 100, left: 0, width: 1000, height: 100},
     ]
   });
+
+// use jQuery or DOM elements
+  cy.get('.some-div').then($el => {
+     cy.eyesCheckWindow({
+    accessibility: [
+      {accessibilityType: 'RegularText', element: $el},
+    ]
+  });
+  })
+
   ```
 
   Possible accessibilityType values are: `IgnoreContrast`,`RegularText`,`LargeText`,`BoldText` and `GraphicalObject`.

package/dist/plugin/handler.js

@@ -43,7 +43,7 @@ async function makeHandler({ port = 31077, singleton = true, lazy = false } = {}
 exports.makeHandler = makeHandler;
 async function isHandshakable(port) {
     return new Promise(resolve => {
-        const handshake = http_1.request(`http://localhost:${port}/handshake`, {
+        const handshake = (0, http_1.request)(`http://localhost:${port}/handshake`, {
             headers: { [TOKEN_HEADER]: TOKEN },
         });
         handshake.on('response', ({ statusCode, headers }) => {

package/eyes-index.d.ts

@@ -1,7 +1,9 @@
 /// <reference types="Cypress" />
 /// <reference types="@applitools/visual-grid-client" />
+import {TestResultsSummary} from '@applitools/eyes-api';
 
-declare namespace Cypress {
+declare global {
+  namespace Cypress {
     interface Chainable {
       /**
        * Create an Applitools test.
@@ -30,5 +32,17 @@ declare namespace Cypress {
        * @example cy.eyesClose()
       */
       eyesClose(): null
+
+      /**
+       * Returns an object with the applitools test results from a given test / test file. This should be called after close.
+       * @example
+       * after(() => {
+       *  cy.eyesGetAllTestResults().then(summary => {
+       *    console.log(summary)
+       *  })
+       * })
+       */
+      eyesGetAllTestResults(): Chainable<TestResultsSummary>
     }
   }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/eyes-cypress",
-  "version": "3.25.7",
+  "version": "3.26.0",
   "main": "index.js",
   "license": "SEE LICENSE IN LICENSE",
   "bin": {
@@ -12,8 +12,11 @@
     "test:unit": "mocha --no-timeouts 'test/unit/**/*.test.js'",
     "test:it": "mocha --no-timeouts 'test/it/**/*.test.js'",
     "test:e2e": "mkdir -p test/fixtures/testAppCopies && mocha --no-timeouts 'test/e2e/**/*.test.js'",
+    "test:ts:compile": "tsc --project test/e2e/ts/cypress",
+    "test:ts:run": "cypress run --config-file test/e2e/ts/cypress-ts.json",
+    "test:ts": "yarn test:ts:compile && yarn test:ts:run",
     "lint": "eslint \"**/*.js\"",
-    "test": "yarn test:unit && yarn test:it && yarn test:e2e && yarn test:coverage",
+    "test": "yarn test:unit && yarn test:it && yarn test:e2e && yarn test:ts && yarn test:coverage",
     "cypress": "cypress open --config-file test/fixtures/cypress-play.json",
     "cypress:new": "node_modules/cypress-new/bin/cypress open --config-file test/fixtures/cypress-play.json",
     "cypress:run": "cypress run --config-file test/fixtures/cypress-play.json --spec=test/fixtures/testApp/cypress/integration-play/play.js",
@@ -46,11 +49,11 @@
   },
   "dependencies": {
     "@applitools/dom-snapshot": "4.5.12",
-    "@applitools/eyes-api": "1.3.1",
-    "@applitools/eyes-universal": "2.5.1",
+    "@applitools/eyes-api": "1.4.1",
+    "@applitools/eyes-universal": "2.5.15",
     "@applitools/functional-commons": "1.6.0",
-    "@applitools/logger": "1.1.2",
-    "@applitools/visual-grid-client": "15.12.13",
+    "@applitools/logger": "1.1.5",
+    "@applitools/visual-grid-client": "15.12.28",
     "body-parser": "1.19.0",
     "chalk": "3.0.0",
     "cors": "2.8.5",
@@ -60,14 +63,14 @@
     "ws": "8.5.0"
   },
   "devDependencies": {
-    "@applitools/bongo": "^2.0.3",
+    "@applitools/bongo": "^2.1.0",
     "@applitools/scripts": "1.1.0",
     "@applitools/sdk-coverage-tests": "^2.3.18",
     "@applitools/snaptdout": "1.0.1",
     "@applitools/test-server": "1.0.8",
     "@applitools/test-utils": "1.3.2",
-    "@applitools/types": "^1.4.2",
-    "@applitools/utils": "1.2.14",
+    "@applitools/types": "^1.4.3",
+    "@applitools/utils": "1.3.0",
     "@types/node": "17.0.13",
     "@types/ws": "^8.2.2",
     "@typescript-eslint/eslint-plugin": "^5.10.2",
@@ -88,7 +91,7 @@
     "ncp": "2.0.0",
     "node-fetch": "2.6.0",
     "prettier": "1.19.1",
-    "typescript": "3.9.2"
+    "typescript": "4.6.4"
   },
   "husky": {
     "hooks": {

package/src/browser/commands.js

@@ -7,7 +7,6 @@ const {socketCommands} = require('./socketCommands');
 const {eyesOpenMapValues} = require('./eyesOpenMapping');
 const {eyesCheckMapValues} = require('./eyesCheckMapping');
 const {TestResultsSummary} = require('@applitools/eyes-api');
-
 const refer = new Refer(value => {
   if (!value || !value.constructor || !value.constructor.name) return false;
   const name = value.constructor.name;
@@ -148,7 +147,7 @@ Cypress.Commands.add('eyesOpen', function(args = {}) {
   });
 });
 
-Cypress.Commands.add('eyesCheckWindow', args =>
+Cypress.Commands.add('eyesCheckWindow', (args = {}) =>
   cy.then({timeout: 86400000}, () => {
     if (isCurrentTestDisabled) return;
 
@@ -156,7 +155,7 @@ Cypress.Commands.add('eyesCheckWindow', args =>
 
     Cypress.log({name: 'Eyes: check window'});
 
-    const checkSettings = eyesCheckMapValues({args});
+    const checkSettings = eyesCheckMapValues({args, refer});
 
     return socket.request('Eyes.check', {
       eyes,

package/src/browser/eyesCheckMapping.js

@@ -1,8 +1,6 @@
-function eyesCheckMapValues({args}) {
-  return toCheckWindowConfiguration(args);
-}
-
-function toCheckWindowConfiguration(config = {}) {
+/* global Node */
+function eyesCheckMapValues({args, refer}) {
+  const config = args; // just did it for having less git changes at this moment
   const mappedValues = [
     'tag',
     'scriptHooks',
@@ -21,17 +19,28 @@ function toCheckWindowConfiguration(config = {}) {
   const checkSettings = {
     name: config.tag,
     hooks: config.scriptHooks,
-    ignoreRegions: config.ignore,
+    ignoreRegions: refElements(config.ignore),
     floatingRegions: convertFloatingRegion(config.floating),
-    strictRegions: config.strict,
-    layoutRegions: config.layout,
-    contentRegions: config.content,
+    strictRegions: refElements(config.strict),
+    layoutRegions: refElements(config.layout),
+    contentRegions: refElements(config.content),
     accessibilityRegions: convertAccessabilityRegions(config.accessibility),
   };
 
   if (config.target === 'region') {
     if (!Array.isArray(config.selector)) {
-      if (!config.hasOwnProperty('selector')) {
+      if (config.element) {
+        if (isHTMLElement(config.element)) {
+          regionSettings = {
+            region: refer.ref(config.element),
+          };
+        } else {
+          // JQuery element
+          regionSettings = {
+            region: refer.ref(config.element[0]),
+          };
+        }
+      } else if (!config.hasOwnProperty('selector')) {
         regionSettings = {
           region: config.region,
         };
@@ -66,39 +75,97 @@ function toCheckWindowConfiguration(config = {}) {
   }
 
   return Object.assign({}, checkSettings, regionSettings, config);
-}
 
-function convertAccessabilityRegions(accessibilityRegions) {
-  if (!accessibilityRegions) return accessibilityRegions;
+  // #region helper functions
 
-  return accessibilityRegions.map(region => ({
-    region: region.selector,
-    type: region.accessibilityType,
-  }));
-}
+  function convertAccessabilityRegions(accessibilityRegions) {
+    if (!accessibilityRegions) return accessibilityRegions;
+    const accessibility = [];
+
+    accessibilityRegions.map(region => {
+      const accessabilityRegion = {
+        type: region.accessibilityType,
+      };
+      if (region.hasOwnProperty('selector')) {
+        accessabilityRegion.region = region.selector;
+        accessibility.push(accessabilityRegion);
+      } else if (region.hasOwnProperty('element')) {
+        const elements = refElements(region.element);
+        for (const element of elements) {
+          accessibility.push(Object.assign({}, accessabilityRegion, {region: element}));
+        }
+      } else {
+        accessabilityRegion.region = {
+          top: region.top,
+          left: region.left,
+          width: region.width,
+          height: region.height,
+        };
+        accessibility.push(accessabilityRegion);
+      }
+    });
 
-function convertFloatingRegion(floatingRegions) {
-  if (!floatingRegions) return floatingRegions;
+    return accessibility;
+  }
 
-  return floatingRegions.map(region => {
-    const floatingRegion = {
-      maxDownOffset: region.maxDownOffset || 0,
-      maxLeftOffset: region.maxLeftOffset || 0,
-      maxUpOffset: region.maxUpOffset || 0,
-      maxRightOffset: region.maxRightOffset || 0,
-    };
-    if (region.hasOwnProperty('selector')) {
-      floatingRegion.region = region.selector;
-    } else {
-      floatingRegion.region = {
-        top: region.top,
-        left: region.left,
-        width: region.width,
-        height: region.height,
+  function convertFloatingRegion(floatingRegions) {
+    if (!floatingRegions) return floatingRegions;
+    const floating = [];
+
+    for (const region of floatingRegions) {
+      const floatingRegion = {
+        maxDownOffset: region.maxDownOffset || 0,
+        maxLeftOffset: region.maxLeftOffset || 0,
+        maxUpOffset: region.maxUpOffset || 0,
+        maxRightOffset: region.maxRightOffset || 0,
       };
+      if (region.hasOwnProperty('selector')) {
+        floatingRegion.region = region.selector;
+        floating.push(floatingRegion);
+      } else if (region.hasOwnProperty('element')) {
+        const elements = refElements(region.element);
+        for (const element of elements) {
+          floating.push(Object.assign({}, floatingRegion, {region: element}));
+        }
+      } else {
+        floatingRegion.region = {
+          top: region.top,
+          left: region.left,
+          width: region.width,
+          height: region.height,
+        };
+        floating.push(floatingRegion);
+      }
+    }
+    return floating;
+  }
+
+  function refElements(regions) {
+    if (!regions) return regions;
+    if (!Array.isArray(regions)) regions = [regions];
+    const elements = [];
+    for (const region of regions) {
+      if (isHTMLElement(region)) {
+        elements.push(refer.ref(region));
+      } else if (region.jquery) {
+        region.each(function() {
+          // there's a small chance that `this` is not an HTML element. So we just verify it.
+          elements.push(isHTMLElement(this) ? refer.ref(this) : this);
+        });
+      } else {
+        elements.push(region);
+      }
     }
-    return floatingRegion;
-  });
+    return elements;
+  }
+
+  // #endregion
+}
+
+function isHTMLElement(element) {
+  // Avoiding instanceof here since the element might come from an iframe, and `instanceof HTMLElement` would fail.
+  // This check looks naive, but if anyone passes something like {nodeType: 1} as a region, then I'm fine with them crashing :)
+  return element.nodeType && element.nodeType === Node.ELEMENT_NODE;
 }
 
 module.exports = {eyesCheckMapValues};