How to use rewriteMagicScrollable method in Appium Xcuitest Driver

1import _ from 'lodash';
2import { errors } from 'appium-base-driver';
3import { util } from 'appium-support';
4import log from '../logger';
5
6// we override the xpath search for this first-visible-child selector, which
7// looks like /*[@firstVisible="true"]
8const MAGIC_FIRST_VIS_CHILD_SEL = /\/\*\[@firstVisible\s*=\s*('|")true\1\]/;
9
10// we likewise override xpath search to provide a shortcut for finding all
11// scrollable elements
12const MAGIC_SCROLLABLE_SEL = /\/\/\*\[@scrollable\s*=\s*('|")true\1\]/;
13
14const WDA_CLASS_CHAIN_STRATEGY = 'class chain';
15
16let helpers = {}, commands = {}, extensions = {};
17
18helpers.findElOrEls = async function findElOrEls (strategy, selector, mult, context) {
19  if (this.isWebview()) {
20    return await this.findWebElementOrElements(strategy, selector, mult, context);
21  } else {
22    return await this.findNativeElementOrElements(strategy, selector, mult, context);
23  }
24};
25
26helpers.findNativeElementOrElements = async function findNativeElementOrElements (strategy, selector, mult, context) {
27  const initSelector = selector;
28  let rewroteSelector = false;
29  if (strategy === '-ios predicate string') {
30    // WebDriverAgent uses 'predicate string'
31    strategy = 'predicate string';
32  } else if (strategy === '-ios class chain') {
33    // WebDriverAgent uses 'class chain'
34    strategy = WDA_CLASS_CHAIN_STRATEGY;
35  }
36
37  // Check if the word 'View' is appended to selector and if it is, strip it out
38  function stripViewFromSelector (selector) {
39    // Don't strip it out if it's one of these 4 element types
40    // (see https://github.com/facebook/WebDriverAgent/blob/master/WebDriverAgentLib/Utilities/FBElementTypeTransformer.m for reference)
41    const keepView = [
42      'XCUIElementTypeScrollView',
43      'XCUIElementTypeCollectionView',
44      'XCUIElementTypeTextView',
45      'XCUIElementTypeWebView',
46    ].includes(selector);
47
48    if (!keepView && selector.indexOf('View') === selector.length - 4) {
49      return selector.substr(0, selector.length - 4);
50    } else {
51      return selector;
52    }
53  }
54
55  if (strategy === 'class name') {
56    // XCUITest classes have `XCUIElementType` prepended
57    // first check if there is the old `UIA` prefix
58    if (selector.startsWith('UIA')) {
59      selector = selector.substring(3);
60    }
61    // now check if we need to add `XCUIElementType`
62    if (!selector.startsWith('XCUIElementType')) {
63      selector = stripViewFromSelector(`XCUIElementType${selector}`);
64      rewroteSelector = true;
65    }
66  }
67
68  if (strategy === 'xpath' && MAGIC_FIRST_VIS_CHILD_SEL.test(selector)) {
69    return await this.getFirstVisibleChild(mult, context);
70  } else if (strategy === 'xpath' && MAGIC_SCROLLABLE_SEL.test(selector)) {
71    [strategy, selector] = rewriteMagicScrollable(mult);
72  } else if (strategy === 'xpath') {
73    // Replace UIA if it comes after a forward slash or is at the beginning of the string
74    selector = selector.replace(/(^|\/)(UIA)([^[/]+)/g, (str, g1, g2, g3) => {
75      rewroteSelector = true;
76      return g1 + stripViewFromSelector(`XCUIElementType${g3}`);
77    });
78  }
79
80  if (rewroteSelector) {
81    log.info(`Rewrote incoming selector from '${initSelector}' to ` +
82             `'${selector}' to match XCUI type. You should consider ` +
83             `updating your tests to use the new selectors directly`);
84  }
85
86  return await this.doNativeFind(strategy, selector, mult, context);
87};
88
89helpers.doNativeFind = async function doNativeFind (strategy, selector, mult, context) {
90  context = util.unwrapElement(context);
91
92  let endpoint = `/element${context ? `/${context}/element` : ''}${mult ? 's' : ''}`;
93
94  let body = {
95    using: strategy,
96    value: selector
97  };
98
99  let method = 'POST';
100
101  // This is either an array is mult === true
102  // or an object if mult === false
103  let els;
104  try {
105    await this.implicitWaitForCondition(async () => {
106      try {
107        els = await this.proxyCommand(endpoint, method, body);
108      } catch (err) {
109        els = [];
110      }
111      // we succeed if we get some elements
112      return !_.isEmpty(els);
113    });
114  } catch (err) {
115    if (err.message && err.message.match(/Condition unmet/)) {
116      // condition was not met setting res to empty array
117      els = [];
118    } else {
119      throw err;
120    }
121  }
122  if (mult) {
123    return els;
124  }
125  if (_.isEmpty(els)) {
126    throw new errors.NoSuchElementError();
127  }
128  return els;
129};
130
131helpers.getFirstVisibleChild = async function getFirstVisibleChild (mult, context) {
132  log.info(`Getting first visible child`);
133  if (mult) {
134    throw new Error('Cannot get multiple first visible children!');
135  }
136  if (!context) {
137    throw new Error('Cannot get first visible child without a context element');
138  }
139  let index = 1;
140  // loop through children via class-chain finds, until we run out of children
141  // or we find a visible one. This loop looks infinite but its not, because at
142  // some point the call to doNativeFind will throw with an Element Not Found
143  // error, when the index gets higher than the number of child elements. This
144  // is what we want because that error will halt the loop and make it all the
145  // way to the client.
146  while (true) { // eslint-disable-line no-constant-condition
147    const strategy = WDA_CLASS_CHAIN_STRATEGY;
148    const selector = `*[${index}]`;
149    const nthChild = await this.doNativeFind(strategy, selector, false, context);
150    const visible = await this.getAttribute('visible', nthChild);
151    if (visible === 'true') {
152      log.info(`Found first visible child at position ${index}`);
153      return nthChild;
154    }
155    index++;
156  }
157};
158
159function rewriteMagicScrollable (mult) {
160  const types = [
161    'ScrollView',
162    'Table',
163    'CollectionView',
164    'WebView'
165  ].map(t => `XCUIElementType${t}`);
166  const pred = types.map(t => `type == "${t}"`).join(' OR ');
167  const strategy = WDA_CLASS_CHAIN_STRATEGY;
168  let selector = '**/*[`' + pred + '`]';
169  if (!mult) {
170    selector += '[1]';
171  }
172  log.info('Rewrote request for scrollable descendants to class chain ' +
173           `format with selector '${selector}'`);
174  return [strategy, selector];
175}
176
177
178Object.assign(extensions, commands, helpers);
179export { commands, helpers};
180export default extensions;
181

Source: find.js

import _ from 'lodash';
import { errors } from 'appium-base-driver';
import { util } from 'appium-support';
import log from '../logger';

// we override the xpath search for this first-visible-child selector, which
// looks like /*[@firstVisible="true"]
const MAGIC_FIRST_VIS_CHILD_SEL = /\/\*\[@firstVisible\s*=\s*('|")true\1\]/;

// we likewise override xpath search to provide a shortcut for finding all
// scrollable elements
const MAGIC_SCROLLABLE_SEL = /\/\/\*\[@scrollable\s*=\s*('|")true\1\]/;

const WDA_CLASS_CHAIN_STRATEGY = 'class chain';

let helpers = {}, commands = {}, extensions = {};

helpers.findElOrEls = async function findElOrEls (strategy, selector, mult, context) {
  if (this.isWebview()) {
    return await this.findWebElementOrElements(strategy, selector, mult, context);
  } else {
    return await this.findNativeElementOrElements(strategy, selector, mult, context);
  }
};

helpers.findNativeElementOrElements = async function findNativeElementOrElements (strategy, selector, mult, context) {
  const initSelector = selector;
  let rewroteSelector = false;
  if (strategy === '-ios predicate string') {
    // WebDriverAgent uses 'predicate string'
    strategy = 'predicate string';
  } else if (strategy === '-ios class chain') {
    // WebDriverAgent uses 'class chain'
    strategy = WDA_CLASS_CHAIN_STRATEGY;
  }

  // Check if the word 'View' is appended to selector and if it is, strip it out
  function stripViewFromSelector (selector) {
    // Don't strip it out if it's one of these 4 element types
    // (see https://github.com/facebook/WebDriverAgent/blob/master/WebDriverAgentLib/Utilities/FBElementTypeTransformer.m for reference)
    const keepView = [
      'XCUIElementTypeScrollView',
      'XCUIElementTypeCollectionView',
      'XCUIElementTypeTextView',
      'XCUIElementTypeWebView',
    ].includes(selector);

    if (!keepView && selector.indexOf('View') === selector.length - 4) {
      return selector.substr(0, selector.length - 4);
    } else {
      return selector;
    }
  }

  if (strategy === 'class name') {
    // XCUITest classes have `XCUIElementType` prepended
    // first check if there is the old `UIA` prefix
    if (selector.startsWith('UIA')) {
      selector = selector.substring(3);
    }
    // now check if we need to add `XCUIElementType`
    if (!selector.startsWith('XCUIElementType')) {
      selector = stripViewFromSelector(`XCUIElementType${selector}`);
      rewroteSelector = true;
    }
  }

  if (strategy === 'xpath' && MAGIC_FIRST_VIS_CHILD_SEL.test(selector)) {
    return await this.getFirstVisibleChild(mult, context);
  } else if (strategy === 'xpath' && MAGIC_SCROLLABLE_SEL.test(selector)) {
    [strategy, selector] = rewriteMagicScrollable(mult);
  } else if (strategy === 'xpath') {
    // Replace UIA if it comes after a forward slash or is at the beginning of the string
    selector = selector.replace(/(^|\/)(UIA)([^[/]+)/g, (str, g1, g2, g3) => {
      rewroteSelector = true;
      return g1 + stripViewFromSelector(`XCUIElementType${g3}`);
    });
  }

  if (rewroteSelector) {
    log.info(`Rewrote incoming selector from '${initSelector}' to ` +
             `'${selector}' to match XCUI type. You should consider ` +
             `updating your tests to use the new selectors directly`);
  }

  return await this.doNativeFind(strategy, selector, mult, context);
};

helpers.doNativeFind = async function doNativeFind (strategy, selector, mult, context) {
  context = util.unwrapElement(context);

  let endpoint = `/element${context ? `/${context}/element` : ''}${mult ? 's' : ''}`;

  let body = {
    using: strategy,
    value: selector
  };

  let method = 'POST';

  // This is either an array is mult === true
  // or an object if mult === false
  let els;
  try {
    await this.implicitWaitForCondition(async () => {
      try {
        els = await this.proxyCommand(endpoint, method, body);
      } catch (err) {
        els = [];
      }
      // we succeed if we get some elements
      return !_.isEmpty(els);
    });
  } catch (err) {
    if (err.message && err.message.match(/Condition unmet/)) {
      // condition was not met setting res to empty array
      els = [];
    } else {
      throw err;
    }
  }
  if (mult) {
    return els;
  }
  if (_.isEmpty(els)) {
    throw new errors.NoSuchElementError();
  }
  return els;
};

helpers.getFirstVisibleChild = async function getFirstVisibleChild (mult, context) {
  log.info(`Getting first visible child`);
  if (mult) {
    throw new Error('Cannot get multiple first visible children!');
  }
  if (!context) {
    throw new Error('Cannot get first visible child without a context element');
  }
  let index = 1;
  // loop through children via class-chain finds, until we run out of children
  // or we find a visible one. This loop looks infinite but its not, because at
  // some point the call to doNativeFind will throw with an Element Not Found
  // error, when the index gets higher than the number of child elements. This
  // is what we want because that error will halt the loop and make it all the
  // way to the client.
  while (true) { // eslint-disable-line no-constant-condition
    const strategy = WDA_CLASS_CHAIN_STRATEGY;
    const selector = `*[${index}]`;
    const nthChild = await this.doNativeFind(strategy, selector, false, context);
    const visible = await this.getAttribute('visible', nthChild);
    if (visible === 'true') {
      log.info(`Found first visible child at position ${index}`);
      return nthChild;
    }
    index++;
  }
};

function rewriteMagicScrollable (mult) {
  const types = [
    'ScrollView',
    'Table',
    'CollectionView',
    'WebView'
  ].map(t => `XCUIElementType${t}`);
  const pred = types.map(t => `type == "${t}"`).join(' OR ');
  const strategy = WDA_CLASS_CHAIN_STRATEGY;
  let selector = '**/*[`' + pred + '`]';
  if (!mult) {
    selector += '[1]';
  }
  log.info('Rewrote request for scrollable descendants to class chain ' +
           `format with selector '${selector}'`);
  return [strategy, selector];
}


Object.assign(extensions, commands, helpers);
export { commands, helpers};
export default extensions;