@xenon-device-management/xenon 1.1.0

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

@@ -0,0 +1,333 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FuzzyXmlHealingProvider = void 0;
+const types_1 = require("./types");
+// @ts-ignore
+const xmldom_1 = require("xmldom");
+// @ts-ignore
+const xpath_1 = require("xpath");
+const typedi_1 = require("typedi");
+const logger_1 = __importDefault(require("../../logger"));
+const HealedLocatorGenerator_1 = require("./HealedLocatorGenerator");
+class FuzzyXmlHealingProvider {
+    constructor(etalonService) {
+        this.etalonService = etalonService;
+        this.name = 'Fuzzy XML Provider';
+        this.tier = types_1.HealingTier.TIER_2_FUZZY_XML;
+        this.logger = logger_1.default.scope('FuzzyXmlHealing');
+        this.generator = typedi_1.Container.get(HealedLocatorGenerator_1.HealedLocatorGenerator);
+    }
+    heal(context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!context.pageSource) {
+                this.logger.debug('No page source available for fuzzy matching');
+                return null;
+            }
+            try {
+                const dom = new xmldom_1.DOMParser().parseFromString(context.pageSource);
+                // TIER 2+ Optimization: Use Baseline Signature if available
+                let etalon = null;
+                if (this.etalonService) {
+                    etalon = yield this.etalonService.getSignature(context.selector);
+                }
+                const keywords = this.extractKeywords(context.selector);
+                if (keywords.length === 0 && !etalon)
+                    return null;
+                if (etalon) {
+                    this.logger.info('Baseline signature found for locator. Using weighted recovery...');
+                }
+                else {
+                    this.logger.info(`No baseline found. Attempting fuzzy match for keywords: ${keywords.join(', ')}`);
+                }
+                // Find all elements with text or attributes matching keywords or etalon
+                const nodes = (0, xpath_1.select)('//*', dom);
+                let bestMatch = null;
+                let highestScore = 0;
+                for (const node of nodes) {
+                    const score = this.calculateScore(node, keywords, etalon);
+                    if (score > highestScore && score > 0.5) {
+                        // Threshold 50% for POC robustness
+                        highestScore = score;
+                        bestMatch = node;
+                    }
+                }
+                if (bestMatch) {
+                    const candidateLocators = this.generator.generate(bestMatch);
+                    // Also add the absolute XPath as the ultimate fallback
+                    const absXpath = this.getAbsoluteXpath(bestMatch);
+                    if (!candidateLocators.includes(absXpath)) {
+                        candidateLocators.push(absXpath);
+                    }
+                    this.logger.info(`✅ Found fuzzy match with score ${highestScore.toFixed(2)}. Trying ${candidateLocators.length} candidate locators...`);
+                    // Try ALL candidate locators until one actually resolves
+                    for (const candidateXpath of candidateLocators) {
+                        try {
+                            this.logger.debug(`  Trying candidate: ${candidateXpath}`);
+                            const element = yield context.driver.findElement('xpath', candidateXpath);
+                            const elementId = element.ELEMENT || element['element-6066-11e4-a52e-4f735466cecf'];
+                            if (elementId) {
+                                this.logger.info(`🎯 Resolved via candidate: ${candidateXpath}`);
+                                return {
+                                    id: elementId,
+                                    tier: this.tier,
+                                    confidence: highestScore,
+                                    originalSelector: context.selector,
+                                    recommendedSelector: candidateXpath,
+                                    candidateSelectors: candidateLocators,
+                                    node: bestMatch,
+                                    message: `Found element via fuzzy matching (${(highestScore * 100).toFixed(0)}% confidence). Healed locator: ${candidateXpath}`,
+                                };
+                            }
+                        }
+                        catch (err) {
+                            this.logger.debug(`  Candidate failed: ${candidateXpath}`);
+                        }
+                    }
+                    this.logger.warn(`All ${candidateLocators.length} candidate locators failed to resolve for fuzzy match.`);
+                }
+            }
+            catch (err) {
+                this.logger.error(`Error during fuzzy healing: ${err.message}`);
+            }
+            return null;
+        });
+    }
+    extractKeywords(selector) {
+        // Extract words from selector, ignoring XPath syntax and common keywords
+        const blacklist = ['and', 'or', 'text', 'contains', 'xpath', 'element'];
+        const cleaned = selector.replace(/[\/\@\[\]\=\'\"]/g, ' ');
+        return cleaned.split(/\s+/).filter((s) => s.length > 2 && !blacklist.includes(s.toLowerCase()));
+    }
+    calculateScore(node, keywords, etalon = null) {
+        const ANCHORS = {
+            'content-desc': 2.0, // Android
+            'resource-id': 1.5, // Android/iOS
+            'accessibility-id': 2.0, // iOS
+            label: 1.5, // iOS
+            name: 1.5, // iOS — elevated: @name is the primary iOS identifier
+            id: 1.0, // Android
+            hint: 0.4, // Android
+            value: 0.5, // iOS
+        };
+        const nodeAttrs = node.attributes || [];
+        let totalScore = 0;
+        let totalWeight = 0;
+        // === CRITICAL GATE: Tag Name Match ===
+        // When we have a baseline etalon, we KNOW the exact element type.
+        // XCUIElementTypeButton should NEVER match XCUIElementTypeImage or XCUIElementTypeApplication.
+        if (etalon) {
+            const etalonTag = etalon.nodeName.toLowerCase();
+            const nodeTag = node.nodeName.toLowerCase();
+            // Exact match required when etalon is present (no fuzzy allowed for tag)
+            if (etalonTag !== nodeTag && etalonTag !== 'xcuielementtypeany' && etalonTag !== 'unknown') {
+                return 0; // Immediate rejection — wrong element type
+            }
+            // Tag matches perfectly
+            totalWeight += 1.0;
+            totalScore += 1.0;
+        }
+        else {
+            // No etalon: use fuzzy tag matching with keywords
+            const tagWeight = 0.5;
+            const tagSim = this.getBestSimilarity(node.nodeName, keywords);
+            totalWeight += tagWeight;
+            totalScore += tagSim * tagWeight;
+        }
+        // === 2. Semantic Text Matching ===
+        // Check text content and text-like attributes against baseline or keywords
+        const textWeight = etalon ? 0.5 : 1.0;
+        const textTargets = etalon
+            ? [etalon.attributes['text'], etalon.attributes['label'], etalon.attributes['name']].filter(Boolean)
+            : keywords;
+        let bestTextSim = 0;
+        if (textTargets.length > 0) {
+            bestTextSim = this.getBestSimilarity(node.textContent || '', textTargets);
+            // Also check text-like attributes: name, label, text, value
+            for (const attrName of ['text', 'name', 'label', 'value']) {
+                const attrVal = this.getAttrValue(node, attrName);
+                if (attrVal) {
+                    const sim = this.getBestSimilarity(attrVal, textTargets);
+                    if (sim > bestTextSim)
+                        bestTextSim = sim;
+                }
+            }
+        }
+        totalWeight += textWeight;
+        totalScore += bestTextSim * textWeight;
+        // === 3. Anchor Attribute Matching ===
+        for (let i = 0; i < nodeAttrs.length; i++) {
+            const attr = nodeAttrs[i];
+            const attrName = attr.name.toLowerCase();
+            // Skip non-anchor, spatial, and already-handled attrs
+            if ([
+                'x',
+                'y',
+                'width',
+                'height',
+                'text',
+                'type',
+                'enabled',
+                'visible',
+                'accessible',
+                'index',
+                'traits',
+                'processId',
+                'bundleId',
+            ].includes(attrName))
+                continue;
+            if (ANCHORS[attrName]) {
+                const weight = ANCHORS[attrName];
+                const etalonValue = etalon === null || etalon === void 0 ? void 0 : etalon.attributes[attrName];
+                const target = etalonValue ? [etalonValue] : keywords;
+                let sim = this.getBestSimilarity(attr.value, target);
+                // Exact match with etalon gets perfect score
+                if (etalonValue && attr.value === etalonValue) {
+                    sim = 1.0;
+                }
+                totalWeight += weight;
+                totalScore += sim * weight;
+            }
+        }
+        // === 4. SPATIAL MATCHING: The Decisive Signal ===
+        // When the etalon has X/Y coordinates, position is the STRONGEST signal.
+        // Elements rarely move on screen; text/names change far more often.
+        if (etalon && etalon.attributes['x'] !== undefined) {
+            const spatialWeight = 5.0; // Very high — position is king
+            let spatialScore = 0;
+            const ex = parseInt(etalon.attributes['x']);
+            const ey = parseInt(etalon.attributes['y']);
+            // Get candidate node coordinates — handle both iOS and Android formats
+            let nx = -999;
+            let ny = -999;
+            // iOS format: separate x, y attributes
+            const iosX = this.getAttrValue(node, 'x');
+            const iosY = this.getAttrValue(node, 'y');
+            if (iosX !== null && iosY !== null) {
+                nx = parseInt(iosX);
+                ny = parseInt(iosY);
+            }
+            else {
+                // Android format: bounds="[x1,y1][x2,y2]" — compute top-left (matches getElementRect)
+                const bounds = this.getAttrValue(node, 'bounds');
+                if (bounds) {
+                    const match = bounds.match(/\[(\d+),(\d+)\]\[(\d+),(\d+)\]/);
+                    if (match) {
+                        nx = parseInt(match[1]); // x1 (left)
+                        ny = parseInt(match[2]); // y1 (top)
+                    }
+                }
+            }
+            if (nx !== -999 && ny !== -999) {
+                const dist = Math.sqrt(Math.pow(ex - nx, 2) + Math.pow(ey - ny, 2));
+                if (dist < 5) {
+                    spatialScore = 1.0; // Near-perfect position match
+                }
+                else if (dist < 20) {
+                    spatialScore = 0.85; // Very close
+                }
+                else if (dist < 50) {
+                    spatialScore = 0.5; // Same general area
+                }
+                else if (dist < 100) {
+                    spatialScore = 0.2; // Nearby
+                }
+                // > 100px: no spatial score
+            }
+            totalWeight += spatialWeight;
+            totalScore += spatialScore * spatialWeight;
+        }
+        const finalScore = totalWeight > 0 ? totalScore / totalWeight : 0;
+        // Diagnostic logging for debugging
+        if (finalScore > 0.3) {
+            this.logger.debug(`Score [${node.nodeName}]: final=${finalScore.toFixed(2)} ` +
+                `(total=${totalScore.toFixed(2)}/${totalWeight.toFixed(1)}) ` +
+                `name=${this.getAttrValue(node, 'name') || '-'} ` +
+                `label=${this.getAttrValue(node, 'label') || '-'} ` +
+                `X=${this.getAttrValue(node, 'x')},Y=${this.getAttrValue(node, 'y')}`);
+        }
+        return finalScore;
+    }
+    getAttrValue(node, name) {
+        if (typeof node.getAttribute === 'function') {
+            const val = node.getAttribute(name);
+            if (val)
+                return val;
+        }
+        const nodeAttrs = node.attributes || [];
+        for (let i = 0; i < nodeAttrs.length; i++) {
+            if (nodeAttrs[i].name.toLowerCase() === name)
+                return nodeAttrs[i].value;
+        }
+        return null;
+    }
+    getBestSimilarity(value, keywords) {
+        const lowerValue = (value || '').toLowerCase().trim();
+        if (!lowerValue)
+            return 0;
+        let best = 0;
+        for (const word of keywords) {
+            const lowerWord = word.toLowerCase().trim();
+            const sim = this.stringSimilarity(lowerValue, lowerWord);
+            if (sim > best)
+                best = sim;
+            // Bonus for exact containment or very high similarity
+            if (lowerValue.includes(lowerWord) && best < 0.7)
+                best = 0.7;
+        }
+        return best;
+    }
+    stringSimilarity(str1, str2) {
+        const s1 = str1.toLowerCase().trim();
+        const s2 = str2.toLowerCase().trim();
+        if (s1 === s2)
+            return 1;
+        // Simple overlap for very short strings
+        if (s1.length < 2 || s2.length < 2)
+            return s1.includes(s2) || s2.includes(s1) ? 0.7 : 0;
+        const bigrams1 = new Set();
+        for (let i = 0; i < s1.length - 1; i++)
+            bigrams1.add(s1.substring(i, i + 2));
+        const bigrams2 = new Set();
+        for (let i = 0; i < s2.length - 1; i++)
+            bigrams2.add(s2.substring(i, i + 2));
+        let intersection = 0;
+        for (const b of bigrams1) {
+            if (bigrams2.has(b))
+                intersection++;
+        }
+        return (2 * intersection) / (bigrams1.size + bigrams2.size);
+    }
+    getAbsoluteXpath(node) {
+        const parts = [];
+        let current = node;
+        while (current && current.nodeType === 1) {
+            // Node.ELEMENT_NODE
+            let index = 0;
+            let sibling = current.previousSibling;
+            while (sibling) {
+                if (sibling.nodeType === 1 && sibling.nodeName === current.nodeName) {
+                    index++;
+                }
+                sibling = sibling.previousSibling;
+            }
+            const tagName = current.nodeName;
+            const pathIndex = index > 0 ? `[${index + 1}]` : '';
+            parts.unshift(`${tagName}${pathIndex}`);
+            current = current.parentNode;
+        }
+        return `/${parts.join('/')}`;
+    }
+}
+exports.FuzzyXmlHealingProvider = FuzzyXmlHealingProvider;

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

@@ -0,0 +1,98 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealEtalonService = void 0;
+const typedi_1 = require("typedi");
+const device_store_1 = require("../../data-service/device-store");
+const logger_1 = __importDefault(require("../../logger"));
+let HealEtalonService = class HealEtalonService {
+    constructor() {
+        this.logger = logger_1.default.scope('HealEtalonService');
+        this.store = device_store_1.DeviceStoreFactory.getHealEtalonStore();
+    }
+    /**
+     * Saves or updates a signature for a successful locator
+     */
+    saveSignature(strategy, selector, node, path) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const attributes = {};
+                // Extract identifying attributes
+                const nodeAttrs = node.attributes || [];
+                const anchorNames = [
+                    'content-desc',
+                    'resource-id',
+                    'text',
+                    'name',
+                    'id',
+                    'hint',
+                    'label',
+                    'accessibility-id',
+                    'value',
+                    'x',
+                    'y',
+                    'width',
+                    'height',
+                ];
+                for (let i = 0; i < nodeAttrs.length; i++) {
+                    const attr = nodeAttrs[i];
+                    if (anchorNames.includes(attr.name.toLowerCase())) {
+                        attributes[attr.name.toLowerCase()] = attr.value;
+                    }
+                }
+                const signature = {
+                    selector,
+                    strategy,
+                    attributes,
+                    nodeName: node.nodeName || 'Unknown',
+                    path,
+                    lastSeen: Date.now(),
+                };
+                yield this.store.saveSignature(signature);
+                this.logger.debug(`Saved signature for locator: ${selector}`);
+            }
+            catch (err) {
+                this.logger.error(`Failed to save signature: ${err.message}`);
+            }
+        });
+    }
+    /**
+     * Retrieves a signature for a locator
+     */
+    getSignature(selector) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield this.store.getSignature(selector);
+            }
+            catch (err) {
+                this.logger.error(`Failed to retrieve signature: ${err.message}`);
+                return null;
+            }
+        });
+    }
+};
+exports.HealEtalonService = HealEtalonService;
+exports.HealEtalonService = HealEtalonService = __decorate([
+    (0, typedi_1.Service)(),
+    __metadata("design:paramtypes", [])
+], HealEtalonService);

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

@@ -0,0 +1,132 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealedLocatorGenerator = void 0;
+const typedi_1 = require("typedi");
+const logger_1 = __importDefault(require("../../logger"));
+let HealedLocatorGenerator = class HealedLocatorGenerator {
+    constructor() {
+        this.logger = logger_1.default.scope('LocatorGenerator');
+    }
+    /**
+     * Generates a set of candidate locators for a healed node, ranked by stability.
+     */
+    generate(node) {
+        const candidates = [];
+        const tagName = node.nodeName || node.tag;
+        if (!tagName)
+            return [];
+        const attrs = {};
+        if (node.attributes) {
+            for (let i = 0; i < node.attributes.length; i++) {
+                const attr = node.attributes[i];
+                attrs[attr.name.toLowerCase()] = attr.value;
+            }
+        }
+        else if (node.attrs) {
+            // Handle ResilioTree node format if different
+            Object.assign(attrs, node.attrs);
+        }
+        // 1. Name attribute (maps to accessibilityIdentifier on iOS — THE most reliable iOS locator)
+        if (attrs['name']) {
+            candidates.push(`//${tagName}[@name='${attrs['name']}']`);
+            candidates.push(`//*[@name='${attrs['name']}']`);
+        }
+        // 2. Label attribute (maps to accessibilityLabel on iOS — stable and user-visible)
+        if (attrs['label']) {
+            candidates.push(`//${tagName}[@label='${attrs['label']}']`);
+            candidates.push(`//*[@label='${attrs['label']}']`);
+        }
+        // 3. Content-Desc (Very stable in Android)
+        if (attrs['content-desc']) {
+            candidates.push(`//*[contains(@content-desc, '${attrs['content-desc']}')]`);
+            candidates.push(`//${tagName}[@content-desc='${attrs['content-desc']}']`);
+        }
+        // 4. Resource-ID (Stable in Android)
+        if (attrs['resource-id']) {
+            candidates.push(`//*[@resource-id='${attrs['resource-id']}']`);
+        }
+        // 5. Value attribute (iOS form elements)
+        if (attrs['value'] && attrs['value'].length > 1 && attrs['value'].length < 80) {
+            candidates.push(`//${tagName}[@value='${attrs['value']}']`);
+        }
+        // 6. Text content — NOTE: @text does NOT work in WDA/XCUITest XPath!
+        // Use it only as a contains() match for Android, never as a primary iOS locator.
+        const textValue = attrs['text'];
+        if (textValue && textValue.length > 2 && textValue.length < 50) {
+            // For Android only — iOS should be handled by @name and @label above
+            candidates.push(`//${tagName}[@text='${textValue}']`);
+            candidates.push(`//*[contains(@text, '${textValue}')]`);
+        }
+        // 7. Accessibility ID (used in Appium, may differ from @name)
+        if (attrs['accessibility-id']) {
+            candidates.push(`//${tagName}[@accessibility-id='${attrs['accessibility-id']}']`);
+            candidates.push(`//*[@accessibility-id='${attrs['accessibility-id']}']`);
+        }
+        // 8. Parent-Relative
+        const parent = node.parentNode || node.parent;
+        if (parent) {
+            const parentTag = parent.nodeName || parent.tag;
+            const parentResourceId = (parent.attributes && this.getAttr(parent, 'resource-id')) ||
+                (parent.attrs && parent.attrs['resource-id']);
+            const parentName = (parent.attributes && this.getAttr(parent, 'name')) ||
+                (parent.attrs && parent.attrs['name']);
+            if (parentResourceId) {
+                candidates.push(`//*[@resource-id='${parentResourceId}']//${tagName}`);
+            }
+            else if (parentName && parentName.length < 80) {
+                candidates.push(`//*[@name='${parentName}']//${tagName}`);
+            }
+            else if (parentTag && parentTag !== 'HTML' && parentTag !== 'BODY') {
+                candidates.push(`//${parentTag}//${tagName}`);
+            }
+        }
+        // 6. Absolute XPath (Fallback)
+        candidates.push(this.generateAbsoluteXpath(node));
+        // Return unique non-empty candidates
+        return [...new Set(candidates)].filter(Boolean);
+    }
+    getAttr(node, name) {
+        if (!node.attributes)
+            return null;
+        for (let i = 0; i < node.attributes.length; i++) {
+            if (node.attributes[i].name.toLowerCase() === name)
+                return node.attributes[i].value;
+        }
+        return null;
+    }
+    generateAbsoluteXpath(node) {
+        const parts = [];
+        let current = node;
+        while (current && current.nodeType === 1) {
+            let index = 0;
+            let sibling = current.previousSibling;
+            while (sibling) {
+                if (sibling.nodeType === 1 && sibling.nodeName === current.nodeName) {
+                    index++;
+                }
+                sibling = sibling.previousSibling;
+            }
+            const tag = current.nodeName || current.tag;
+            // Skip wrapper tags for cleaner XPath
+            if (tag.toLowerCase() !== 'html' && tag.toLowerCase() !== 'body') {
+                const pathIndex = index > 0 ? `[${index + 1}]` : '';
+                parts.unshift(`${tag}${pathIndex}`);
+            }
+            current = current.parentNode || current.parent;
+        }
+        return `/${parts.join('/')}`;
+    }
+};
+exports.HealedLocatorGenerator = HealedLocatorGenerator;
+exports.HealedLocatorGenerator = HealedLocatorGenerator = __decorate([
+    (0, typedi_1.Service)()
+], HealedLocatorGenerator);