@applitools/eyes-cypress 3.31.0 → 3.32.0

package/src/browser/transformCypressCheckSettings.ts

@@ -0,0 +1,263 @@
+type MaybeArray<T> = T | T[]
+import type {
+  CypressCheckSettings,
+  Element,
+  Selector,
+  LegacyRegion,
+  ElementWithOptions,
+  EyesSelector,
+  SelectorWithOptions,
+  FloatingRegion,
+  accessibilityRegion,
+} from '../expose'
+import type {CheckSettings, SpecType} from '@applitools/core'
+import * as utils from '@applitools/utils'
+import {transformBrowsers} from './utils'
+type CodedRegion = MaybeArray<Element | Selector | ElementWithOptions | SelectorWithOptions | LegacyRegion | EyesSelector>
+type Ref = {'applitools-ref-id': string}
+type RefRegionWIthOptions = {region: Ref} & {padding?: number | LegacyRegion; regionId?: string}
+
+export function transformCypressCheckSettings(settings: CypressCheckSettings, refer: any): CheckSettings<SpecType, 'ufg'> {
+  if (utils.types.isString(settings)) {
+    return {name: settings}
+  }
+  const target = settings.target === 'region' ? transformTargetRegion(settings) : undefined
+  return {
+    renderers: transformBrowsers(settings.browser),
+    hooks: settings.scriptHooks,
+    disableBrowserFetching: settings.disableBrowserFetching,
+    layoutBreakpoints: settings.layoutBreakpoints,
+    ufgOptions: settings.visualGridOptions,
+    name: settings.tag,
+    ignoreRegions: transformRegionsWithOptions(settings.ignore),
+    floatingRegions: convertFloatingRegion(settings.floating),
+    strictRegions: transformRegionsWithOptions(settings.strict),
+    contentRegions: transformRegionsWithOptions(settings.content),
+    layoutRegions: transformRegionsWithOptions(settings.layout),
+    accessibilityRegions: convertAccessabilityRegions(settings.accessibility),
+    userCommandId: settings.variationGroupId,
+    region: utils.types.has(target, 'region') ? target.region : undefined,
+    ignoreCaret: settings.ignoreCaret,
+    ignoreDisplacements: settings.ignoreDisplacements,
+    fully: settings.fully,
+    waitBeforeCapture: settings.waitBeforeCapture,
+    lazyLoad: settings.lazyLoad,
+    matchLevel: settings.matchLevel,
+    useDom: settings.useDom,
+    sendDom: settings.sendDom,
+    enablePatterns: settings.enablePatterns,
+    pageId: settings.pageId,
+  }
+
+  function transformTargetRegion(checkSettings: CypressCheckSettings): CheckSettings<SpecType, 'ufg'>['region'] {
+    const shadowDomSettings: any = {}
+    let regionSettings: any = {}
+    if (!Array.isArray(checkSettings.selector)) {
+      if (utils.types.has(checkSettings, 'element')) {
+        if (isHTMLElement(checkSettings.element)) {
+          regionSettings = {
+            region: Object.assign(refer.ref(checkSettings.element), {type: 'element'}),
+          }
+        } else if (utils.types.has(checkSettings.element, [0])) {
+          // JQuery element
+          regionSettings = {
+            region: Object.assign(refer.ref(checkSettings.element[0]), {type: 'element'}),
+          }
+        }
+      } else if (
+        utils.types.has(checkSettings, 'region') &&
+        utils.types.has(checkSettings.region, 'top') &&
+        utils.types.has(checkSettings.region, 'left') &&
+        utils.types.has(checkSettings.region, 'width') &&
+        utils.types.has(checkSettings.region, 'height')
+      ) {
+        regionSettings = {
+          region: {
+            y: checkSettings.region.top,
+            x: checkSettings.region.left,
+            width: checkSettings.region.width,
+            height: checkSettings.region.height,
+          },
+        }
+      } else if (!utils.types.has(checkSettings, 'selector')) {
+        regionSettings = {
+          region: checkSettings.region,
+        }
+      } else {
+        regionSettings = {
+          region: checkSettings.selector,
+        }
+      }
+    } else {
+      const selectors = checkSettings.selector
+      for (let i = selectors.length - 1; i > -1; i--) {
+        if (i === selectors.length - 1) {
+          shadowDomSettings['shadow'] = selectors[i].selector
+        } else {
+          const prevSettings = Object.assign({}, shadowDomSettings)
+          shadowDomSettings['selector'] = selectors[i].selector
+          if (!prevSettings.hasOwnProperty('selector')) {
+            shadowDomSettings['shadow'] = prevSettings.shadow
+          } else {
+            shadowDomSettings['shadow'] = prevSettings
+          }
+        }
+      }
+      regionSettings = {region: shadowDomSettings}
+    }
+    return regionSettings
+  }
+
+  function convertAccessabilityRegions(
+    accessibilityRegions: accessibilityRegion,
+  ): CheckSettings<SpecType, 'ufg'>['accessibilityRegions'] {
+    if (!accessibilityRegions) return
+    if (!Array.isArray(accessibilityRegions)) {
+      accessibilityRegions = [accessibilityRegions]
+    }
+    const accessibility: any = []
+    for (const region of accessibilityRegions) {
+      const accessabilityRegion = {
+        type: utils.types.has(region, 'accessibilityType') ? region.accessibilityType : undefined,
+      }
+
+      if (utils.types.has(region, 'selector')) {
+        const currRegion = {...accessabilityRegion, region: region.selector}
+        delete region.selector
+        accessibility.push(currRegion)
+      } else if (utils.types.has(region, 'element')) {
+        const elements = refElements(region.element)
+        delete region['element']
+        for (const element of elements) {
+          accessibility.push(Object.assign({}, region, accessabilityRegion, {region: element}))
+        }
+      } else if (utils.types.has(region, 'region')) {
+        const currRegion = {...region, type: region.region.accessibilityType}
+        delete currRegion.region.accessibilityType
+        accessibility.push(currRegion)
+      } else if (utils.types.has(region, 'top')) {
+        accessibility.push({
+          ...accessabilityRegion,
+          region: {y: region.top, x: region.left, width: region.width, height: region.height},
+        })
+      } else {
+        accessibility.push(region)
+      }
+    }
+    return accessibility
+  }
+
+  function convertFloatingRegion(floatingRegions: FloatingRegion): CheckSettings<SpecType, 'ufg'>['floatingRegions'] {
+    if (!floatingRegions) return
+    if (!Array.isArray(floatingRegions)) {
+      floatingRegions = [floatingRegions]
+    }
+    const floating = []
+
+    for (const region of floatingRegions) {
+      const floatingRegion = {
+        offset: {
+          bottom: region.maxDownOffset || 0,
+          left: region.maxLeftOffset || 0,
+          top: region.maxUpOffset || 0,
+          right: region.maxRightOffset || 0,
+        },
+      }
+      delete region.maxDownOffset
+      delete region.maxLeftOffset
+      delete region.maxUpOffset
+      delete region.maxRightOffset
+      if (utils.types.has(region, 'selector')) {
+        const currRegion = {region: region.selector, ...region, ...floatingRegion}
+        delete currRegion.selector
+        floating.push(currRegion)
+      } else if (utils.types.has(region, 'element')) {
+        const elements = refElements(region.element)
+        delete region.element
+        for (const element of elements) {
+          floating.push({...region, ...floatingRegion, region: element})
+        }
+      } else if (utils.types.has(region, 'region')) {
+        const currRegion = {offset: floatingRegion.offset, ...region}
+        floating.push(currRegion)
+      } else if (utils.types.has(region, 'top')) {
+        floating.push({
+          ...floatingRegion,
+          region: {
+            y: region.top,
+            x: region.left,
+            width: region.width,
+            height: region.height,
+          },
+        })
+      } else {
+        floating.push(region)
+      }
+    }
+    return floating
+  }
+
+  function transformRegionsWithOptions(regions: CodedRegion): CheckSettings<SpecType, 'ufg'>['ignoreRegions'] {
+    if (!regions) return
+    if (!Array.isArray(regions)) regions = [regions]
+    let resRegions: any = []
+    for (const region of regions) {
+      if (utils.types.has(region, 'element')) {
+        if (utils.types.has(region, 'padding') || utils.types.has(region, 'regionId')) {
+          const currRefElements = refElements(region.element)
+          for (const refElement of currRefElements) {
+            const curr: RefRegionWIthOptions = {region: refElement}
+            if (region.padding) {
+              curr.padding = region.padding
+            }
+            if (region.regionId) {
+              curr.regionId = region.regionId
+            }
+            resRegions.push(curr)
+          }
+        } else {
+          resRegions = [...resRegions, ...refElements(region.element)]
+        }
+      } else if (isHTMLElement(region) || utils.types.has(region, 'jquery')) {
+        // @ts-ignore
+        //for some reason TS doesn't recognize that region is an HTMLElement,
+        //but if I paste the conditions from the method here, it does recornize it
+        resRegions = [...resRegions, ...refElements(region)]
+      } else {
+        if (utils.types.has(region, 'selector') && !utils.types.has(region, 'type')) {
+          const currRegion = {region: region.selector, ...region}
+          delete currRegion.selector
+          resRegions.push(currRegion)
+        } else {
+          resRegions.push(region)
+        }
+      }
+    }
+    return resRegions
+  }
+
+  function refElements(regions: Element | Element[]): Ref[] {
+    if (!regions) return
+    if (!Array.isArray(regions)) regions = [regions]
+    const elements = []
+    for (const region of regions) {
+      if (isHTMLElement(region)) {
+        elements.push(Object.assign(refer.ref(region), {type: 'element'}))
+      } else if (utils.types.has(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) ? Object.assign(refer.ref(this), {type: 'element'}) : this)
+        })
+      } else {
+        elements.push(region)
+      }
+    }
+    return elements
+  }
+
+  function isHTMLElement(element: CodedRegion): boolean {
+    // 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 utils.types.has(element, 'nodeType') && element.nodeType === Node.ELEMENT_NODE
+  }
+}

package/src/browser/transformCypressConfig.ts

@@ -0,0 +1,56 @@
+import type {CypressEyesConfig} from '../expose'
+import type {SpecType, Config} from '@applitools/core'
+import {transformBrowsers, transformAccessibilityValidation} from './utils'
+
+export function transformCypressConfig(config: CypressEyesConfig): Config<SpecType, 'ufg'> {
+  return {
+    open: {
+      apiKey: config.apiKey,
+      serverUrl: config.serverUrl,
+      proxy: config.proxy,
+      appName: config.appName,
+      testName: config.testName,
+      displayName: config.displayName,
+      batch: {
+        ...config.batch,
+        id: config.batchId ?? config.batch?.id,
+        name: config.batchName ?? config.batch?.name,
+        sequenceName: config.batchSequenceName ?? config.batch?.sequenceName,
+        notifyOnCompletion: config.notifyOnCompletion ?? config.batch?.notifyOnCompletion,
+      },
+      keepBatchOpen: !config.shouldUseBrowserHooks,
+      environmentName: config.envName,
+      baselineBranchName: config.baselineBranchName,
+      branchName: config.branchName,
+      parentBranchName: config.parentBranchName,
+      compareWithParentBranch: config.compareWithParentBranch,
+      ignoreBaseline: config.ignoreBaseline,
+      ignoreGitBranching: config.ignoreGitMergeBase,
+      saveDiffs: config.saveDiffs,
+      properties: config.properties,
+      environment: {
+        viewportSize: config.viewportSize,
+      },
+    },
+    check: {
+      renderers: transformBrowsers(config.browser),
+      matchLevel: config.matchLevel,
+      ignoreCaret: config.ignoreCaret,
+      ignoreDisplacements: config.ignoreDisplacements,
+      accessibilitySettings: transformAccessibilityValidation(config.accessibilityValidation),
+      layoutBreakpoints: config.layoutBreakpoints,
+      sendDom: config.sendDom,
+      useDom: config.useDom,
+      enablePatterns: config.enablePatterns,
+      ufgOptions: config.visualGridOptions,
+      disableBrowserFetching: config.disableBrowserFetching,
+      hooks: config.scriptHooks,
+    },
+    screenshot: {
+      waitBeforeCapture: config.waitBeforeCapture,
+    },
+    close: {
+      updateBaselineIfNew: config.saveNewTests,
+    },
+  }
+}

package/src/browser/utils.ts

@@ -0,0 +1,33 @@
+import * as utils from '@applitools/utils'
+
+import type {CypressEyesConfig, MaybeArray, DeviceName, ScreenOrientationPlain} from '../expose'
+import type {SpecType, Config} from '@applitools/core'
+import type {Renderer} from '@applitools/core'
+
+type CypressBrowser = MaybeArray<Renderer | {deviceName: DeviceName; screenOrientation?: ScreenOrientationPlain; name?: string}>
+
+export function transformBrowsers(browsers: CypressBrowser): Renderer[] {
+  if (!browsers) return
+  if (!Array.isArray(browsers)) browsers = [browsers]
+
+  return browsers.map(browser => {
+    if (utils.types.has(browser, 'width') && utils.types.has(browser, 'height') && !utils.types.has(browser, 'name')) {
+      browser.name = 'chrome'
+      return browser
+    } else if (utils.types.has(browser, 'deviceName')) {
+      return {chromeEmulationInfo: browser}
+    } else {
+      return browser
+    }
+  })
+}
+
+export function transformAccessibilityValidation(
+  accessibilityValidation: NonNullable<CypressEyesConfig['defaultMatchSettings']>['accessibilitySettings'],
+): Config<SpecType, 'ufg'>['check']['accessibilitySettings'] {
+  if (!accessibilityValidation) return
+  return {
+    level: accessibilityValidation.level,
+    version: accessibilityValidation.guidelinesVersion,
+  }
+}

package/src/expose.ts

@@ -9,60 +9,89 @@
 /// <reference types="cypress" />
 import type * as api from '@applitools/eyes-api'
 import type * as core from '@applitools/core'
-import {type EyesSelector, type TestResultsStatus} from '@applitools/eyes-api'
+import {
+  type EyesSelector,
+  type TestResultsStatus,
+  type DeviceName,
+  type ScreenOrientationPlain,
+  type AccessibilityRegionTypePlain,
+} from '@applitools/eyes-api'
 
-export type {EyesSelector, TestResultsStatus}
-
-type MaybeArray<T> = T | T[]
-
-type LegacyRegion = {left: number; top: number; width: number; height: number}
-type Selector = {selector: string; type?: 'css' | 'xpath'; nodeType?: 'element' | 'shadow-root'} | string
-type Element = HTMLElement | JQuery<HTMLElement>
-type ElementWithOptions = {element: Element; regionId?: string; padding?: any}
+export type MaybeArray<T> = T | T[]
+export type {EyesSelector, TestResultsStatus, DeviceName, ScreenOrientationPlain}
+export type LegacyRegion = {left: number; top: number; width: number; height: number}
+export type Selector = {selector: string; type?: 'css' | 'xpath'; nodeType?: 'element' | 'shadow-root'} | string
+export type Element = HTMLElement | JQuery<HTMLElement>
+export type ElementWithOptions = {element: Element; regionId?: string; padding?: any}
+export type SelectorWithOptions = {region: Selector; regionId?: string; padding?: number | LegacyRegion}
 type SpecType = core.SpecType<unknown, unknown, Element, Selector>
+type CodedRegion = NonNullable<Element | ElementWithOptions | LegacyRegion | Selector | SelectorWithOptions>
+export type AccessibilityValidation = NonNullable<CypressEyesConfig['defaultMatchSettings']>['accessibilitySettings']
+export type FloatingRegion = MaybeArray<
+  (ElementWithOptions | SelectorWithOptions | Selector | LegacyRegion) & {
+    maxUpOffset?: number
+    maxDownOffset?: number
+    maxLeftOffset?: number
+    maxRightOffset?: number
+  }
+>
+export type accessibilityRegion = MaybeArray<
+  | ((ElementWithOptions | Selector | LegacyRegion) & {
+      accessibilityType?: AccessibilityRegionTypePlain
+    })
+  | {
+      region: {selector: Selector; accessibilityType: AccessibilityRegionTypePlain}
+      regionId?: string
+      padding?: number | LegacyRegion
+    }
+>
 
 export type CypressCheckSettings = api.CheckSettingsAutomationPlain<SpecType> & {
-  tag?: CypressCheckSettings['name']
-
+  tag?: string
   target?: 'window' | 'region'
   selector?: Selector
   element?: Element
-
-  ignore?: MaybeArray<NonNullable<CypressCheckSettings['ignoreRegions']>[number] | LegacyRegion | ElementWithOptions>
-  layout?: MaybeArray<NonNullable<CypressCheckSettings['layoutRegions']>[number] | LegacyRegion | ElementWithOptions>
-  content?: MaybeArray<NonNullable<CypressCheckSettings['contentRegions']>[number] | LegacyRegion | ElementWithOptions>
-  strict?: MaybeArray<NonNullable<CypressCheckSettings['strictRegions']>[number] | LegacyRegion | ElementWithOptions>
-  floating?: MaybeArray<
-    | NonNullable<CypressCheckSettings['floatingRegions']>[number]
-    | ((ElementWithOptions | Selector | LegacyRegion) & {
-        maxUpOffset?: number
-        maxDownOffset?: number
-        maxLeftOffset?: number
-        maxRightOffset?: number
-      })
-  >
-  accessibility?: MaybeArray<
-    | NonNullable<CypressCheckSettings['accessibilityRegions']>[number]
-    | ((ElementWithOptions | Selector | LegacyRegion) & {accessibilityType?: api.AccessibilityRegionTypePlain})
-  >
+  region?: LegacyRegion
+  ignore?: MaybeArray<CodedRegion>
+  layout?: MaybeArray<CodedRegion>
+  content?: MaybeArray<CodedRegion>
+  strict?: MaybeArray<CodedRegion>
+  floating?: FloatingRegion
+  accessibility?: accessibilityRegion
   scriptHooks?: CypressCheckSettings['hooks']
   ignoreCaret?: boolean
   ignoreDisplacements?: boolean
+  browser?: MaybeArray<
+    | NonNullable<CypressEyesConfig['browsersInfo']>[number]
+    | {deviceName: DeviceName; screenOrientation?: ScreenOrientationPlain; name?: string}
+  >
 }
 export type CypressEyesConfig = api.ConfigurationPlain<SpecType> & {
   browser?: MaybeArray<
     | NonNullable<CypressEyesConfig['browsersInfo']>[number]
-    | {deviceName: string; screenOrientation?: api.ScreenOrientationPlain; name?: string}
+    | {deviceName: DeviceName; screenOrientation?: ScreenOrientationPlain; name?: string}
   >
 
   batchId?: NonNullable<CypressEyesConfig['batch']>['id']
   batchName?: NonNullable<CypressEyesConfig['batch']>['name']
   batchSequence?: NonNullable<CypressEyesConfig['batch']>['sequenceName']
   notifyOnCompletion?: NonNullable<CypressEyesConfig['batch']>['notifyOnCompletion']
+  batchSequenceName?: NonNullable<CypressEyesConfig['batch']>['sequenceName']
 
   envName?: CypressEyesConfig['environmentName']
 
-  accessibilitySettings?: NonNullable<CypressEyesConfig['defaultMatchSettings']>['accessibilitySettings']
+  accessibilityValidation?: AccessibilityValidation
+  matchLevel?: NonNullable<CypressEyesConfig['defaultMatchSettings']>['matchLevel']
+  ignoreCaret?: NonNullable<boolean>
+  ignoreDisplacements?: NonNullable<boolean>
+  useDom?: NonNullable<boolean>
+  enablePatterns?: NonNullable<boolean>
+  scriptHooks?: {
+    beforeCaptureScreenshot: string
+  }
+  saveNewTests?: boolean
+  /** @internal */
+  shouldUseBrowserHooks?: boolean
 }
 
 export type CypressTestResultsSummary = api.TestResultsSummary

package/src/plugin/config.ts

@@ -14,6 +14,8 @@ export default function makeConfig(): {config: any; eyesConfig: EyesPluginConfig
       'disableBrowserFetching',
       'testConcurrency',
       'removeDuplicateTests',
+      'eyesFetchConcurrency',
+      'universalDebug',
     ],
   })
 
@@ -49,6 +51,7 @@ export default function makeConfig(): {config: any; eyesConfig: EyesPluginConfig
     eyesTestConcurrency: config.testConcurrency || DEFAULT_TEST_CONCURRENCY,
     eyesWaitBeforeCapture: config.waitBeforeCapture,
     eyesRemoveDuplicateTests: !!config.removeDuplicateTests,
+    universalDebug: !!config.universalDebug,
   }
 
   return {config, eyesConfig}

package/src/plugin/index.ts

@@ -24,6 +24,7 @@ export type EyesPluginConfig = {
   eyesPort?: number
   eyesIsGlobalHooksSupported?: boolean
   eyesRemoveDuplicateTests?: boolean
+  universalDebug?: boolean
 }
 
 const {config, eyesConfig} = makeConfig()

package/src/plugin/server.ts

@@ -67,6 +67,7 @@ export default function makeStartServer({logger, eyesConfig}: {logger: Logger; e
       forkOptions,
       singleton: false,
       portResolutionMode: 'random',
+      debug: eyesConfig.universalDebug,
     })
 
     const managers: {manager: object; socketWithUniversal: SocketWithUniversal}[] = []