@xenon-device-management/xenon 1.17.4 → 1.18.0

package/lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xenon-device-management/xenon",
-    "version": "1.17.4",
+    "version": "1.18.0",
     "description": "Xenon - Intelligent Mobile Infrastructure. A self-healing device orchestration platform for Appium.",
     "main": "./lib/src/index.js",
     "exports": {

package/lib/src/device-managers/ios/IOSStreamService.js

@@ -692,6 +692,12 @@ let IOSStreamService = class IOSStreamService {
                     if (!fs_extra_1.default.existsSync(logDir))
                         fs_extra_1.default.mkdirSync(logDir);
                     const wdaRunLog = path_1.default.join(logDir, `runwda-${udid}.log`);
+                    // Truncated per run, because this file is also the evidence the failure
+                    // is classified from. Appending across runs meant a "Did not find test
+                    // app" line from a day earlier was still matched today, so every later
+                    // failure of any kind — including one where WDA was demonstrably
+                    // installed — was reported as "WebDriverAgent is not installed".
+                    fs_extra_1.default.writeFileSync(wdaRunLog, '');
                     (_a = session.wdaProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (d) => fs_extra_1.default.appendFileSync(wdaRunLog, d));
                     (_b = session.wdaProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (d) => fs_extra_1.default.appendFileSync(wdaRunLog, d));
                     // 4. Wait for WDA to be ready
@@ -770,11 +776,16 @@ let IOSStreamService = class IOSStreamService {
                         }
                         if (((_c = session.wdaProcess) === null || _c === void 0 ? void 0 : _c.exitCode) !== null) {
                             const logContent = fs_extra_1.default.existsSync(wdaRunLog) ? fs_extra_1.default.readFileSync(wdaRunLog, 'utf8') : '';
-                            // Missing WDA is permanent until the app is installed — surface an
-                            // actionable reason instead of a raw exit code + log tail.
+                            // Both of these are permanent until a human acts, and they call for
+                            // opposite actions — install the app, versus trust the app that is
+                            // already installed. Surface which, rather than a raw exit code and
+                            // a log tail.
                             if ((0, iosStreamDiagnostics_1.isMissingWdaError)(logContent)) {
                                 throw new Error((0, iosStreamDiagnostics_1.missingWdaMessage)(udid));
                             }
+                            if ((0, iosStreamDiagnostics_1.isWdaLaunchFailure)(logContent)) {
+                                throw new Error((0, iosStreamDiagnostics_1.wdaLaunchFailureMessage)(udid));
+                            }
                             throw new Error(`WDA process exited with code ${(_d = session.wdaProcess) === null || _d === void 0 ? void 0 : _d.exitCode}. Log: ${logContent.slice(-200)}`);
                         }
                         yield new Promise((resolve) => setTimeout(resolve, 1000));

package/lib/src/device-managers/ios/iosStreamDiagnostics.js

@@ -9,6 +9,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMissingWdaError = isMissingWdaError;
 exports.missingWdaMessage = missingWdaMessage;
+exports.isWdaLaunchFailure = isWdaLaunchFailure;
+exports.wdaLaunchFailureMessage = wdaLaunchFailureMessage;
 exports.classifyTunnelStderr = classifyTunnelStderr;
 exports.isOwnStreamProcess = isOwnStreamProcess;
 /**
@@ -27,6 +29,34 @@ function missingWdaMessage(udid) {
     return (`WebDriverAgent is not installed on ${udid}. ` +
         `Live streaming requires the WebDriverAgentRunner app — install WDA on this device to enable the mirror.`);
 }
+/**
+ * True when WDA is installed but the runner could not be *started*.
+ *
+ * go-ios reports the two conditions quite differently, and conflating them
+ * sends people to reinstall an app that is already there:
+ *
+ *   missing:  cannot get test app information: Did not find test app for '…'
+ *   present:  cannot start test runner: LaunchAppWithStdIo: failed to launch
+ *             app: launchApp: failed to get PID
+ *
+ * The second is nearly always the device refusing to run the binary — an
+ * untrusted developer certificate, a locked screen, or a lapsed signature —
+ * none of which reinstalling addresses on its own.
+ */
+function isWdaLaunchFailure(logContent) {
+    if (!logContent)
+        return false;
+    return (/failed to launch app/i.test(logContent) ||
+        /LaunchAppWithStdIo/i.test(logContent) ||
+        /cannot start test runner/i.test(logContent));
+}
+/** Human-facing, actionable message for the installed-but-unlaunchable case. */
+function wdaLaunchFailureMessage(udid) {
+    return (`WebDriverAgent is installed on ${udid} but would not start. ` +
+        `This is usually the device refusing to run it: trust the developer certificate under ` +
+        `Settings → General → VPN & Device Management, unlock the screen, and check the signing ` +
+        `profile has not expired. Launching WebDriverAgentRunner once by hand confirms it.`);
+}
 /**
  * Classify a chunk of go-ios `tunnel start` stderr.
  *

package/lib/src/services/InspectorService.js

@@ -432,28 +432,46 @@ let InspectorService = class InspectorService {
                 score: 95,
             });
         }
+        // On iOS `node.text` is `label || value`, so every locator that selects on
+        // it — predicate and xpath alike — has to name whichever of the two
+        // actually supplied it. Hardcoding `label` sends a page indicator, whose
+        // text lives in `value`, to a predicate that matches nothing.
+        const iosTextAttr = asText(node.attributes.label) === node.text ? 'label' : 'value';
         // 3. Platform Specific - Performance Tier
         if (platform === 'ios') {
             // iOS Predicate String - High Performance
-            const predicate = `type == "${node.type}" AND label == "${node.text || node.label || ''}"`;
+            const predicateValue = node.text || node.label || '';
             if (node.text || node.label) {
                 suggestions.push({
                     strategy: '-ios predicate string',
-                    value: predicate,
-                    unique: true,
+                    value: `type == "${node.type}" AND ${iosTextAttr} == "${predicateValue}"`,
+                    // A compound predicate is at least as selective as its label term, so
+                    // a unique label makes it unique. The converse does not hold — two
+                    // elements sharing a label may differ by type — which makes this
+                    // conservative rather than exact, and that is the right direction:
+                    // it was previously hardcoded true, and a predicate badged unique
+                    // was measured against a real device matching two elements.
+                    unique: this.isUnique(uniqueness, 'text', predicateValue),
                     score: 90,
                 });
             }
             // iOS Class Chain - High Precision
-            const classChain = `**/${node.type}[` +
-                (node.attributes.name
-                    ? `name == "${node.attributes.name}"`
-                    : `label == "${node.text || ''}"`) +
-                ']';
+            //
+            // The predicate MUST be wrapped in backticks. Without them Appium
+            // resolves nothing at all: measured against a real iPhone,
+            // `**/XCUIElementTypePageIndicator[name == "Page control"]` found 0
+            // elements and the same chain with backticks found 1. Every class chain
+            // this service produced was unusable, and each was badged unique — 280
+            // of them in a single snapshot of a home screen.
+            const chainValue = node.attributes.name ? String(node.attributes.name) : node.text || '';
+            const chainTerm = node.attributes.name ? 'name' : 'label';
             suggestions.push({
                 strategy: '-ios class chain',
-                value: classChain,
-                unique: true,
+                value: `**/${node.type}[\`${chainTerm} == "${chainValue}"\`]`,
+                // Same index the accessibility-id suggestion uses, and the same value:
+                // a node's identity there is `name || label`, which is exactly what
+                // the chain selects on.
+                unique: this.isUnique(uniqueness, 'accessibility id', chainValue),
                 score: 85,
             });
         }
@@ -495,9 +513,15 @@ let InspectorService = class InspectorService {
             });
         }
         else if (node.text) {
+            // `@text` is an Android attribute. An XCUIElement has name, label and
+            // value and no text at all, so every iOS suggestion in this shape
+            // resolved to nothing: measured on a real iPhone,
+            // `//XCUIElementTypePageIndicator[@text="Page control"]` found 0 and the
+            // same path with `@label` found 1.
+            const textAttr = platform === 'ios' ? iosTextAttr : 'text';
             suggestions.push({
                 strategy: 'xpath',
-                value: `//${tagName}[@text="${node.text}"]`,
+                value: `//${tagName}[@${textAttr}="${node.text}"]`,
                 unique: this.isUnique(uniqueness, 'text', node.text),
                 score: 60,
             });

package/lib/test/unit/inspector-hierarchy.spec.js

@@ -197,6 +197,61 @@ describe('InspectorService hierarchy parsing', () => {
             (0, chai_1.expect)(root.name).to.equal('1');
         });
     });
+    describe('iOS locator syntax', () => {
+        // Two StaticTexts share the label "Done" and neither has a name, so both a
+        // predicate and a class chain built from that label are genuinely
+        // ambiguous. The button carries a name and is genuinely unique. The text
+        // field has a value and no label.
+        const XML = `<AppiumAUT>
+      <XCUIElementTypeApplication type="XCUIElementTypeApplication" name="MyApp" label="MyApp" x="0" y="0" width="390" height="844">
+        <XCUIElementTypeButton type="XCUIElementTypeButton" name="done-btn" label="Save" x="0" y="0" width="10" height="10" />
+        <XCUIElementTypeStaticText type="XCUIElementTypeStaticText" label="Done" x="0" y="20" width="10" height="10" />
+        <XCUIElementTypeStaticText type="XCUIElementTypeStaticText" label="Done" x="0" y="30" width="10" height="10" />
+        <XCUIElementTypeTextField type="XCUIElementTypeTextField" value="typed text" x="0" y="40" width="10" height="10" />
+      </XCUIElementTypeApplication>
+    </AppiumAUT>`;
+        const root = () => parse(XML, 'ios');
+        const byType = (t) => find(root(), (n) => n.type === t)[0];
+        it('wraps the class chain predicate in backticks', () => {
+            // Measured on a real iPhone: without backticks Appium resolves 0
+            // elements, with them it resolves 1. Every chain this produced was
+            // unusable — 280 of them in one home-screen snapshot.
+            (0, chai_1.expect)(locator(byType('XCUIElementTypeButton'), '-ios class chain').value).to.equal('**/XCUIElementTypeButton[`name == "done-btn"`]');
+        });
+        it('selects on label in the class chain when there is no name', () => {
+            (0, chai_1.expect)(locator(byType('XCUIElementTypeStaticText'), '-ios class chain').value).to.equal('**/XCUIElementTypeStaticText[`label == "Done"`]');
+        });
+        it('uses an attribute an XCUIElement actually has in xpath', () => {
+            // `@text` is Android's. iOS has name, label and value — and `@text`
+            // resolved to nothing on a real device.
+            const xpath = locator(byType('XCUIElementTypeStaticText'), 'xpath').value;
+            (0, chai_1.expect)(xpath).to.equal('//XCUIElementTypeStaticText[@label="Done"]');
+            (0, chai_1.expect)(xpath).to.not.contain('@text');
+        });
+        it('names value rather than label when value is what supplied the text', () => {
+            (0, chai_1.expect)(locator(byType('XCUIElementTypeTextField'), 'xpath').value).to.equal('//XCUIElementTypeTextField[@value="typed text"]');
+        });
+        it('names the same attribute in the predicate as in the xpath', () => {
+            // A page indicator carries its text in `value` and has no label at all.
+            // The predicate hardcoded `label ==`, so it matched nothing — measured
+            // against a real iPhone as the last surviving miss after the other
+            // fixes landed.
+            const field = byType('XCUIElementTypeTextField');
+            (0, chai_1.expect)(locator(field, '-ios predicate string').value).to.equal('type == "XCUIElementTypeTextField" AND value == "typed text"');
+            (0, chai_1.expect)(locator(byType('XCUIElementTypeStaticText'), '-ios predicate string').value).to.equal('type == "XCUIElementTypeStaticText" AND label == "Done"');
+        });
+        it('stops claiming every predicate and class chain is unique', () => {
+            // Both were hardcoded true. On a real device a predicate badged unique
+            // matched two elements.
+            const shared = byType('XCUIElementTypeStaticText'); // label "Done", shared
+            (0, chai_1.expect)(locator(shared, '-ios predicate string').unique).to.equal(false);
+            (0, chai_1.expect)(locator(shared, '-ios class chain').unique).to.equal(false);
+        });
+        it('still reports a genuinely unique one as unique', () => {
+            const named = byType('XCUIElementTypeButton'); // name "done-btn", unique
+            (0, chai_1.expect)(locator(named, '-ios class chain').unique).to.equal(true);
+        });
+    });
     describe('iOS', () => {
         it('parses the XCUIElementType tree unchanged', () => {
             const root = parse(IOS_XML, 'ios');

package/lib/test/unit/iosStreamDiagnostics.spec.js

@@ -2,6 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const chai_1 = require("chai");
 const iosStreamDiagnostics_1 = require("../../src/device-managers/ios/iosStreamDiagnostics");
+/**
+ * Both verbatim from a real go-ios run log, and the whole point is that they
+ * mean opposite things: reinstall the app, versus trust the app that is
+ * already installed.
+ */
+const GO_IOS_MISSING = `{"level":"ERROR","msg":"Failed running WDA","error":"runXUITestWithBundleIdsXcode15Ctx: ` +
+    `cannot get test app information: Did not find test app for ` +
+    `'com.qasecret.WebDriverAgentRunner.xctrunner' on device. Is it installed?"}`;
+const GO_IOS_WONT_LAUNCH = `{"level":"ERROR","msg":"Failed running WDA","error":"runXUITestWithBundleIdsXcode15Ctx: ` +
+    `cannot start test runner: LaunchAppWithStdIo: failed to launch app: launchApp: ` +
+    `failed to get PID: pidFromResponse: could not get pid"}`;
 describe('iosStreamDiagnostics', () => {
     describe('isMissingWdaError', () => {
         it('detects the go-ios "Did not find test app" WDA crash', () => {
@@ -25,6 +36,44 @@ describe('iosStreamDiagnostics', () => {
             (0, chai_1.expect)(msg.toLowerCase()).to.contain('install');
         });
     });
+    describe('telling "not installed" apart from "would not start"', () => {
+        it('reads the real missing-app log as missing', () => {
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isMissingWdaError)(GO_IOS_MISSING)).to.equal(true);
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isWdaLaunchFailure)(GO_IOS_MISSING)).to.equal(false);
+        });
+        it('reads the real launch-failure log as a launch failure, not as missing', () => {
+            // This is the one that was reported as "WebDriverAgent is not installed"
+            // against a device where it demonstrably was installed, sending the
+            // reader off to reinstall an app that was already there.
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isWdaLaunchFailure)(GO_IOS_WONT_LAUNCH)).to.equal(true);
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isMissingWdaError)(GO_IOS_WONT_LAUNCH)).to.equal(false);
+        });
+        it('gives the two cases opposite advice', () => {
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.missingWdaMessage)('udid-1')).to.contain('not installed');
+            const launch = (0, iosStreamDiagnostics_1.wdaLaunchFailureMessage)('udid-1');
+            (0, chai_1.expect)(launch).to.contain('is installed');
+            (0, chai_1.expect)(launch).to.contain('VPN & Device Management');
+            (0, chai_1.expect)(launch).to.not.contain('not installed');
+        });
+        it('is safe on empty input', () => {
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isWdaLaunchFailure)('')).to.equal(false);
+        });
+        it('is why the run log must be truncated per run', () => {
+            // These classifiers read a file, and the file used to be appended to
+            // across runs. A stale "Did not find test app" from a previous day still
+            // wins over today's launch failure — which is exactly how an installed
+            // WDA came to be reported as missing. IOSStreamService now empties the
+            // log before each spawn; this pins what happens if it stops.
+            const stale = `${GO_IOS_MISSING}\n${GO_IOS_WONT_LAUNCH}`;
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isMissingWdaError)(stale)).to.equal(true);
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isWdaLaunchFailure)(stale)).to.equal(true);
+        });
+        it('does not flag an unrelated crash as either', () => {
+            const crash = 'WDA crashed: signal 11 (SIGSEGV)';
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isMissingWdaError)(crash)).to.equal(false);
+            (0, chai_1.expect)((0, iosStreamDiagnostics_1.isWdaLaunchFailure)(crash)).to.equal(false);
+        });
+    });
     describe('classifyTunnelStderr', () => {
         it('extracts the real target udid from the go-ios JSON payload', () => {
             const line = JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenon-device-management/xenon",
-  "version": "1.17.4",
+  "version": "1.18.0",
   "description": "Xenon - Intelligent Mobile Infrastructure. A self-healing device orchestration platform for Appium.",
   "main": "./lib/src/index.js",
   "exports": {