@taqwright/taqwright 0.0.24

package/dist/inspector/locator-suggester.js

@@ -0,0 +1,539 @@
+import { Platform } from '../types/index.js';
+export const CATEGORY_ORDER = {
+    [Platform.ANDROID]: ['id', 'uiautomator', 'xpath'],
+    [Platform.IOS]: ['id', 'predicate', 'classChain', 'xpath'],
+};
+export const WEB_CATEGORY_ORDER = ['css', 'xpath'];
+export function generateCandidates(platform, attrs, _xpath, isWeb = false) {
+    if (isWeb) {
+        return generateWebCandidates(attrs, _xpath);
+    }
+    const out = [];
+    if (platform === Platform.ANDROID) {
+        const resourceId = attrs['resource-id'];
+        const contentDesc = attrs['content-desc'];
+        const text = attrs['text'];
+        const hint = attrs['hint'];
+        const cls = attrs['class'];
+        const stableAttrs = [];
+        if (resourceId)
+            stableAttrs.push({ key: 'resource-id', val: resourceId, priority: 700 });
+        if (contentDesc)
+            stableAttrs.push({ key: 'content-desc', val: contentDesc, priority: 680 });
+        if (text)
+            stableAttrs.push({ key: 'text', val: text, priority: 660 });
+        if (hint)
+            stableAttrs.push({ key: 'hint', val: hint, priority: 640 });
+        if (resourceId) {
+            const shortId = resourceId.includes(':id/') ? resourceId.split(':id/')[1] : resourceId;
+            out.push({
+                category: 'id',
+                subLabel: 'resource-id',
+                priority: 1000,
+                code: `mobile.getById(${jsString(shortId)})`,
+                using: 'id',
+                value: resourceId,
+            });
+        }
+        if (resourceId) {
+            const ua = `new UiSelector().resourceId(${jsString(resourceId)})`;
+            out.push({
+                category: 'uiautomator',
+                subLabel: 'resourceId',
+                priority: 950,
+                code: `mobile.getByUiSelector(${jsString(ua)})`,
+                using: '-android uiautomator',
+                value: ua,
+            });
+        }
+        if (contentDesc) {
+            const ua = `new UiSelector().description(${jsString(contentDesc)})`;
+            out.push({
+                category: 'uiautomator',
+                subLabel: 'content-desc',
+                priority: 920,
+                code: `mobile.getByUiSelector(${jsString(ua)})`,
+                using: '-android uiautomator',
+                value: ua,
+            });
+            const cdLine = contentDesc.includes('\n') ? longestLine(contentDesc) : undefined;
+            if (cdLine) {
+                const uac = `new UiSelector().descriptionContains(${jsString(cdLine)})`;
+                out.push({
+                    category: 'uiautomator',
+                    subLabel: 'content-desc contains',
+                    priority: 915,
+                    code: `mobile.getByUiSelector(${jsString(uac)})`,
+                    using: '-android uiautomator',
+                    value: uac,
+                });
+            }
+        }
+        if (cls && contentDesc) {
+            const ua = `new UiSelector().className(${jsString(cls)}).description(${jsString(contentDesc)})`;
+            out.push({
+                category: 'uiautomator',
+                subLabel: 'class + content-desc',
+                priority: 910,
+                code: `mobile.getByUiSelector(${jsString(ua)})`,
+                using: '-android uiautomator',
+                value: ua,
+            });
+        }
+        if (text) {
+            const ua = `new UiSelector().text(${jsString(text)})`;
+            out.push({
+                category: 'uiautomator',
+                subLabel: 'text',
+                priority: 900,
+                code: `mobile.getByUiSelector(${jsString(ua)})`,
+                using: '-android uiautomator',
+                value: ua,
+            });
+            const txtLine = text.includes('\n') ? longestLine(text) : undefined;
+            if (txtLine) {
+                const uac = `new UiSelector().textContains(${jsString(txtLine)})`;
+                out.push({
+                    category: 'uiautomator',
+                    subLabel: 'text contains',
+                    priority: 895,
+                    code: `mobile.getByUiSelector(${jsString(uac)})`,
+                    using: '-android uiautomator',
+                    value: uac,
+                });
+            }
+        }
+        if (cls && text) {
+            const ua = `new UiSelector().className(${jsString(cls)}).text(${jsString(text)})`;
+            out.push({
+                category: 'uiautomator',
+                subLabel: 'class + text',
+                priority: 890,
+                code: `mobile.getByUiSelector(${jsString(ua)})`,
+                using: '-android uiautomator',
+                value: ua,
+            });
+        }
+        if (cls) {
+            const ua = `new UiSelector().className(${jsString(cls)})`;
+            out.push({
+                category: 'uiautomator',
+                subLabel: 'class',
+                priority: 700,
+                code: `mobile.getByUiSelector(${jsString(ua)})`,
+                using: '-android uiautomator',
+                value: ua,
+            });
+        }
+        for (const a of stableAttrs) {
+            const xp = `//*[${xpathAttrEq(a.key, a.val)}]`;
+            out.push({
+                category: 'xpath',
+                subLabel: a.key,
+                priority: a.priority,
+                code: `mobile.getByXpath(${jsString(xp)})`,
+                using: 'xpath',
+                value: xp,
+            });
+        }
+        if (cls) {
+            const shortCls = shortClassLabel(cls);
+            for (const a of stableAttrs) {
+                const xp = `//${cls}[${xpathAttrEq(a.key, a.val)}]`;
+                out.push({
+                    category: 'xpath',
+                    subLabel: `${shortCls} + ${a.key}`,
+                    priority: a.priority - 50,
+                    code: `mobile.getByXpath(${jsString(xp)})`,
+                    using: 'xpath',
+                    value: xp,
+                });
+            }
+        }
+        if (cls && stableAttrs.length >= 2) {
+            const shortCls = shortClassLabel(cls);
+            for (let i = 0; i < stableAttrs.length; i++) {
+                for (let j = i + 1; j < stableAttrs.length; j++) {
+                    const a = stableAttrs[i];
+                    const b = stableAttrs[j];
+                    const xp = `//${cls}[${xpathAttrEq(a.key, a.val)}]` + `[${xpathAttrEq(b.key, b.val)}]`;
+                    out.push({
+                        category: 'xpath',
+                        subLabel: `${shortCls} + ${a.key} + ${b.key}`,
+                        priority: 450,
+                        code: `mobile.getByXpath(${jsString(xp)})`,
+                        using: 'xpath',
+                        value: xp,
+                    });
+                }
+            }
+        }
+    }
+    else {
+        const name = attrs['name'];
+        const label = attrs['label'];
+        const value = attrs['value'];
+        const placeholder = attrs['placeholderValue'];
+        const type = attrs['type'];
+        const stableAttrs = [];
+        if (name)
+            stableAttrs.push({ key: 'name', val: name, priority: 500 });
+        if (label)
+            stableAttrs.push({ key: 'label', val: label, priority: 480 });
+        if (value)
+            stableAttrs.push({ key: 'value', val: value, priority: 460 });
+        if (placeholder)
+            stableAttrs.push({ key: 'placeholderValue', val: placeholder, priority: 470 });
+        if (name) {
+            out.push({
+                category: 'id',
+                subLabel: 'accessibility id',
+                priority: 1000,
+                code: `mobile.getById(${jsString(name)})`,
+                using: 'accessibility id',
+                value: name,
+            });
+        }
+        if (name) {
+            const expr = `name == ${nsString(name)}`;
+            out.push({
+                category: 'predicate',
+                subLabel: 'name',
+                priority: 950,
+                code: `mobile.getByPredicate(${jsString(expr)})`,
+                using: '-ios predicate string',
+                value: expr,
+            });
+        }
+        if (label) {
+            const expr = `label == ${nsString(label)}`;
+            out.push({
+                category: 'predicate',
+                subLabel: 'label',
+                priority: 920,
+                code: `mobile.getByPredicate(${jsString(expr)})`,
+                using: '-ios predicate string',
+                value: expr,
+            });
+        }
+        if (value) {
+            const expr = `value == ${nsString(value)}`;
+            out.push({
+                category: 'predicate',
+                subLabel: 'value',
+                priority: 900,
+                code: `mobile.getByPredicate(${jsString(expr)})`,
+                using: '-ios predicate string',
+                value: expr,
+            });
+        }
+        if (placeholder) {
+            const expr = `placeholderValue == ${nsString(placeholder)}`;
+            out.push({
+                category: 'predicate',
+                subLabel: 'placeholderValue',
+                priority: 890,
+                code: `mobile.getByPredicate(${jsString(expr)})`,
+                using: '-ios predicate string',
+                value: expr,
+            });
+        }
+        if (type && name) {
+            const expr = `type == ${nsString(type)} AND name == ${nsString(name)}`;
+            out.push({
+                category: 'predicate',
+                subLabel: 'type + name',
+                priority: 880,
+                code: `mobile.getByPredicate(${jsString(expr)})`,
+                using: '-ios predicate string',
+                value: expr,
+            });
+        }
+        if (type && label) {
+            const expr = `type == ${nsString(type)} AND label == ${nsString(label)}`;
+            out.push({
+                category: 'predicate',
+                subLabel: 'type + label',
+                priority: 870,
+                code: `mobile.getByPredicate(${jsString(expr)})`,
+                using: '-ios predicate string',
+                value: expr,
+            });
+        }
+        if (type && placeholder) {
+            const expr = `type == ${nsString(type)} AND placeholderValue == ${nsString(placeholder)}`;
+            out.push({
+                category: 'predicate',
+                subLabel: 'type + placeholderValue',
+                priority: 860,
+                code: `mobile.getByPredicate(${jsString(expr)})`,
+                using: '-ios predicate string',
+                value: expr,
+            });
+        }
+        if (type && name) {
+            const chain = `**/${type}[\`name == ${classChainQuote(name)}\`]`;
+            out.push({
+                category: 'classChain',
+                subLabel: 'type + name',
+                priority: 800,
+                code: `mobile.getByClassChain(${jsString(chain)})`,
+                using: '-ios class chain',
+                value: chain,
+            });
+        }
+        if (type && label) {
+            const chain = `**/${type}[\`label == ${classChainQuote(label)}\`]`;
+            out.push({
+                category: 'classChain',
+                subLabel: 'type + label',
+                priority: 780,
+                code: `mobile.getByClassChain(${jsString(chain)})`,
+                using: '-ios class chain',
+                value: chain,
+            });
+        }
+        if (type && value) {
+            const chain = `**/${type}[\`value == ${classChainQuote(value)}\`]`;
+            out.push({
+                category: 'classChain',
+                subLabel: 'type + value',
+                priority: 770,
+                code: `mobile.getByClassChain(${jsString(chain)})`,
+                using: '-ios class chain',
+                value: chain,
+            });
+        }
+        if (type && placeholder) {
+            const chain = `**/${type}[\`placeholderValue == ${classChainQuote(placeholder)}\`]`;
+            out.push({
+                category: 'classChain',
+                subLabel: 'type + placeholderValue',
+                priority: 760,
+                code: `mobile.getByClassChain(${jsString(chain)})`,
+                using: '-ios class chain',
+                value: chain,
+            });
+        }
+        if (type) {
+            const chain = `**/${type}`;
+            out.push({
+                category: 'classChain',
+                subLabel: 'type only',
+                priority: 600,
+                code: `mobile.getByClassChain(${jsString(chain)})`,
+                using: '-ios class chain',
+                value: chain,
+            });
+        }
+        for (const a of stableAttrs) {
+            const xp = `//*[${xpathAttrEq(a.key, a.val)}]`;
+            out.push({
+                category: 'xpath',
+                subLabel: a.key,
+                priority: a.priority,
+                code: `mobile.getByXpath(${jsString(xp)})`,
+                using: 'xpath',
+                value: xp,
+            });
+        }
+        if (type) {
+            const shortType = type.replace(/^XCUIElementType/, '');
+            for (const a of stableAttrs) {
+                const xp = `//${type}[${xpathAttrEq(a.key, a.val)}]`;
+                out.push({
+                    category: 'xpath',
+                    subLabel: `${shortType} + ${a.key}`,
+                    priority: a.priority - 50,
+                    code: `mobile.getByXpath(${jsString(xp)})`,
+                    using: 'xpath',
+                    value: xp,
+                });
+            }
+        }
+        if (type && stableAttrs.length >= 2) {
+            const shortType = type.replace(/^XCUIElementType/, '');
+            for (let i = 0; i < stableAttrs.length; i++) {
+                for (let j = i + 1; j < stableAttrs.length; j++) {
+                    const a = stableAttrs[i];
+                    const b = stableAttrs[j];
+                    const xp = `//${type}[${xpathAttrEq(a.key, a.val)}]` + `[${xpathAttrEq(b.key, b.val)}]`;
+                    out.push({
+                        category: 'xpath',
+                        subLabel: `${shortType} + ${a.key} + ${b.key}`,
+                        priority: 350,
+                        code: `mobile.getByXpath(${jsString(xp)})`,
+                        using: 'xpath',
+                        value: xp,
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+function generateWebCandidates(attrs, xpath) {
+    const out = [];
+    const tag = (attrs['__tag'] ?? '').toLowerCase();
+    const pushCss = (value, subLabel, priority) => {
+        out.push({
+            category: 'css',
+            subLabel,
+            priority,
+            code: `mobile.getByCss(${jsString(value)})`,
+            using: 'css selector',
+            value,
+        });
+    };
+    const testKey = attrs['data-testid'] !== undefined
+        ? 'data-testid'
+        : attrs['data-test-id'] !== undefined
+            ? 'data-test-id'
+            : attrs['data-test'] !== undefined
+                ? 'data-test'
+                : undefined;
+    if (testKey) {
+        pushCss(`[${testKey}="${cssAttrValue(attrs[testKey])}"]`, testKey, 1000);
+    }
+    const id = attrs['id'];
+    if (id) {
+        if (/^[A-Za-z][\w-]*$/.test(id))
+            pushCss('#' + id, 'id', 950);
+        else
+            pushCss(`[id="${cssAttrValue(id)}"]`, 'id', 950);
+    }
+    const name = attrs['name'];
+    if (name)
+        pushCss(`[name="${cssAttrValue(name)}"]`, 'name', 900);
+    const cls = attrs['class'];
+    if (cls) {
+        const classes = cls.split(/\s+/).filter((c) => /^[A-Za-z_-][\w-]*$/.test(c));
+        if (classes.length) {
+            pushCss((tag || '') + '.' + classes.join('.'), tag ? 'tag + class' : 'class', 700);
+        }
+    }
+    if (xpath) {
+        const webXpath = xpath.replace(/(^|\/)([A-Za-z][A-Za-z0-9]*)/g, (_m, sep, name) => sep + name.toLowerCase());
+        out.push({
+            category: 'xpath',
+            subLabel: 'position',
+            priority: 100,
+            code: `mobile.getByXpath(${jsString(webXpath)})`,
+            using: 'xpath',
+            value: webXpath,
+        });
+    }
+    return out;
+}
+export function selectBestPerCategory(platform, suggestions, isWeb = false) {
+    const order = isWeb ? WEB_CATEGORY_ORDER : CATEGORY_ORDER[platform];
+    const byCategory = new Map();
+    for (const s of suggestions) {
+        if (!byCategory.has(s.category))
+            byCategory.set(s.category, []);
+        byCategory.get(s.category).push(s);
+    }
+    const out = [];
+    for (const cat of order) {
+        const list = byCategory.get(cat);
+        if (!list || list.length === 0)
+            continue;
+        list.sort((a, b) => b.priority - a.priority);
+        const unique = list.find((s) => s.unique);
+        out.push(unique ?? list[0]);
+    }
+    return out;
+}
+export function isPositional(s) {
+    return s.descriptor?.kind === 'nth';
+}
+export function pickRecommended(platform, verified, isWeb = false) {
+    const order = isWeb ? WEB_CATEGORY_ORDER : CATEGORY_ORDER[platform];
+    const rank = (s) => {
+        const ci = order.indexOf(s.category);
+        return ci === -1 ? order.length : ci;
+    };
+    const better = (a, b) => {
+        if (a.priority !== b.priority)
+            return a.priority > b.priority;
+        return rank(a) < rank(b);
+    };
+    const unique = verified.filter((s) => s.unique);
+    if (unique.length === 0)
+        return undefined;
+    const robust = unique.filter((s) => !isPositional(s));
+    const pool = robust.length > 0 ? robust : unique;
+    let best;
+    for (const s of pool)
+        if (!best || better(s, best))
+            best = s;
+    return best;
+}
+function shortClassLabel(cls) {
+    if (cls.startsWith('android.widget.'))
+        return cls.slice('android.widget.'.length);
+    if (cls.startsWith('android.view.'))
+        return cls.slice('android.view.'.length);
+    return cls.split('.').pop() || cls;
+}
+function jsString(s) {
+    return JSON.stringify(s);
+}
+function cssAttrValue(s) {
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function xpathLiteral(s) {
+    if (!s.includes("'"))
+        return `'${s}'`;
+    if (!s.includes('"'))
+        return `"${s}"`;
+    const parts = s.split("'");
+    return `concat(${parts.map((p, i) => (i === 0 ? `'${p}'` : `"'", '${p}'`)).join(', ')})`;
+}
+function nonEmptyLines(val) {
+    return val
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+function longestLine(val) {
+    const lines = nonEmptyLines(val);
+    if (lines.length === 0)
+        return undefined;
+    return lines.reduce((a, b) => (b.length > a.length ? b : a));
+}
+function xpathAttrEq(key, val) {
+    if (val.includes('\n')) {
+        const lines = nonEmptyLines(val);
+        if (lines.length > 0) {
+            return lines.map((l) => `contains(@${key}, ${xpathLiteral(l)})`).join(' and ');
+        }
+    }
+    return `@${key}=${xpathLiteral(val)}`;
+}
+function nsString(s) {
+    return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+function classChainQuote(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+export function makeNthSuggestion(base, idx) {
+    const descriptor = {
+        kind: 'nth',
+        on: {
+            kind: 'leaf',
+            using: base.using,
+            value: base.value,
+        },
+        n: idx,
+    };
+    return {
+        ...base,
+        code: `${base.code}.nth(${idx})`,
+        subLabel: `${base.subLabel} + nth(${idx})`,
+        priority: base.priority - 100,
+        descriptor,
+        count: 1,
+        unique: true,
+    };
+}

package/dist/inspector/recorder.d.ts

@@ -0,0 +1,128 @@
+import type { LocatorDescriptor } from '../types/index.js';
+export type SwipeDirection = 'up' | 'down' | 'left' | 'right';
+export interface RecordedLocator {
+    code: string;
+    using?: string;
+    value?: string;
+    descriptor?: LocatorDescriptor;
+}
+export type RecordedAction = {
+    kind: 'tap';
+    x: number;
+    y: number;
+} | {
+    kind: 'swipe';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    durationMs: number;
+} | {
+    kind: 'screenScroll';
+    direction: SwipeDirection;
+    fromX?: number;
+    toX?: number;
+    fromY?: number;
+    toY?: number;
+} | ({
+    kind: 'locatorClick';
+} & RecordedLocator) | ({
+    kind: 'locatorDoubleTap';
+} & RecordedLocator) | ({
+    kind: 'locatorLongPress';
+} & RecordedLocator) | ({
+    kind: 'locatorFill';
+    text: string;
+} & RecordedLocator) | ({
+    kind: 'locatorClear';
+} & RecordedLocator) | ({
+    kind: 'assertVisible';
+} & RecordedLocator) | ({
+    kind: 'assertHidden';
+} & RecordedLocator) | ({
+    kind: 'assertEnabled';
+} & RecordedLocator) | ({
+    kind: 'assertDisabled';
+} & RecordedLocator) | ({
+    kind: 'assertText';
+    expected: string;
+    mode: 'exact' | 'contains';
+} & RecordedLocator) | ({
+    kind: 'assertValue';
+    expected: string;
+} & RecordedLocator) | ({
+    kind: 'locatorSwipe';
+    direction: SwipeDirection;
+} & RecordedLocator) | ({
+    kind: 'locatorScrollIntoView';
+} & RecordedLocator) | ({
+    kind: 'locatorPinch';
+    direction: 'in' | 'out';
+} & RecordedLocator) | ({
+    kind: 'locatorDragTo';
+    targetCode: string;
+    target?: RecordedLocator;
+} & RecordedLocator) | ({
+    kind: 'locatorCheck';
+} & RecordedLocator) | ({
+    kind: 'locatorUncheck';
+} & RecordedLocator) | ({
+    kind: 'locatorFocus';
+} & RecordedLocator) | ({
+    kind: 'locatorBlur';
+} & RecordedLocator) | ({
+    kind: 'locatorPress';
+    key: string;
+} & RecordedLocator) | ({
+    kind: 'locatorPressSequentially';
+    text: string;
+    delay?: number;
+} & RecordedLocator) | ({
+    kind: 'locatorSelectOption';
+    value: SelectOptionInput | string;
+} & RecordedLocator) | ({
+    kind: 'assertChecked';
+} & RecordedLocator) | ({
+    kind: 'assertUnchecked';
+} & RecordedLocator) | ({
+    kind: 'assertEditable';
+} & RecordedLocator) | ({
+    kind: 'assertReadonly';
+} & RecordedLocator) | ({
+    kind: 'assertFocused';
+} & RecordedLocator) | ({
+    kind: 'assertAttached';
+} & RecordedLocator) | ({
+    kind: 'assertEmpty';
+} & RecordedLocator) | ({
+    kind: 'assertInViewport';
+} & RecordedLocator) | ({
+    kind: 'assertCount';
+    expected: number;
+} & RecordedLocator) | ({
+    kind: 'assertAttribute';
+    name: string;
+    expected: string;
+} & RecordedLocator) | {
+    kind: 'sendKeys';
+    text: string;
+} | {
+    kind: 'switchContext';
+    context: string;
+} | {
+    kind: 'comment';
+    text: string;
+};
+export interface SelectOptionInput {
+    label?: string;
+    index?: number;
+    date?: string;
+    time?: string;
+}
+export declare class Recorder {
+    private readonly actions;
+    push(a: RecordedAction): void;
+    list(): RecordedAction[];
+    clear(): void;
+    toSpec(testName?: string): string;
+}