appium-mcp 0.0.1 → 1.1.4

package/src/locators/locator-generation.ts

@@ -0,0 +1,657 @@
+import _ from 'lodash';
+import * as XPath from 'xpath';
+const xpathSelect = XPath.select;
+
+import log from './logger.js';
+import {
+  childNodesOf,
+  domToXML,
+  findDOMNodeByPath,
+  xmlToDOM,
+  JSONElement,
+  ElementAttributes,
+} from './source-parsing.js';
+import {
+  Document as XMLDocument,
+  Node as XMLNode,
+  Element as XMLElement,
+} from '@xmldom/xmldom';
+
+// Attributes on nodes that are likely to be unique to the node so we should consider first when
+// suggesting xpath locators. These are considered IN ORDER.
+const UNIQUE_XPATH_ATTRIBUTES = [
+  'name',
+  'content-desc',
+  'id',
+  'resource-id',
+  'accessibility-id',
+];
+
+// Attributes that we should recommend as a fallback but ideally only in conjunction with other
+// attributes
+const MAYBE_UNIQUE_XPATH_ATTRIBUTES = ['label', 'text', 'value'];
+
+const CHECKED_CLASS_CHAIN_ATTRIBUTES = ['name', 'label', 'value'];
+
+const CHECKED_PREDICATE_ATTRIBUTES = ['name', 'label', 'value', 'type'];
+
+// Map of element attributes to their UiAutomator syntax, ordered by (likely) decreasing uniqueness
+const CHECKED_UIAUTOMATOR_ATTRIBUTES: [string, string][] = [
+  ['resource-id', 'resourceId'],
+  ['text', 'text'],
+  ['content-desc', 'description'],
+  ['class', 'className'],
+];
+
+// Map of element attributes to their matching simple (optimal) locator strategies
+const SIMPLE_STRATEGY_MAPPINGS: [string, string][] = [
+  ['name', 'accessibility id'],
+  ['content-desc', 'accessibility id'],
+  ['id', 'id'],
+  ['rntestid', 'id'],
+  ['resource-id', 'id'],
+  ['class', 'class name'],
+  ['type', 'class name'],
+];
+
+/**
+ * Check whether the provided attribute & value are unique in the source
+ */
+export function areAttrAndValueUnique(
+  attrName: string,
+  attrValue: string,
+  sourceDoc: XMLDocument
+): boolean {
+  // If no sourceDoc provided, assume it's unique
+  if (!sourceDoc || _.isEmpty(sourceDoc)) {
+    return true;
+  }
+  const result = xpathSelect(
+    `//*[@${attrName}="${attrValue.replace(/"/g, '')}"]`,
+    sourceDoc as any
+  );
+  return Array.isArray(result) ? result.length < 2 : false;
+}
+
+/**
+ * Get suggested selectors for simple locator strategies (which match a specific attribute)
+ */
+export function getSimpleSuggestedLocators(
+  attributes: ElementAttributes,
+  sourceDoc: XMLDocument,
+  isNative: boolean = true
+): Record<string, string> {
+  const res: Record<string, string> = {};
+  for (let [strategyAlias, strategy] of SIMPLE_STRATEGY_MAPPINGS) {
+    // accessibility id is only supported in native context
+    if (!(strategy === 'accessibility id' && !isNative)) {
+      const value = attributes[strategyAlias];
+      if (value && areAttrAndValueUnique(strategyAlias, value, sourceDoc)) {
+        res[strategy] = value;
+      }
+    }
+  }
+  return res;
+}
+
+/**
+ * Get suggested selectors for complex locator strategies (multiple attributes, axes, etc.)
+ */
+export function getComplexSuggestedLocators(
+  path: string,
+  sourceDoc: XMLDocument,
+  isNative: boolean,
+  automationName: string
+): Record<string, string> {
+  let complexLocators: Record<string, string | null> = {};
+  const domNode = findDOMNodeByPath(path, sourceDoc);
+  if (isNative) {
+    switch (automationName) {
+      case 'xcuitest':
+      case 'mac2': {
+        const optimalClassChain = getOptimalClassChain(sourceDoc, domNode);
+        complexLocators['-ios class chain'] = optimalClassChain
+          ? '**' + optimalClassChain
+          : null;
+        complexLocators['-ios predicate string'] = getOptimalPredicateString(
+          sourceDoc,
+          domNode
+        );
+        break;
+      }
+      case 'uiautomator2': {
+        complexLocators['-android uiautomator'] = getOptimalUiAutomatorSelector(
+          sourceDoc,
+          domNode,
+          path
+        );
+        break;
+      }
+    }
+  }
+  complexLocators.xpath = getOptimalXPath(sourceDoc, domNode);
+
+  // Remove entries for locators where the optimal selector could not be found
+  return _.omitBy(complexLocators, _.isNil) as Record<string, string>;
+}
+
+/**
+ * Get suggested selectors for all locator strategies
+ */
+export function getSuggestedLocators(
+  selectedElement: JSONElement,
+  sourceXML: string,
+  isNative: boolean,
+  automationName: string
+): [string, string][] {
+  const sourceDoc = xmlToDOM(sourceXML);
+  const simpleLocators = getSimpleSuggestedLocators(
+    selectedElement.attributes,
+    sourceDoc,
+    isNative
+  );
+  const complexLocators = getComplexSuggestedLocators(
+    selectedElement.path,
+    sourceDoc,
+    isNative,
+    automationName
+  );
+
+  // Combine all locators
+  const allLocators = { ...simpleLocators, ...complexLocators };
+
+  // Define priority order based on platform preference
+  let priorityOrder: string[];
+
+  if (
+    isNative &&
+    (automationName === 'xcuitest' || automationName === 'mac2')
+  ) {
+    // iOS priority: Accessibility Id > Predicate > Class Chain > XPath > Class Name
+    priorityOrder = [
+      'id',
+      'accessibility id',
+      '-ios predicate string',
+      '-ios class chain',
+      'xpath',
+      'class name',
+    ];
+  } else if (isNative && automationName === 'uiautomator2') {
+    // Android priority: Accessibility Id > UiAutomator > XPath > Class Name
+    priorityOrder = [
+      'id',
+      'accessibility id',
+      'xpath',
+      '-android uiautomator',
+      'class name',
+    ];
+  } else {
+    priorityOrder = ['id', 'class name', 'xpath'];
+  }
+
+  // Sort locators by priority order, keeping only available ones
+  const sortedLocators: [string, string][] = [];
+
+  // Add locators in priority order
+  for (const strategy of priorityOrder) {
+    if (allLocators[strategy]) {
+      sortedLocators.push([strategy, allLocators[strategy]]);
+    }
+  }
+
+  // Add any remaining locators that weren't in the priority list (like 'id' for native contexts)
+  for (const [strategy, value] of _.toPairs(allLocators)) {
+    if (!priorityOrder.includes(strategy)) {
+      sortedLocators.push([strategy, value]);
+    }
+  }
+
+  // Return all valid locators, or empty array if none found
+  // Filter out any undefined entries
+  return sortedLocators.filter(
+    (locator): locator is [string, string] =>
+      Array.isArray(locator) &&
+      locator.length === 2 &&
+      typeof locator[0] === 'string' &&
+      typeof locator[1] === 'string' &&
+      locator[0] !== undefined &&
+      locator[1] !== undefined
+  );
+}
+
+/**
+ * Return information about whether an xpath query results in a unique element, and the non-unique
+ * index of the element in the document if not unique
+ */
+function determineXpathUniqueness(
+  xpath: string,
+  doc: XMLDocument,
+  domNode: XMLNode
+): [boolean, number?] {
+  let othersWithAttr: XMLNode[] = [];
+
+  // If the XPath does not parse, move to the next unique attribute
+  try {
+    const result = XPath.select(xpath, doc as any);
+    othersWithAttr = Array.isArray(result)
+      ? (result as unknown as XMLNode[])
+      : [];
+  } catch {
+    return [false];
+  }
+
+  if (othersWithAttr.length > 1) {
+    return [false, othersWithAttr.indexOf(domNode)];
+  }
+
+  return [true];
+}
+
+/**
+ * Given an xml doc and a current dom node, try to find a robust xpath selector qualified by
+ * key attributes, which is unique in the document (or unique plus index).
+ */
+function getUniqueXPath(
+  doc: XMLDocument,
+  domNode: XMLNode,
+  attrs: string[] | [string, string][]
+): [string | undefined, boolean | undefined] {
+  let uniqueXpath: string | undefined, semiUniqueXpath: string | undefined;
+  const tagForXpath = domNode.nodeName || '*';
+  const isPairs = attrs.length > 0 && _.isArray(attrs[0]);
+  const isNodeName = attrs.length === 0;
+
+  // If we're looking for a unique //<nodetype>, return it only if it's actually unique. No
+  // semi-uniqueness here!
+  if (isNodeName) {
+    let xpath = `//${domNode.nodeName}`;
+    const [isUnique] = determineXpathUniqueness(xpath, doc, domNode);
+    if (isUnique) {
+      // even if this node name is unique, if it's the root node, we don't want to refer to it using
+      // '//' but rather '/'
+      if (!domNode.parentNode?.nodeName) {
+        xpath = `/${domNode.nodeName}`;
+      }
+      return [xpath, true];
+    }
+    return [undefined, undefined];
+  }
+
+  // Otherwise go through our various attributes to look for uniqueness
+  for (const attrName of attrs) {
+    let xpath: string;
+    if (isPairs) {
+      const [attr1Name, attr2Name] = attrName as [string, string];
+      const attr1Value = (domNode as XMLElement).getAttribute?.(attr1Name);
+      const attr2Value = (domNode as XMLElement).getAttribute?.(attr2Name);
+      if (!attr1Value || !attr2Value) {
+        continue;
+      }
+      xpath = `//${tagForXpath}[@${attr1Name}="${attr1Value}" and @${attr2Name}="${attr2Value}"]`;
+    } else {
+      const attrValue = (domNode as XMLElement).getAttribute?.(
+        attrName as string
+      );
+      if (!attrValue) {
+        continue;
+      }
+      xpath = `//${tagForXpath}[@${attrName}="${attrValue}"]`;
+    }
+    const [isUnique, indexIfNotUnique] = determineXpathUniqueness(
+      xpath,
+      doc,
+      domNode
+    );
+    if (isUnique) {
+      uniqueXpath = xpath;
+      break;
+    }
+
+    // if the xpath wasn't totally unique it might still be our best bet. Store a less unique
+    // version qualified by an index for later in semiUniqueXpath. If we can't find a better
+    // unique option down the road, we'll fall back to this
+    if (!semiUniqueXpath && !_.isUndefined(indexIfNotUnique)) {
+      semiUniqueXpath = `(${xpath})[${indexIfNotUnique + 1}]`;
+    }
+  }
+  if (uniqueXpath) {
+    return [uniqueXpath, true];
+  }
+  if (semiUniqueXpath) {
+    return [semiUniqueXpath, false];
+  }
+  return [undefined, undefined];
+}
+
+/**
+ * Get an optimal XPath for a Node
+ */
+export function getOptimalXPath(
+  doc: XMLDocument,
+  domNode: XMLNode
+): string | null {
+  try {
+    // BASE CASE #1: If this isn't an element, we're above the root, return empty string
+    if (!domNode.nodeName || domNode.nodeType !== 1) {
+      return '';
+    }
+
+    const attrsForPairs = [
+      ...UNIQUE_XPATH_ATTRIBUTES,
+      ...MAYBE_UNIQUE_XPATH_ATTRIBUTES,
+    ];
+    const attrPairsPermutations: [string, string][] = attrsForPairs.flatMap(
+      (v1, i) =>
+        attrsForPairs.slice(i + 1).map(v2 => [v1, v2] as [string, string])
+    );
+
+    const cases = [
+      // BASE CASE #2: If this node has a unique attribute or content attribute, return an absolute
+      // XPath with that attribute
+      UNIQUE_XPATH_ATTRIBUTES,
+
+      // BASE CASE #3: If this node has a unique pair of attributes including 'maybe' attributes,
+      // return an xpath based on that pair
+      attrPairsPermutations,
+
+      // BASE CASE #4: Look for a 'maybe' unique attribute on its own. It's better if we find one
+      // of these that's unique in conjunction with another attribute, but if not, that's OK.
+      // Better than a hierarchical query.
+      MAYBE_UNIQUE_XPATH_ATTRIBUTES,
+
+      // BASE CASE #5: Look to see if the node type is unique in the document
+      [],
+    ];
+
+    // It's possible that in all of these cases we don't find a truly unique selector. But
+    // a selector qualified by attribute with an index attached like //*[@id="foo"][1] is still
+    // better than a fully path-based selector. We call this a 'semi unique xpath'
+    let semiUniqueXpath: string | undefined;
+
+    // Go through each of our cases and look for selectors for each case in order
+    for (const attrs of cases) {
+      const [xpath, isFullyUnique] = getUniqueXPath(doc, domNode, attrs);
+      if (isFullyUnique) {
+        // if we ever encounter an actually unique selector, return it straightaway
+        return xpath!;
+      } else if (!semiUniqueXpath && xpath) {
+        // if we have a semin unique selector, and haven't already captured a semi unique selector,
+        // hold onto it for later. If we end up without any unique selectors from any of the cases,
+        // then we'll return this. But we want to make sure to return our FIRST instance of a semi
+        // unique selector, since it might theoretically be the best.
+        semiUniqueXpath = xpath;
+      }
+    }
+
+    // Once we've gone through all our cases, if we do have a semi unique xpath, send that back
+    if (semiUniqueXpath) {
+      return semiUniqueXpath;
+    }
+
+    // Otherwise fall back to a purely hierarchical expression of this dom node's position in the
+    // document as a last resort.
+    // First get the relative xpath of this node using tagName
+    let xpath = `/${domNode.nodeName}`;
+
+    // If this node has siblings of the same tagName, get the index of this node
+    if (domNode.parentNode) {
+      // Get the siblings
+      const childNodes = Array.prototype.slice
+        .call(domNode.parentNode.childNodes, 0)
+        .filter(
+          (childNode: XMLNode) =>
+            childNode.nodeType === 1 && childNode.nodeName === domNode.nodeName
+        );
+
+      // If there's more than one sibling, append the index
+      if (childNodes.length > 1) {
+        let index = childNodes.indexOf(domNode);
+        xpath += `[${index + 1}]`;
+      }
+    }
+
+    // Make a recursive call to this nodes parents and prepend it to this xpath
+    return getOptimalXPath(doc, domNode.parentNode!) + xpath;
+  } catch (error) {
+    // If there's an unexpected exception, abort
+    logLocatorError('XPath', error);
+    return null;
+  }
+}
+
+/**
+ * Get an optimal class chain for a Node based on the getOptimalXPath method
+ */
+export function getOptimalClassChain(
+  doc: XMLDocument,
+  domNode: XMLNode
+): string | null {
+  try {
+    // BASE CASE #1: If this isn't an element, we're above the root, return empty string
+    // Also return empty for 'XCUIElementTypeApplication', which cannot be found via class chain
+    if (
+      !domNode.nodeName ||
+      domNode.nodeType !== 1 ||
+      domNode.nodeName === 'XCUIElementTypeApplication'
+    ) {
+      return '';
+    }
+
+    // BASE CASE #2: If this node has a unique class chain based on attributes, return it
+    let classChain: string, othersWithAttr: XMLNode[];
+
+    for (let attrName of CHECKED_CLASS_CHAIN_ATTRIBUTES) {
+      const attrValue = (domNode as XMLElement).getAttribute?.(attrName);
+      if (_.isEmpty(attrValue)) {
+        continue;
+      }
+      const xpath = `//${domNode.nodeName || '*'}[@${attrName}="${attrValue}"]`;
+      classChain = `/${
+        domNode.nodeName || '*'
+      }[\`${attrName} == "${attrValue}"\`]`;
+
+      // If the XPath does not parse, move to the next unique attribute
+      try {
+        const result = xpathSelect(xpath, doc as any);
+        othersWithAttr = Array.isArray(result)
+          ? (result as unknown as XMLNode[])
+          : [];
+      } catch {
+        continue;
+      }
+
+      // If the attribute isn't actually unique, get its index too
+      if (othersWithAttr.length > 1) {
+        let index = othersWithAttr.indexOf(domNode);
+        classChain = `${classChain}[${index + 1}]`;
+      }
+      return classChain;
+    }
+
+    // BASE CASE #3: If this node has no unique attributes, repeat checks for its parent
+    // Get the relative xpath of this node using tagName
+    classChain = `/${domNode.nodeName}`;
+
+    // If this node has siblings of the same tagName, get the index of this node
+    if (domNode.parentNode) {
+      // Get the siblings
+      const childNodes = Array.prototype.slice
+        .call(domNode.parentNode.childNodes, 0)
+        .filter(
+          (childNode: XMLNode) =>
+            childNode.nodeType === 1 && childNode.nodeName === domNode.nodeName
+        );
+
+      // If there's more than one sibling, append the index
+      if (childNodes.length > 1) {
+        let index = childNodes.indexOf(domNode);
+        classChain += `[${index + 1}]`;
+      }
+    }
+
+    // Make a recursive call to this nodes parents and prepend it to this xpath
+    return getOptimalClassChain(doc, domNode.parentNode!) + classChain;
+  } catch (error) {
+    // If there's an unexpected exception, abort
+    logLocatorError('class chain', error);
+    return null;
+  }
+}
+
+/**
+ * Get an optimal predicate string for a Node based on the getOptimalXPath method
+ * Only works for a single element - no parent/child scope
+ */
+export function getOptimalPredicateString(
+  doc: XMLDocument,
+  domNode: XMLNode
+): string | null {
+  try {
+    // BASE CASE #1: If this isn't an element, or we're above the root, return empty string
+    if (!domNode.nodeName || domNode.nodeType !== 1) {
+      return '';
+    }
+
+    // BASE CASE #2: Check all attributes and try to find the best way
+    let xpathAttributes: string[] = [];
+    let predicateString: string[] = [];
+    let othersWithAttr: XMLNode[];
+
+    for (let attrName of CHECKED_PREDICATE_ATTRIBUTES) {
+      const attrValue = (domNode as XMLElement).getAttribute?.(attrName);
+      if (_.isEmpty(attrValue)) {
+        continue;
+      }
+
+      xpathAttributes.push(`@${attrName}="${attrValue}"`);
+      const xpath = `//*[${xpathAttributes.join(' and ')}]`;
+      predicateString.push(`${attrName} == "${attrValue}"`);
+
+      // If the XPath does not parse, move to the next attribute
+      try {
+        const result = xpathSelect(xpath, doc as any);
+        othersWithAttr = Array.isArray(result)
+          ? (result as unknown as XMLNode[])
+          : [];
+      } catch {
+        continue;
+      }
+
+      // Return as soon as the accumulated attribute combination is unique
+      if (othersWithAttr.length === 1) {
+        return predicateString.join(' AND ');
+      }
+    }
+  } catch (error) {
+    // If there's an unexpected exception, abort
+    logLocatorError('predicate string', error);
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Get an optimal UiAutomator selector for a Node
+ * Only works for elements inside the last direct child of the hierarchy (xpath: /hierarchy/*[last()] )
+ */
+export function getOptimalUiAutomatorSelector(
+  doc: XMLDocument,
+  domNode: XMLNode,
+  path: string
+): string | null {
+  try {
+    // BASE CASE #1: If this isn't an element, or we're above the root, return empty string
+    if (!domNode.nodeName || domNode.nodeType !== 1) {
+      return '';
+    }
+
+    // UiAutomator can only find elements inside the last direct child of the hierarchy.
+    // hierarchy is the child of doc (which is <xml/>), so need to get the children of its child
+    // BASE CASE #2: If there is no hierarchy or its children, return null
+    const docChildren = childNodesOf(doc);
+    const hierarchyChildren = _.isEmpty(docChildren)
+      ? []
+      : childNodesOf(docChildren[0]);
+    if (_.isEmpty(hierarchyChildren)) {
+      return null;
+    }
+
+    // BASE CASE #3: If looking for an element that is not inside
+    // the last direct child of the hierarchy, return null
+    const lastHierarchyChildIndex = (hierarchyChildren.length - 1).toString();
+    let pathArray = path.split('.');
+    const requestedHierarchyChildIndex = pathArray[0];
+    if (requestedHierarchyChildIndex !== lastHierarchyChildIndex) {
+      return null;
+    }
+
+    // In order to use only the last direct child of the hierarchy as the new scope,
+    // need to recreate it as a Document (Node -> XML -> Document),
+    // then modify the path by changing the first index,
+    // and finally recreate the domNode, since it still references the original parent
+    const lastHierarchyChild =
+      hierarchyChildren[parseInt(lastHierarchyChildIndex, 10)];
+    const newXml = domToXML(lastHierarchyChild);
+    // wrap the new XML in a dummy tag which will have the node type Document
+    const newDoc = xmlToDOM(`<dummy>${newXml}</dummy>`);
+    pathArray[0] = '0';
+    const newPath = pathArray.join('.');
+    const newDomNode = findDOMNodeByPath(newPath, newDoc);
+
+    // BASE CASE #4: Check all attributes and try to find unique ones
+    let uiSelector: string,
+      othersWithAttr: XMLNode[],
+      othersWithAttrMinCount: number | undefined,
+      mostUniqueSelector: string | undefined;
+
+    for (const [attrName, attrTranslation] of CHECKED_UIAUTOMATOR_ATTRIBUTES) {
+      const attrValue = (newDomNode as XMLElement).getAttribute?.(attrName);
+      if (_.isEmpty(attrValue)) {
+        continue;
+      }
+
+      const xpath = `//${newDomNode.nodeName}[@${attrName}="${attrValue}"]`;
+      uiSelector = `new UiSelector().${attrTranslation}("${attrValue}")`;
+
+      // If the XPath does not parse, move to the next unique attribute
+      try {
+        const result = xpathSelect(xpath, newDoc as any);
+        othersWithAttr = Array.isArray(result)
+          ? (result as unknown as XMLNode[])
+          : [];
+      } catch {
+        continue;
+      }
+
+      // If the attribute is unique, return it, otherwise save it and add an index,
+      // but only if it returns the least number of elements
+      if (othersWithAttr.length === 1) {
+        return uiSelector;
+      } else if (
+        !othersWithAttrMinCount ||
+        othersWithAttr.length < othersWithAttrMinCount
+      ) {
+        othersWithAttrMinCount = othersWithAttr.length;
+        mostUniqueSelector = `${uiSelector}.instance(${othersWithAttr.indexOf(
+          newDomNode
+        )})`;
+      }
+    }
+
+    // BASE CASE #5: Did not find any unique attributes - use the 'most unique' selector
+    if (mostUniqueSelector) {
+      return mostUniqueSelector;
+    }
+  } catch (error) {
+    // If there's an unexpected exception, abort
+    logLocatorError('uiautomator selector', error);
+    return null;
+  }
+  return null;
+}
+
+function logLocatorError(strategy: string, error: any): void {
+  log.error(
+    `The most optimal ${strategy} could not be determined because an error was thrown: '${error}'`
+  );
+}

package/src/locators/logger.ts

@@ -0,0 +1,11 @@
+import { logger } from '@appium/support';
+
+const log = logger.getLogger('mcp-appium');
+
+export default log;
+export { log };
+
+// For backward compatibility, export as named exports
+// Note: @appium/support logger doesn't have trace method, using debug instead
+export const trace = (message: string) => log.debug(message);
+export const error = (message: string) => log.error(message);