appium-session-recorder 0.0.1

package/src/core/selectors/generate-candidates.ts

@@ -0,0 +1,155 @@
+import type { ParsedElement, Platform, SelectorCandidate } from '../types';
+
+function pushUnique(candidates: SelectorCandidate[], candidate: SelectorCandidate): void {
+    if (!candidate.value) return;
+    if (candidates.some(existing => existing.strategy === candidate.strategy && existing.value === candidate.value)) {
+        return;
+    }
+    candidates.push(candidate);
+}
+
+function escapeDoubleQuoted(value: string): string {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+export function generateSelectorCandidates(element: ParsedElement): SelectorCandidate[] {
+    const candidates: SelectorCandidate[] = [];
+    const platform: Platform = element.platform;
+
+    const primaryAccessibility = element.name || element.label || element.contentDesc;
+    if (primaryAccessibility) {
+        pushUnique(candidates, {
+            strategy: 'accessibility id',
+            value: primaryAccessibility,
+            platform,
+        });
+    }
+
+    if (platform === 'ios') {
+        if (element.label && element.label !== primaryAccessibility) {
+            pushUnique(candidates, {
+                strategy: 'accessibility id',
+                value: element.label,
+                platform,
+            });
+        }
+
+        if (element.name) {
+            pushUnique(candidates, {
+                strategy: '-ios predicate string',
+                value: `name == "${escapeDoubleQuoted(element.name)}"`,
+                platform,
+            });
+            pushUnique(candidates, {
+                strategy: '-ios class chain',
+                value: `**/${element.type}[\`name == "${escapeDoubleQuoted(element.name)}"\`]`,
+                platform,
+            });
+        }
+
+        if (element.label) {
+            pushUnique(candidates, {
+                strategy: '-ios predicate string',
+                value: `label == "${escapeDoubleQuoted(element.label)}"`,
+                platform,
+            });
+        }
+    }
+
+    if (platform === 'android') {
+        if (element.resourceId) {
+            pushUnique(candidates, {
+                strategy: 'id',
+                value: element.resourceId,
+                platform,
+            });
+            pushUnique(candidates, {
+                strategy: '-android uiautomator',
+                value: `new UiSelector().resourceId("${escapeDoubleQuoted(element.resourceId)}")`,
+                platform,
+            });
+        }
+
+        if (element.contentDesc) {
+            pushUnique(candidates, {
+                strategy: 'accessibility id',
+                value: element.contentDesc,
+                platform,
+            });
+            pushUnique(candidates, {
+                strategy: '-android uiautomator',
+                value: `new UiSelector().description("${escapeDoubleQuoted(element.contentDesc)}")`,
+                platform,
+            });
+        }
+
+        if (element.text) {
+            pushUnique(candidates, {
+                strategy: '-android uiautomator',
+                value: `new UiSelector().text("${escapeDoubleQuoted(element.text)}")`,
+                platform,
+            });
+        }
+    }
+
+    if (element.type && (element.name || element.label || element.text)) {
+        const attrName = element.platform === 'android' ? 'text' : 'name';
+        const attrValue = element.platform === 'android' ? element.text || element.label : element.name || element.label;
+        if (attrValue) {
+            pushUnique(candidates, {
+                strategy: 'xpath',
+                value: `//*[@type="${escapeDoubleQuoted(element.type)}" and @${attrName}="${escapeDoubleQuoted(attrValue)}"]`,
+                platform: 'generic',
+            });
+        }
+    }
+
+    pushUnique(candidates, { strategy: 'xpath', value: element.xpath, platform: 'generic' });
+    pushUnique(candidates, { strategy: 'class name', value: element.type, platform: 'generic' });
+
+    return candidates;
+}
+
+export type LegacyLocatorInput = {
+    type: string;
+    name: string;
+    label: string;
+    xpath: string;
+};
+
+export function generateLegacyLocators(element: LegacyLocatorInput): SelectorCandidate[] {
+    const locators: SelectorCandidate[] = [];
+
+    if (element.name) {
+        locators.push({ strategy: 'accessibility id', value: element.name, platform: 'ios' });
+    }
+    if (element.label && element.label !== element.name) {
+        locators.push({ strategy: 'accessibility id', value: element.label, platform: 'ios' });
+    }
+    locators.push({ strategy: 'xpath', value: element.xpath, platform: 'generic' });
+    locators.push({ strategy: 'class name', value: element.type, platform: 'generic' });
+
+    if (element.name) {
+        locators.push({
+            strategy: '-ios predicate string',
+            value: `name == "${escapeDoubleQuoted(element.name)}"`,
+            platform: 'ios',
+        });
+    }
+    if (element.label) {
+        locators.push({
+            strategy: '-ios predicate string',
+            value: `label == "${escapeDoubleQuoted(element.label)}"`,
+            platform: 'ios',
+        });
+    }
+    if (element.name) {
+        locators.push({
+            strategy: '-ios class chain',
+            value: `**/${element.type}[\`name == "${escapeDoubleQuoted(element.name)}"\`]`,
+            platform: 'ios',
+        });
+    }
+
+    return locators;
+}

package/src/core/selectors/score-candidates.ts

@@ -0,0 +1,184 @@
+import type { ParsedElement, RankedSelector, SelectorCandidate, SelectorReason, SelectorStrategy } from '../types';
+
+const baseScoreByStrategy: Record<SelectorStrategy, number> = {
+    id: 100,
+    'accessibility id': 95,
+    '-ios predicate string': 90,
+    '-ios class chain': 85,
+    '-android uiautomator': 85,
+    xpath: 70,
+    'class name': 55,
+};
+
+function isDynamicValue(value: string): boolean {
+    if (/(?:^|[^a-zA-Z])\d{5,}(?:$|[^a-zA-Z])/.test(value)) return true;
+    if (/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}/.test(value)) {
+        return true;
+    }
+    if (/autogen|generated|tmp|temp|anonymous/i.test(value)) return true;
+    return false;
+}
+
+function xpathFragilityPenalty(xpath: string): number {
+    if (!xpath.startsWith('/')) return 0;
+
+    const depth = xpath.split('/').filter(Boolean).length;
+    const indexCount = (xpath.match(/\[\d+\]/g) || []).length;
+
+    let penalty = 0;
+    if (depth > 5) penalty += 8;
+    if (indexCount > 3) penalty += 8;
+
+    return penalty;
+}
+
+function valueEquals(value: string, expected: string): boolean {
+    return value === expected;
+}
+
+function matchIosPredicate(element: ParsedElement, predicate: string): boolean {
+    const equalsMatch = predicate.match(/(name|label|type)\s*==\s*['"](.+?)['"]/i);
+    if (equalsMatch) {
+        const [, field, expected] = equalsMatch;
+        if (field === 'name') return valueEquals(element.name, expected);
+        if (field === 'label') return valueEquals(element.label, expected);
+        return valueEquals(element.type, expected);
+    }
+
+    const containsMatch = predicate.match(/(name|label|type)\s*CONTAINS\s*['"](.+?)['"]/i);
+    if (containsMatch) {
+        const [, field, expected] = containsMatch;
+        if (field === 'name') return element.name.includes(expected);
+        if (field === 'label') return element.label.includes(expected);
+        return element.type.includes(expected);
+    }
+
+    return false;
+}
+
+function matchIosClassChain(element: ParsedElement, classChain: string): boolean {
+    const classChainMatch = classChain.match(/\*\*\/(\w+)(?:\[`(.+?)`\])?/);
+    if (!classChainMatch) return false;
+
+    const targetType = classChainMatch[1];
+    const predicate = classChainMatch[2];
+    if (element.type !== targetType) return false;
+
+    if (!predicate) return true;
+    return matchIosPredicate(element, predicate);
+}
+
+function matchAndroidUiAutomator(element: ParsedElement, value: string): boolean {
+    const matches = [...value.matchAll(/\.(\w+)\("(.+?)"\)/g)];
+    if (matches.length === 0) return false;
+
+    return matches.every(([, method, expected]) => {
+        if (method === 'resourceId') return element.resourceId === expected;
+        if (method === 'description') return element.contentDesc === expected;
+        if (method === 'text') return element.text === expected || element.label === expected;
+        if (method === 'className') return element.type === expected;
+        return false;
+    });
+}
+
+function matchSimpleXPath(element: ParsedElement, xpath: string): boolean {
+    if (xpath === element.xpath) return true;
+
+    const attrMatches = [...xpath.matchAll(/@(\w+)="([^"]+)"/g)];
+    if (attrMatches.length === 0) return false;
+
+    return attrMatches.every(([, attribute, expected]) => {
+        if (attribute === 'type') return element.type === expected;
+        if (attribute === 'name') return element.name === expected;
+        if (attribute === 'label') return element.label === expected;
+        if (attribute === 'text') return element.text === expected;
+        if (attribute === 'resource-id') return element.resourceId === expected;
+        if (attribute === 'content-desc') return element.contentDesc === expected;
+        return element.attributes[attribute] === expected;
+    });
+}
+
+function candidateMatchesElement(candidate: SelectorCandidate, element: ParsedElement): boolean {
+    switch (candidate.strategy) {
+        case 'id':
+            return element.resourceId === candidate.value;
+        case 'accessibility id':
+            return (
+                element.name === candidate.value ||
+                element.label === candidate.value ||
+                element.contentDesc === candidate.value
+            );
+        case 'class name':
+            return element.type === candidate.value;
+        case 'xpath':
+            return matchSimpleXPath(element, candidate.value);
+        case '-ios predicate string':
+            return matchIosPredicate(element, candidate.value);
+        case '-ios class chain':
+            return matchIosClassChain(element, candidate.value);
+        case '-android uiautomator':
+            return matchAndroidUiAutomator(element, candidate.value);
+        default:
+            return false;
+    }
+}
+
+export function rankSelectorCandidates(
+    target: ParsedElement,
+    allElements: ParsedElement[],
+    candidates: SelectorCandidate[],
+): RankedSelector[] {
+    const ranked = candidates.map((candidate) => {
+        const reasons: SelectorReason[] = ['BASE_STRATEGY_PRIORITY'];
+        let score = baseScoreByStrategy[candidate.strategy] ?? 50;
+
+        const matchCount = allElements.filter(element => candidateMatchesElement(candidate, element)).length;
+
+        if (matchCount === 1) {
+            score += 25;
+            reasons.push('UNIQUE_MATCH');
+        } else if (matchCount > 1) {
+            score -= 10;
+            reasons.push('MULTIPLE_MATCHES');
+        } else {
+            score -= 40;
+            reasons.push('NO_MATCH');
+        }
+
+        if (matchCount > 0) {
+            score += 5;
+            reasons.push('VALID_MATCH');
+        }
+
+        if (target.enabled && target.visible && (target.clickable || target.accessible)) {
+            score += 8;
+            reasons.push('ACTIONABLE_ELEMENT_BONUS');
+        }
+
+        if (isDynamicValue(candidate.value)) {
+            score -= 18;
+            reasons.push('DYNAMIC_TOKEN_PENALTY');
+        }
+
+        if (candidate.strategy === 'xpath') {
+            const penalty = xpathFragilityPenalty(candidate.value);
+            if (penalty > 0) {
+                score -= penalty;
+                reasons.push('FRAGILE_XPATH_PENALTY');
+            }
+        }
+
+        return {
+            ...candidate,
+            score: Math.max(0, Math.min(100, Math.round(score))),
+            matchCount,
+            reasons,
+        };
+    });
+
+    return ranked.sort((a, b) => {
+        if (b.score !== a.score) return b.score - a.score;
+        if (a.matchCount !== b.matchCount) return a.matchCount - b.matchCount;
+        return a.value.localeCompare(b.value);
+    });
+}

package/src/core/types.ts

@@ -0,0 +1,79 @@
+export type Platform = 'ios' | 'android' | 'unknown';
+
+export type SelectorStrategy =
+    | 'accessibility id'
+    | 'id'
+    | 'xpath'
+    | 'class name'
+    | '-ios predicate string'
+    | '-ios class chain'
+    | '-android uiautomator';
+
+export type SelectorReason =
+    | 'BASE_STRATEGY_PRIORITY'
+    | 'UNIQUE_MATCH'
+    | 'MULTIPLE_MATCHES'
+    | 'NO_MATCH'
+    | 'VALID_MATCH'
+    | 'ACTIONABLE_ELEMENT_BONUS'
+    | 'DYNAMIC_TOKEN_PENALTY'
+    | 'FRAGILE_XPATH_PENALTY';
+
+export type ParsedElement = {
+    elementRef: string;
+    index: number;
+    platform: Platform;
+    type: string;
+    xpath: string;
+    name: string;
+    label: string;
+    value: string;
+    text: string;
+    resourceId: string;
+    contentDesc: string;
+    enabled: boolean;
+    visible: boolean;
+    accessible: boolean;
+    clickable: boolean;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    attributes: Record<string, string>;
+};
+
+export type SelectorCandidate = {
+    strategy: SelectorStrategy;
+    value: string;
+    platform: Platform | 'generic';
+};
+
+export type RankedSelector = SelectorCandidate & {
+    score: number;
+    matchCount: number;
+    reasons: SelectorReason[];
+};
+
+export type ParsedSource = {
+    platform: Platform;
+    elements: ParsedElement[];
+};
+
+export type CommandError = {
+    code: string;
+    message: string;
+    details?: unknown;
+};
+
+export type CommandResponse<T = unknown> = {
+    ok: boolean;
+    command: string;
+    timestamp: string;
+    result?: T;
+    error?: CommandError;
+};
+
+export type Point = {
+    x: number;
+    y: number;
+};

package/src/core/xml/parse-source.ts

@@ -0,0 +1,197 @@
+import { XMLParser } from 'fast-xml-parser';
+import type { ParsedElement, ParsedSource, Platform } from '../types';
+
+type XmlNode = Record<string, unknown>;
+
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '',
+    parseTagValue: false,
+    parseAttributeValue: false,
+    trimValues: false,
+    textNodeName: '#text',
+    preserveOrder: false,
+});
+
+function asString(value: unknown): string {
+    if (value === undefined || value === null) return '';
+    return String(value);
+}
+
+function asBoolean(value: unknown): boolean {
+    if (typeof value === 'boolean') return value;
+    return asString(value).toLowerCase() === 'true' || asString(value) === '1';
+}
+
+function asNumber(value: unknown): number {
+    const n = Number(asString(value));
+    return Number.isFinite(n) ? n : 0;
+}
+
+function parseAndroidBounds(bounds: string): { x: number; y: number; width: number; height: number } {
+    const match = bounds.match(/\[(\-?\d+),(\-?\d+)\]\[(\-?\d+),(\-?\d+)\]/);
+    if (!match) {
+        return { x: 0, y: 0, width: 0, height: 0 };
+    }
+
+    const x1 = Number(match[1]);
+    const y1 = Number(match[2]);
+    const x2 = Number(match[3]);
+    const y2 = Number(match[4]);
+
+    return {
+        x: x1,
+        y: y1,
+        width: Math.max(0, x2 - x1),
+        height: Math.max(0, y2 - y1),
+    };
+}
+
+function detectPlatform(type: string, attrs: Record<string, string>): Platform {
+    if (type.startsWith('XCUIElementType') || attrs.type?.startsWith('XCUIElementType')) {
+        return 'ios';
+    }
+
+    if (
+        type.startsWith('android.') ||
+        attrs.class?.startsWith('android.') ||
+        attrs['resource-id'] ||
+        attrs['content-desc']
+    ) {
+        return 'android';
+    }
+
+    return 'unknown';
+}
+
+function extractAttributes(node: XmlNode): Record<string, string> {
+    const attrs: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(node)) {
+        if (value === null || value === undefined || key === '#text') continue;
+        if (Array.isArray(value)) continue;
+        if (typeof value === 'object') continue;
+        attrs[key] = String(value);
+    }
+
+    return attrs;
+}
+
+function extractChildren(node: XmlNode): Array<{ tag: string; child: XmlNode }> {
+    const children: Array<{ tag: string; child: XmlNode }> = [];
+
+    for (const [key, value] of Object.entries(node)) {
+        if (key === '#text' || value === null || value === undefined) continue;
+
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item && typeof item === 'object') {
+                    children.push({ tag: key, child: item as XmlNode });
+                }
+            }
+            continue;
+        }
+
+        if (typeof value === 'object') {
+            children.push({ tag: key, child: value as XmlNode });
+        }
+    }
+
+    return children;
+}
+
+function makeElementRef(platform: Platform, xpath: string): string {
+    return `${platform}:${xpath}`;
+}
+
+export function parseSource(xmlString: string): ParsedSource {
+    if (!xmlString || !xmlString.trim()) {
+        return { platform: 'unknown', elements: [] };
+    }
+
+    let parsed: Record<string, unknown>;
+    try {
+        parsed = parser.parse(xmlString) as Record<string, unknown>;
+    } catch {
+        return { platform: 'unknown', elements: [] };
+    }
+
+    const rootEntry = Object.entries(parsed).find(([, value]) => value && typeof value === 'object');
+    if (!rootEntry) {
+        return { platform: 'unknown', elements: [] };
+    }
+
+    const [rootTag, rootNode] = rootEntry;
+    const elements: ParsedElement[] = [];
+    let nextIndex = 0;
+
+    function visit(tag: string, node: XmlNode, parentXpath: string, siblingIndex: number): void {
+        const attrs = extractAttributes(node);
+        const type = attrs.type || attrs.class || tag;
+        const xpath = `${parentXpath}/${type}[${siblingIndex}]`;
+
+        const platform = detectPlatform(type, attrs);
+        const bounds = attrs.bounds ? parseAndroidBounds(attrs.bounds) : undefined;
+
+        const x = attrs.x !== undefined ? asNumber(attrs.x) : (bounds?.x ?? 0);
+        const y = attrs.y !== undefined ? asNumber(attrs.y) : (bounds?.y ?? 0);
+        const width = attrs.width !== undefined ? asNumber(attrs.width) : (bounds?.width ?? 0);
+        const height = attrs.height !== undefined ? asNumber(attrs.height) : (bounds?.height ?? 0);
+
+        const name = attrs.name || attrs['content-desc'] || attrs.resourceId || '';
+        const label = attrs.label || attrs.text || attrs['content-desc'] || '';
+        const value = attrs.value || '';
+        const text = attrs.text || value || '';
+        const resourceId = attrs['resource-id'] || attrs.resourceId || attrs.id || '';
+        const contentDesc = attrs['content-desc'] || attrs.contentDesc || '';
+
+        elements.push({
+            elementRef: makeElementRef(platform, xpath),
+            index: nextIndex++,
+            platform,
+            type,
+            xpath,
+            name,
+            label,
+            value,
+            text,
+            resourceId,
+            contentDesc,
+            enabled: asBoolean(attrs.enabled),
+            visible: asBoolean(attrs.visible) || asBoolean(attrs.displayed),
+            accessible: asBoolean(attrs.accessible),
+            clickable: asBoolean(attrs.clickable),
+            x,
+            y,
+            width,
+            height,
+            attributes: attrs,
+        });
+
+        const childCounters: Record<string, number> = {};
+        const children = extractChildren(node);
+        for (const { tag: childTag, child } of children) {
+            const childType = asString((child as XmlNode).type || (child as XmlNode).class || childTag);
+            childCounters[childType] = (childCounters[childType] || 0) + 1;
+            visit(childTag, child, xpath, childCounters[childType]);
+        }
+    }
+
+    visit(rootTag, rootNode as XmlNode, '', 1);
+
+    const platform =
+        elements.find(element => element.platform === 'ios')?.platform ||
+        elements.find(element => element.platform === 'android')?.platform ||
+        'unknown';
+
+    const withResolvedPlatform = elements.map(element => ({
+        ...element,
+        platform: element.platform === 'unknown' ? platform : element.platform,
+        elementRef: makeElementRef(element.platform === 'unknown' ? platform : element.platform, element.xpath),
+    }));
+
+    return {
+        platform,
+        elements: withResolvedPlatform,
+    };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+import { runCLI } from './cli/index';
+
+runCLI().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/src/server/appium-client.ts

@@ -0,0 +1,24 @@
+export class AppiumClient {
+    constructor(private appiumUrl: string) { }
+
+    async fetchFromAppium(sessionId: string, endpoint: string): Promise<any> {
+        try {
+            const response = await fetch(`${this.appiumUrl}/session/${sessionId}/${endpoint}`);
+            const data = await response.json();
+            if (data && typeof data === 'object' && 'value' in data) {
+                return data.value;
+            }
+            return null;
+        } catch (e) {
+            return null;
+        }
+    }
+
+    async captureState(sessionId: string): Promise<{ screenshot?: string; source?: string }> {
+        const [screenshot, source] = await Promise.all([
+            this.fetchFromAppium(sessionId, 'screenshot'),
+            this.fetchFromAppium(sessionId, 'source'),
+        ]);
+        return { screenshot, source };
+    }
+}

package/src/server/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './appium-client';
+export * from './interaction-recorder';
+export * from './proxy-middleware';
+export * from './routes';
+export * from './server';