@xenon-device-management/xenon 2.13.2 → 2.15.0

package/lib/src/services/healing/fingerprintIdentity.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * What a stored fingerprint (`LocatorSignature.attributes`) says about which
+ * element it is, as opposed to where the element was (x, y, width, height).
+ *
+ * Through 2.14 every learnt fingerprint held only the rect and the type: the
+ * attribute reads failed (CommandInterceptor.triggerLearning). Fuzzy XML, which
+ * weighs position above everything else, then healed a selector to whatever
+ * element of that type sat at that spot. A fingerprint with no identity isn't
+ * used for position, and is learnt again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINGERPRINT_IDENTITY_ATTRIBUTES = void 0;
+exports.meaningful = meaningful;
+exports.hasIdentity = hasIdentity;
+exports.attributesToLearn = attributesToLearn;
+exports.resourceIdName = resourceIdName;
+exports.stableIdentifierOf = stableIdentifierOf;
+exports.sameIdentifier = sameIdentifier;
+exports.sameText = sameText;
+/**
+ * The attributes that say which element a fingerprint is. Not `value`: on a
+ * text field it is what the test typed, which fingerprints no longer keep.
+ */
+exports.FINGERPRINT_IDENTITY_ATTRIBUTES = [
+    'resource-id',
+    'content-desc',
+    'accessibility-id',
+    'text',
+    'name',
+    'label',
+    'id',
+    'hint',
+];
+/**
+ * A value that says something: a string with more than spaces in it, and not
+ * "null", which is what UiAutomator2 answers for an attribute the element
+ * hasn't set (its getAttribute is String(value)).
+ */
+function meaningful(value) {
+    return typeof value === 'string' && value.trim() !== '' && value.trim() !== 'null';
+}
+/** Whether a fingerprint says anything about which element it is. */
+function hasIdentity(attributes) {
+    return exports.FINGERPRINT_IDENTITY_ATTRIBUTES.some((name) => meaningful(attributes === null || attributes === void 0 ? void 0 : attributes[name]));
+}
+/**
+ * The attributes learning asks a driver for: those it has. UiAutomator2
+ * throws for `id` and `label`, and its `name` is the text again; WebDriverAgent
+ * throws for anything but its own, so five of the old list were five failed
+ * round trips per selector learnt.
+ */
+function attributesToLearn(platformName) {
+    const platform = String(platformName !== null && platformName !== void 0 ? platformName : '').toLowerCase();
+    if (platform === 'android')
+        return ['resource-id', 'content-desc', 'text', 'hint'];
+    if (platform === 'ios' || platform === 'tvos')
+        return ['name', 'label'];
+    return ['resource-id', 'content-desc', 'text', 'hint', 'name', 'label'];
+}
+/**
+ * An Android resource-id without its package: `com.shop:id/pay` is `pay`.
+ * Fuzzy XML's veto asks whether two ids are the same this way: ids of one
+ * app share the package, and of a debug build another one. Its score still
+ * compares whole ids, where the shared package earns a share of the weight.
+ */
+function resourceIdName(resourceId) {
+    const at = resourceId.lastIndexOf(':id/');
+    if (at >= 0)
+        return resourceId.slice(at + 4);
+    return resourceId.slice(resourceId.lastIndexOf('/') + 1);
+}
+/**
+ * The identifier a developer gave the element, which stays when its text
+ * changes: an Android resource-id, or an iOS accessibility identifier (`name`
+ * when it isn't just the label; an element without one has its label as name).
+ */
+function stableIdentifierOf(attributes) {
+    const resourceId = attributes === null || attributes === void 0 ? void 0 : attributes['resource-id'];
+    if (meaningful(resourceId))
+        return { attribute: 'resource-id', value: resourceId };
+    const name = attributes === null || attributes === void 0 ? void 0 : attributes.name;
+    if (meaningful(name) && name !== (attributes === null || attributes === void 0 ? void 0 : attributes.label))
+        return { attribute: 'name', value: name };
+    return null;
+}
+// Built at run time: the compiler's target predates Unicode property escapes
+// in regular expression literals. Letters, their combining marks and digits,
+// in any script.
+const NOT_A_WORD = new RegExp('[^\\p{L}\\p{M}\\p{N}]+', 'gu');
+const CAMEL_TURN = new RegExp('([\\p{Ll}\\p{N}])(\\p{Lu})', 'gu');
+/** An identifier's words: split where camelCase turns and at anything but a letter or digit. */
+function identifierWords(identifier) {
+    return identifier
+        .normalize('NFC')
+        .replace(CAMEL_TURN, '$1 $2')
+        .toLowerCase()
+        .split(NOT_A_WORD)
+        .filter(Boolean);
+}
+/**
+ * Whether two identifiers name the same element: they have the same words,
+ * however written (btn-pay, pay_btn, payBtn). Any other pair names another
+ * element, and the text decides: an id that gains words is as often another
+ * element (pay_later, undo_delete) as a rename (checkout_pay), and letters
+ * alone can't tell follow from unfollow, or checkout.cancel from
+ * checkout.pay (64% of their letter pairs are shared). Two with no letter or
+ * digit between them can't be told apart, and count as the same.
+ */
+function sameIdentifier(a, b) {
+    const [wordsA, wordsB] = [new Set(identifierWords(a)), new Set(identifierWords(b))];
+    if (wordsA.size !== wordsB.size)
+        return false;
+    return [...wordsA].every((w) => wordsB.has(w));
+}
+/**
+ * Whether two texts read the same: case, punctuation and spacing aside, with
+ * accents composed (NFC). Combining marks count: Hindi दें and दो differ only
+ * by theirs. Nothing looser: "Log in" and "Log out", "Enable" and "Disable"
+ * are as alike by their letters as a reworded label is.
+ */
+function sameText(a, b) {
+    const read = (t) => t.normalize('NFC').toLowerCase().replace(NOT_A_WORD, ' ').trim();
+    const [textA, textB] = [read(a), read(b)];
+    return textA !== '' && textA === textB;
+}

package/lib/src/services/healing/resilioPath.js

@@ -0,0 +1,274 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_LEAD = exports.MIN_SCORE = exports.RESILIO_PATH_FORMAT = void 0;
+exports.resilioPathOf = resilioPathOf;
+exports.isResilioPath = isResilioPath;
+exports.findLearntElement = findLearntElement;
+exports.nearestElement = nearestElement;
+exports.locatorsSelectingOnly = locatorsSelectingOnly;
+exports.contradictsSelector = contradictsSelector;
+const xmldom_1 = require("@xmldom/xmldom");
+const resiliotree_1 = require("resiliotree");
+const xpath_1 = require("xpath");
+/**
+ * The Resilio healing tier's view of a page source: an element's path from
+ * the root of the driver's element tree, as resiliotree compares paths.
+ *
+ * The page source is parsed as the XML it is. Through 2.14 it went through
+ * resiliotree's HTML parser, which lowercases every tag
+ * (`android.widget.button`, which the drivers' XPath doesn't match) and nests
+ * every element written `<x/>` around its next siblings.
+ *
+ * A path is stored with the selector's fingerprint (`LocatorEtalon.path`).
+ * Each node keeps what resiliotree compares (tag, id, labels, index, other
+ * attributes), not its children or text, so a path is a few kilobytes.
+ */
+/** Marks a path made here. A path without it (an HTML parse, before 2.15) is not used. */
+exports.RESILIO_PATH_FORMAT = 'page-source-1';
+/**
+ * How sure Resilio must be. An element that kept its id scores about 0.99
+ * after moving anywhere in the tree; once its id changed, or it is gone, the
+ * best element scores about 0.55, and a neighbour of the same type comes
+ * within a few hundredths of it. Below this, or with a second element as
+ * close as MIN_LEAD, the next tier decides.
+ */
+exports.MIN_SCORE = 0.8;
+exports.MIN_LEAD = 0.05;
+function platformOf(pageSource) {
+    if (/<XCUIElementType/.test(pageSource))
+        return 'ios';
+    if (/<hierarchy[\s>]/.test(pageSource))
+        return 'android';
+    return 'other';
+}
+const isElement = (n) => !!n && n.nodeType === 1;
+function childElements(el) {
+    const out = [];
+    for (let c = el.firstChild; c; c = c.nextSibling)
+        if (isElement(c))
+            out.push(c);
+    return out;
+}
+/**
+ * One element as a resiliotree node, without children. The platform decides
+ * what its id is: Android's resource-id, iOS's name, else `id`.
+ */
+function nodeBuilderFor(el, index, platform) {
+    const attributes = new Map();
+    for (let i = 0; i < el.attributes.length; i++) {
+        attributes.set(el.attributes[i].name, el.attributes[i].value);
+    }
+    const builder = new resiliotree_1.NodeBuilder().setTag(el.tagName).setIndex(index);
+    if (platform === 'android')
+        builder.setAndroidAttributes(attributes);
+    else if (platform === 'ios')
+        builder.setIOSAttributes(attributes);
+    else
+        builder.setAttributes(attributes);
+    return builder;
+}
+function parse(pageSource) {
+    return new xmldom_1.DOMParser({
+        errorHandler: { warning: () => { }, error: () => { }, fatalError: () => { } },
+    }).parseFromString(pageSource, 'text/xml');
+}
+/** The page source as a resiliotree tree, each node knowing its element. */
+function treeOf(pageSource) {
+    const doc = parse(pageSource);
+    const top = doc === null || doc === void 0 ? void 0 : doc.documentElement;
+    if (!isElement(top))
+        return null;
+    const platform = platformOf(pageSource);
+    const elementOf = new Map();
+    const build = (el, index) => {
+        const builder = nodeBuilderFor(el, index, platform);
+        childElements(el).forEach((child, i) => builder.addChild(build(child, i)));
+        const node = builder.build();
+        elementOf.set(node, el);
+        return node;
+    };
+    return { root: build(top, 0), elementOf };
+}
+function compact(node) {
+    const _a = node.toJSON(), { children: _children, innerText: _text } = _a, rest = __rest(_a, ["children", "innerText"]);
+    return rest;
+}
+/**
+ * The path of an element of a parsed page source (an xmldom Element, as the
+ * Fuzzy XML and Resilio tiers find them), from the root of the page source.
+ * `pageSource` decides the platform. Null for anything that isn't such an
+ * element.
+ */
+function resilioPathOf(element, pageSource) {
+    if (!isElement(element))
+        return null;
+    const platform = platformOf(pageSource);
+    const lineage = [];
+    for (let el = element; isElement(el); el = el.parentNode)
+        lineage.unshift(el);
+    const nodes = lineage.map((el) => {
+        const parent = el.parentNode;
+        const index = isElement(parent) ? childElements(parent).indexOf(el) : 0;
+        return compact(nodeBuilderFor(el, index, platform).build());
+    });
+    return { format: exports.RESILIO_PATH_FORMAT, nodes };
+}
+/** Whether `path` is one made here (not an older HTML parse). */
+function isResilioPath(path) {
+    return (!!path &&
+        typeof path === 'object' &&
+        path.format === exports.RESILIO_PATH_FORMAT &&
+        Array.isArray(path.nodes) &&
+        path.nodes.length > 0);
+}
+/** Attributes that say which element an element is, not where it is or what state it is in. */
+const IDENTITY_ATTRIBUTES = new Set([
+    'resource-id',
+    'content-desc',
+    'text',
+    'name',
+    'label',
+    'value',
+    'id',
+    'hint',
+    'accessibility-id',
+]);
+/**
+ * The element of the page source that the driver found, from its tag and the
+ * attributes Xenon read from it (`name`/`value` pairs: resource-id, text,
+ * name, label, ..., and x, y, width, height). The element of that tag with
+ * the most of them, among those that share at least one identity attribute or
+ * the whole rect with it: the page source is read after the find answered,
+ * so the screen may have changed, and a size alone names nothing. Null when
+ * none qualifies, or two qualify equally well.
+ */
+function findLearntElement(pageSource, nodeName, attributes) {
+    const doc = parse(pageSource);
+    if (!isElement(doc === null || doc === void 0 ? void 0 : doc.documentElement))
+        return null;
+    const tag = (nodeName || '').toLowerCase();
+    const anyTag = !tag || tag === 'xcuielementtypeany' || tag === 'unknown';
+    const wanted = new Map(attributes.map((a) => [a.name.toLowerCase(), String(a.value)]));
+    const rect = ['x', 'y', 'width', 'height'].map((k) => wanted.get(k));
+    const hasRect = rect.every((v) => v !== undefined);
+    /** How many of the attributes `el` shares, or 0 when it shares no identity and not the rect. */
+    const matchesOf = (el) => {
+        let all = 0;
+        let identity = 0;
+        for (const [name, value] of wanted) {
+            if (el.getAttribute(name) !== value)
+                continue;
+            all++;
+            if (IDENTITY_ATTRIBUTES.has(name))
+                identity++;
+        }
+        // Android writes a rect as bounds="[x1,y1][x2,y2]"; iOS as x, y, width, height.
+        let wholeRect = hasRect && ['x', 'y', 'width', 'height'].every((k, i) => el.getAttribute(k) === rect[i]);
+        const bounds = el.getAttribute('bounds');
+        if (bounds && hasRect) {
+            const [x, y, w, h] = rect.map(Number);
+            if (bounds === `[${x},${y}][${x + w},${y + h}]`) {
+                all++;
+                wholeRect = true;
+            }
+        }
+        return identity > 0 || wholeRect ? all : 0;
+    };
+    let best = null;
+    let bestCount = 0;
+    let tie = false;
+    const walk = (el) => {
+        if (anyTag || el.tagName.toLowerCase() === tag) {
+            const n = matchesOf(el);
+            if (n > bestCount) {
+                best = el;
+                bestCount = n;
+                tie = false;
+            }
+            else if (n > 0 && n === bestCount) {
+                tie = true;
+            }
+        }
+        childElements(el).forEach(walk);
+    };
+    walk(doc.documentElement);
+    return tie ? null : best;
+}
+/**
+ * The element of `pageSource` at the end of the path most like `path`, and
+ * how alike they are (0 to 1). Null when no element scores MIN_SCORE, or
+ * another comes within MIN_LEAD of the best: Resilio then has no answer.
+ */
+function nearestElement(path, pageSource) {
+    const tree = treeOf(pageSource);
+    if (!tree)
+        return null;
+    const finder = new resiliotree_1.PathFinder(new resiliotree_1.LCSPathDistance(), new resiliotree_1.HeuristicNodeDistance());
+    // resiliotree scores an element once for each leaf below it, so an element
+    // holding others (a list row) comes back several times at one score. Every
+    // result, best first, and the best of each element.
+    const scored = finder.find(resiliotree_1.Path.fromJSON(path), tree.root, Number.MAX_SAFE_INTEGER);
+    const best = scored[0];
+    if (!best || best.score < exports.MIN_SCORE)
+        return null;
+    const second = scored.find((s) => s.value !== best.value);
+    if (second && best.score - second.score < exports.MIN_LEAD)
+        return null;
+    const element = tree.elementOf.get(best.value);
+    return element ? { element, score: best.score } : null;
+}
+/**
+ * The locators among `candidates` that select `element` and nothing else in
+ * its page source. A driver answers a find with the first match, so a
+ * locator that also matches an element before it would hand back that one.
+ */
+function locatorsSelectingOnly(element, candidates) {
+    const doc = element.ownerDocument;
+    return candidates.filter((xpath) => {
+        try {
+            const found = (0, xpath_1.select)(xpath, doc);
+            return Array.isArray(found) && found.length === 1 && found[0] === element;
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}
+/** The text-like attributes a selector can state that the element it means must have. */
+const STATED_ATTRIBUTES = 'text|content-desc|label|name|value';
+/**
+ * Whether `element` has, for an attribute the XPath `selector` states (the
+ * text, description, label, name or value), something other than what it
+ * says: `@text='OK'` on an element reading "Delete". Resilio compares paths,
+ * in which a changed text weighs little, so a dialog's OK button that now
+ * reads Delete would otherwise be healed to. A stated attribute may belong to
+ * another element of the XPath (an ancestor, a sibling); Resilio then
+ * declines a heal it could have made, and the next tier decides.
+ */
+function contradictsSelector(element, strategy, selector) {
+    if (strategy !== 'xpath' || typeof selector !== 'string')
+        return false;
+    const valueOf = (name) => { var _a; return (_a = element.getAttribute(name)) !== null && _a !== void 0 ? _a : ''; };
+    const equals = new RegExp(`@(${STATED_ATTRIBUTES})\\s*=\\s*(['"])(.*?)\\2`, 'g');
+    for (const [, name, , value] of selector.matchAll(equals)) {
+        if (valueOf(name) !== value)
+            return true;
+    }
+    const contains = new RegExp(`contains\\(\\s*@(${STATED_ATTRIBUTES})\\s*,\\s*(['"])(.*?)\\2\\s*\\)`, 'g');
+    for (const [, name, , value] of selector.matchAll(contains)) {
+        if (!valueOf(name).includes(value))
+            return true;
+    }
+    return false;
+}

package/lib/src/services/interceptor/AndroidProxyAdapter.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AndroidProxyAdapter = void 0;
+const xenonProxy_1 = require("../network/xenonProxy");
 class AndroidProxyAdapter {
     constructor(getAdb) {
         this.getAdb = getAdb;
@@ -38,6 +39,23 @@ class AndroidProxyAdapter {
             yield adb.adbExec(['-s', udid, 'shell', 'settings', 'put', 'global', 'http_proxy', ':0']);
         });
     }
+    /** The phone's global HTTP proxy as stored: `host:port`, or `null` / `:0` / '' for none. */
+    readProxy(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const adb = yield this.getAdb(udid);
+            const out = yield adb.adbExec(['-s', udid, 'shell', 'settings', 'get', 'global', 'http_proxy']);
+            return String(out !== null && out !== void 0 ? out : '').trim();
+        });
+    }
+    /** Puts `previous` back as the phone's proxy, or clears it when there was none. */
+    restoreProxy(udid, previous) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (previous === null || (0, xenonProxy_1.isUnsetProxy)(previous))
+                return this.clearProxy(udid);
+            const adb = yield this.getAdb(udid);
+            yield adb.adbExec(['-s', udid, 'shell', 'settings', 'put', 'global', 'http_proxy', previous]);
+        });
+    }
     // Forwards a port on the device back to a port on the host over the adb transport
     // (USB or wireless adb). The device sees `127.0.0.1:devicePort` and that traffic
     // reaches the host's `hostPort`. This is the standard way to make a host-side

package/lib/src/services/interceptor/interceptorOptions.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInterceptorOptions = resolveInterceptorOptions;
+const XenonCapabilityManager_1 = require("../../XenonCapabilityManager");
+/**
+ * The network capture a session gets: its own capability (any of the shapes
+ * getXenonCapabilities reads) wins field by field, and the server's
+ * `interceptor` option fills in what the session leaves unset.
+ *
+ * - `enabled`: the session's, when it says true or false; else the server's;
+ *   else off.
+ * - `bufferSize`, `captureBodies`: the session's, else the server's, else the
+ *   service's defaults (1000, true).
+ * - `mocks`, `includeHosts`, `excludeHosts`: the session's only.
+ *
+ * `sessionCaps` is getXenonCapabilities' output, where a field the session
+ * didn't set is `undefined`.
+ */
+function resolveInterceptorOptions(sessionCaps, server) {
+    var _a;
+    const own = (key) => sessionCaps[key];
+    const enabled = own(XenonCapabilityManager_1.XENON_CAPABILITIES.INTERCEPTOR_ENABLED);
+    const bufferSize = own(XenonCapabilityManager_1.XENON_CAPABILITIES.INTERCEPTOR_BUFFER_SIZE);
+    const captureBodies = own(XenonCapabilityManager_1.XENON_CAPABILITIES.INTERCEPTOR_CAPTURE_BODIES);
+    return {
+        enabled: typeof enabled === 'boolean' ? enabled : (server === null || server === void 0 ? void 0 : server.enabled) === true,
+        bufferSize: (_a = positive(bufferSize)) !== null && _a !== void 0 ? _a : positive(server === null || server === void 0 ? void 0 : server.bufferSize),
+        captureBodies: typeof captureBodies === 'boolean'
+            ? captureBodies
+            : typeof (server === null || server === void 0 ? void 0 : server.captureBodies) === 'boolean'
+                ? server.captureBodies
+                : true,
+        mocks: listOr(own(XenonCapabilityManager_1.XENON_CAPABILITIES.INTERCEPTOR_MOCKS)),
+        includeHosts: listOr(own(XenonCapabilityManager_1.XENON_CAPABILITIES.INTERCEPTOR_INCLUDE_HOSTS)),
+        excludeHosts: listOr(own(XenonCapabilityManager_1.XENON_CAPABILITIES.INTERCEPTOR_EXCLUDE_HOSTS)),
+    };
+}
+function positive(value) {
+    const n = typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+    return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;
+}
+function listOr(value) {
+    return Array.isArray(value) ? value : [];
+}