Proposal to add element equals command (webdriverio#4802)

* webdriverio: add element equals command * rename to isEqual, compare ref in mobile * remove refetch, add test * fix doc issues

Author: mgrybyk

packages/wdio-sync/webdriverio-core.d.ts

@@ -389,6 +389,13 @@ declare namespace WebdriverIO {
  */
  isEnabled(): boolean;
 
+ /**
+ * Return true if the selected DOM-element matches with the provided one.
+ */
+ isEqual(
+ el: Element
+ ): boolean;
+
  /**
  * Returns true if element exists in the DOM
  */

packages/webdriverio/src/commands/element.js

@@ -20,6 +20,7 @@ export const isClickable = require('./element/isClickable').default
 export const isDisplayed = require('./element/isDisplayed').default
 export const isDisplayedInViewport = require('./element/isDisplayedInViewport').default
 export const isEnabled = require('./element/isEnabled').default
+export const isEqual = require('./element/isEqual').default
 export const isExisting = require('./element/isExisting').default
 export const isFocused = require('./element/isFocused').default
 export const isSelected = require('./element/isSelected').default

packages/webdriverio/src/commands/element/isEqual.js

@@ -0,0 +1,55 @@
+/**
+ *
+ * Return true if the selected element matches with the provided one.
+ *
+ * <example>
+ :isEqual.js
+ it('should detect if an element is clickable', () => {
+ const el = $('#el')
+ const sameEl = $('#el')
+ const anotherEl = $('#anotherEl')
+
+ el.isEqual(sameEl) // outputs: true
+
+ el.isEqual(anotherEl) // outputs: false
+ });
+ * </example>
+ *
+ * @alias element.isEqual
+ * @param {Element} el element to compare with
+ * @return {Boolean} true if elements are equal
+ *
+ */
+
+import { ELEMENT_KEY } from '../../constants'
+import { getBrowserObject } from '../../utils'
+
+const getWebElement = (el) => ({
+ [ELEMENT_KEY]: el.elementId, // w3c compatible
+ ELEMENT: el.elementId // jsonwp compatible
+})
+
+export default async function isEqual (el) {
+ const browser = getBrowserObject(this)
+
+ // mobile native
+ if (browser.isMobile) {
+ const context = await browser.getContext()
+ if (context.toLowerCase().includes('native')) {
+ return this.elementId === el.elementId
+ }
+ }
+
+ // browser or webview
+ let result
+ try {
+ result = await browser.execute(
+ /* istanbul ignore next */
+ (el1, el2) => el1 === el2,
+ getWebElement(this), getWebElement(el))
+ } catch (err) {
+ result = false
+ }
+
+ return result
+}

packages/webdriverio/tests/commands/element/isEqual.test.js

@@ -0,0 +1,78 @@
+import request from 'request'
+import { remote } from '../../../src'
+
+describe('isEqual test', () => {
+ let browser
+ let elem
+
+ describe('web', () => {
+ beforeAll(async () => {
+ browser = await remote({
+ baseUrl: 'http://foobar.com',
+ capabilities: {
+ browserName: 'foobar'
+ }
+ })
+ elem = await browser.$('#foo')
+ request.mockClear()
+ })
+
+ it('should return true if elements are equal', async () => {
+ expect(await elem.isEqual(elem)).toBe(true)
+ })
+
+ it('should return false if elements are NOT equal', async () => {
+ const elements = await browser.$$('#bar')
+ expect(await elem.isEqual(elements[1])).toBe(false)
+ })
+
+ it('should return false if execute command fails', async () => {
+ const execute = browser.execute
+ delete browser.execute
+ expect(await elem.isEqual(elem)).toBe(false)
+ browser.execute = execute
+ })
+ })
+
+ describe('mobile', () => {
+ beforeAll(async () => {
+ browser = await remote({
+ baseUrl: 'http://foobar.com',
+ capabilities: {
+ mobileMode: true,
+ browserName: 'foobar'
+ }
+ })
+ elem = await browser.$('#foo')
+ request.mockClear()
+ })
+
+ it('should return true if elements are equal', async () => {
+ request.setMockResponse(['NATIVE_APP'])
+ expect(await elem.isEqual(elem)).toBe(true)
+ })
+
+ it('should return false if elements are NOT equal', async () => {
+ const elements = await browser.$$('#bar')
+ request.setMockResponse(['NATIVE_APP'])
+ expect(await elem.isEqual(elements[1])).toBe(false)
+ })
+
+ it('should call execute if in webview', async () => {
+ request.setMockResponse(['WEBVIEW'])
+ const execute = browser.execute
+ delete browser.execute
+ browser.execute = jest.fn().mockReturnValue(true)
+
+ expect(await elem.isEqual(elem)).toBe(true)
+ expect(browser.execute).toBeCalled()
+
+ delete browser.execute
+ browser.execute = execute
+ })
+ })
+
+ afterEach(() => {
+ request.mockClear()
+ })
+})

packages/webdriverio/webdriverio-core-v5.d.ts

@@ -389,6 +389,13 @@ declare namespace WebdriverIO {
  */
  isEnabled(): boolean;
 
+ /**
+ * Return true if the selected DOM-element matches with the provided one.
+ */
+ isEqual(
+ el: Element
+ ): boolean;
+
  /**
  * Returns true if element exists in the DOM
  */

packages/webdriverio/webdriverio-core.d.ts

@@ -389,6 +389,13 @@ declare namespace WebdriverIO {
  */
  isEnabled(): Promise<boolean>;
 
+ /**
+ * Return true if the selected DOM-element matches with the provided one.
+ */
+ isEqual(
+ el: Element
+ ): Promise<boolean>;
+
  /**
  * Returns true if element exists in the DOM
  */