@leera.io/qa-runner 1.0.0

package/dist/src/drivers/webdriver/actions.js

@@ -0,0 +1,328 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { clip, expectWithin, matches, verb } from '../common.js';
+import { NotFound, Unsupported } from '../driver.js';
+import { describeAndroidTarget, findAll, locate } from './locate.js';
+import { mobile, webdriverMessage } from './session.js';
+/** Named android keys (plan §3) → Android key codes. */
+export const ANDROID_KEYS = {
+    back: 4,
+    home: 3,
+    enter: 66,
+    tab: 61,
+    delete: 67,
+    volume_up: 24,
+    volume_down: 25,
+    app_switch: 187,
+};
+/** `KEYCODE_*` names from android.view.KeyEvent that scripts are most likely to use. */
+export const ANDROID_KEYCODES = {
+    KEYCODE_SOFT_LEFT: 1, KEYCODE_SOFT_RIGHT: 2, KEYCODE_HOME: 3, KEYCODE_BACK: 4, KEYCODE_CALL: 5, KEYCODE_ENDCALL: 6,
+    KEYCODE_0: 7, KEYCODE_1: 8, KEYCODE_2: 9, KEYCODE_3: 10, KEYCODE_4: 11, KEYCODE_5: 12, KEYCODE_6: 13, KEYCODE_7: 14,
+    KEYCODE_8: 15, KEYCODE_9: 16, KEYCODE_STAR: 17, KEYCODE_POUND: 18, KEYCODE_DPAD_UP: 19, KEYCODE_DPAD_DOWN: 20,
+    KEYCODE_DPAD_LEFT: 21, KEYCODE_DPAD_RIGHT: 22, KEYCODE_DPAD_CENTER: 23, KEYCODE_VOLUME_UP: 24, KEYCODE_VOLUME_DOWN: 25,
+    KEYCODE_POWER: 26, KEYCODE_CAMERA: 27, KEYCODE_CLEAR: 28,
+    KEYCODE_A: 29, KEYCODE_B: 30, KEYCODE_C: 31, KEYCODE_D: 32, KEYCODE_E: 33, KEYCODE_F: 34, KEYCODE_G: 35, KEYCODE_H: 36,
+    KEYCODE_I: 37, KEYCODE_J: 38, KEYCODE_K: 39, KEYCODE_L: 40, KEYCODE_M: 41, KEYCODE_N: 42, KEYCODE_O: 43, KEYCODE_P: 44,
+    KEYCODE_Q: 45, KEYCODE_R: 46, KEYCODE_S: 47, KEYCODE_T: 48, KEYCODE_U: 49, KEYCODE_V: 50, KEYCODE_W: 51, KEYCODE_X: 52,
+    KEYCODE_Y: 53, KEYCODE_Z: 54, KEYCODE_COMMA: 55, KEYCODE_PERIOD: 56, KEYCODE_TAB: 61, KEYCODE_SPACE: 62,
+    KEYCODE_ENTER: 66, KEYCODE_DEL: 67, KEYCODE_MINUS: 69, KEYCODE_EQUALS: 70, KEYCODE_AT: 77, KEYCODE_SEARCH: 84,
+    KEYCODE_MEDIA_PLAY_PAUSE: 85, KEYCODE_PAGE_UP: 92, KEYCODE_PAGE_DOWN: 93, KEYCODE_ESCAPE: 111, KEYCODE_FORWARD_DEL: 112,
+    KEYCODE_MOVE_HOME: 122, KEYCODE_MOVE_END: 123, KEYCODE_MENU: 82, KEYCODE_NOTIFICATION: 83, KEYCODE_VOLUME_MUTE: 164,
+    KEYCODE_APP_SWITCH: 187, KEYCODE_WAKEUP: 224, KEYCODE_SLEEP: 223,
+};
+/** Resolves an android key name to its key code; throws `Unsupported` for anything else. */
+export function androidKeyCode(key) {
+    const named = ANDROID_KEYS[key.toLowerCase()];
+    if (named !== undefined)
+        return named;
+    const upper = key.toUpperCase();
+    if (/^KEYCODE_[A-Z0-9_]+$/.test(upper)) {
+        const code = ANDROID_KEYCODES[upper];
+        if (code !== undefined)
+            return code;
+        throw new Unsupported(`key '${key}' is not known to this runner version`);
+    }
+    throw new Unsupported(`'${key}' is not an android key; use ${Object.keys(ANDROID_KEYS).join(', ')} or KEYCODE_…`);
+}
+export const ANDROID_ACTIONS = [
+    'launch',
+    'terminate',
+    'reset',
+    'deep_link',
+    'tap',
+    'double_tap',
+    'long_press',
+    'type',
+    'clear',
+    'press',
+    'hide_keyboard',
+    'swipe',
+    'scroll_to',
+    'set_orientation',
+    'accept_alert',
+    'dismiss_alert',
+    'wait',
+    'wait_for',
+    'screenshot',
+    'expect_visible',
+    'expect_hidden',
+    'expect_text',
+];
+/** Deep link schemes a script may open (plan §3); the server validates too. */
+export function checkDeepLink(url) {
+    const match = /^([a-z][a-z0-9+.-]{1,63}):\/\//i.exec(url);
+    if (!match)
+        throw new Error(`deep link '${clip(url)}' must start with a scheme such as https:// or myapp://`);
+    if (/^(javascript|file|data|blob|content|intent)$/i.test(match[1]))
+        throw new Error(`deep links with the ${match[1]} scheme are not allowed`);
+    return url;
+}
+function requireTarget(action) {
+    if (!action.target)
+        throw new Error(`'${action.type}' needs a target`);
+    return action.target;
+}
+async function element(ctx, target, timeoutMs) {
+    const found = await locate(ctx.client, target, timeoutMs, ctx.render);
+    if (!found)
+        throw new NotFound(`${describeAndroidTarget(target)} was not found within ${Math.round(timeoutMs / 100) / 10} s`);
+    ctx.onLocated?.(found);
+    return found;
+}
+async function visibleCount(ctx, target) {
+    const nth = target.nth;
+    const ids = await findAll(ctx.client, { ...target, fallbacks: undefined }, ctx.render);
+    const pool = nth === undefined ? ids : ids.slice(nth, nth + 1);
+    let count = 0;
+    for (const id of pool) {
+        if (await ctx.client.isElementDisplayed(id).catch(() => false))
+            count += 1;
+    }
+    return count;
+}
+/** The text an element shows: its text, else its content-description. */
+export async function elementText(client, elementId) {
+    const text = (await client.getElementText(elementId).catch(() => '')) ?? '';
+    if (text.trim())
+        return text.trim();
+    const desc = await client.getElementAttribute(elementId, 'content-desc').catch(() => null);
+    return (desc ?? '').trim();
+}
+export function orientationValue(value) {
+    const lower = (value ?? '').toLowerCase();
+    if (lower === 'portrait')
+        return 'PORTRAIT';
+    if (lower === 'landscape')
+        return 'LANDSCAPE';
+    throw new Error(`orientation must be portrait or landscape, not '${value ?? ''}'`);
+}
+export function swipeDistance(distance) {
+    if (distance === undefined)
+        return 0.7;
+    if (!Number.isFinite(distance) || distance < 0.1 || distance > 1)
+        throw new Error('distance must be between 0.1 and 1');
+    return distance;
+}
+/** The screen area gestures use when no element is given: the middle, clear of the system bars. */
+export function gestureArea(rect) {
+    const left = Math.round(rect.width * 0.1);
+    const top = Math.round(rect.height * 0.2);
+    return { left, top, width: Math.round(rect.width * 0.8), height: Math.round(rect.height * 0.6) };
+}
+function checkDirection(direction, fallback) {
+    const value = (direction ?? fallback);
+    if (!['up', 'down', 'left', 'right'].includes(value))
+        throw new Error(`direction must be up, down, left or right, not '${direction}'`);
+    return value;
+}
+async function pressKey(ctx, key) {
+    await mobile(ctx.client, 'pressKey', { keycode: androidKeyCode(key) });
+}
+/** Performs one android DSL action (or a session-only `back`/`home`). */
+export async function runAndroidAction(ctx, action) {
+    const timeout = action.timeout_ms ?? ctx.defaultTimeoutMs;
+    const { client, appId } = ctx;
+    switch (action.type) {
+        case 'launch': {
+            if (action.activity) {
+                const activity = ctx.render(action.activity);
+                if (!/^[A-Za-z0-9_.$/]+$/.test(activity))
+                    throw new Error(`'${activity}' is not an activity name`);
+                const component = activity.includes('/') ? activity : `${appId}/${activity.includes('.') ? activity : `.${activity}`}`;
+                await mobile(client, 'startActivity', { component, wait: true });
+            }
+            else {
+                await mobile(client, 'activateApp', { appId });
+            }
+            return {};
+        }
+        case 'terminate':
+            await mobile(client, 'terminateApp', { appId });
+            return {};
+        case 'reset':
+            await mobile(client, 'clearApp', { appId });
+            await mobile(client, 'activateApp', { appId });
+            return {};
+        case 'deep_link': {
+            const url = checkDeepLink(ctx.render(action.url ?? ''));
+            try {
+                await mobile(client, 'deepLink', { url, package: appId, waitForLaunch: true });
+            }
+            catch (error) {
+                throw new Error(`the deep link could not be opened: ${webdriverMessage(error)}`);
+            }
+            return {};
+        }
+        case 'tap': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            await client.elementClick(found.elementId);
+            return {};
+        }
+        case 'double_tap': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            await mobile(client, 'doubleClickGesture', { elementId: found.elementId });
+            return {};
+        }
+        case 'long_press': {
+            const ms = action.ms ?? 1_000;
+            if (ms < 300 || ms > 10_000)
+                throw new Error('long_press ms must be between 300 and 10000');
+            const found = await element(ctx, requireTarget(action), timeout);
+            await mobile(client, 'longClickGesture', { elementId: found.elementId, duration: ms });
+            return {};
+        }
+        case 'type': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            if (action.clear)
+                await client.elementClear(found.elementId);
+            await client.elementSendKeys(found.elementId, ctx.render(action.value ?? ''));
+            return {};
+        }
+        case 'clear': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            await client.elementClear(found.elementId);
+            return {};
+        }
+        case 'press':
+            await pressKey(ctx, action.key ?? '');
+            return {};
+        case 'back':
+            await pressKey(ctx, 'back');
+            return {};
+        case 'home':
+            await pressKey(ctx, 'home');
+            return {};
+        case 'hide_keyboard':
+            await mobile(client, 'hideKeyboard').catch((error) => {
+                // Nothing to hide is not a failure.
+                if (!/keyboard/i.test(webdriverMessage(error)))
+                    throw error;
+            });
+            return {};
+        case 'swipe': {
+            const direction = checkDirection(action.direction, 'up');
+            const percent = swipeDistance(action.distance);
+            if (action.target) {
+                const found = await element(ctx, action.target, timeout);
+                await mobile(client, 'swipeGesture', { elementId: found.elementId, direction, percent });
+            }
+            else {
+                const area = gestureArea(await client.getWindowRect());
+                await mobile(client, 'swipeGesture', { ...area, direction, percent });
+            }
+            return {};
+        }
+        case 'scroll_to': {
+            const target = requireTarget(action);
+            const direction = checkDirection(action.direction, 'down');
+            const maxSwipes = action.max_swipes ?? 10;
+            if (!Number.isInteger(maxSwipes) || maxSwipes < 1 || maxSwipes > 20)
+                throw new Error('max_swipes must be 1-20');
+            const area = gestureArea(await client.getWindowRect());
+            for (let swipe = 0;; swipe += 1) {
+                const found = await locate(client, target, 500, ctx.render);
+                if (found && (await client.isElementDisplayed(found.elementId).catch(() => false))) {
+                    ctx.onLocated?.(found);
+                    return {};
+                }
+                if (swipe >= maxSwipes)
+                    break;
+                const more = await mobile(client, 'scrollGesture', { ...area, direction, percent: 0.7 });
+                if (more === false) {
+                    // One last look after reaching the end.
+                    const last = await locate(client, target, 500, ctx.render);
+                    if (last) {
+                        ctx.onLocated?.(last);
+                        return {};
+                    }
+                    break;
+                }
+            }
+            throw new Error(`${describeAndroidTarget(target)} did not appear after scrolling ${direction} ${maxSwipes} times`);
+        }
+        case 'set_orientation':
+            await client.setOrientation(orientationValue(action.value));
+            return {};
+        case 'accept_alert':
+        case 'dismiss_alert': {
+            const deadline = Date.now() + timeout;
+            for (;;) {
+                try {
+                    if (action.type === 'accept_alert')
+                        await client.acceptAlert();
+                    else
+                        await client.dismissAlert();
+                    return {};
+                }
+                catch (error) {
+                    if (Date.now() >= deadline)
+                        throw new Error(`no alert was showing: ${webdriverMessage(error)}`);
+                    await sleep(300);
+                }
+            }
+        }
+        case 'wait':
+            await sleep(Math.min(Math.max(action.ms ?? 0, 0), 30_000));
+            return {};
+        case 'screenshot':
+            return { screenshot: Buffer.from(await client.takeScreenshot(), 'base64') };
+        case 'wait_for':
+        case 'expect_visible': {
+            const target = requireTarget(action);
+            await expectWithin(timeout, async () => {
+                const found = await locate(client, target, 0, ctx.render);
+                if (!found)
+                    return false;
+                const shown = await client.isElementDisplayed(found.elementId).catch(() => false);
+                if (shown)
+                    ctx.onLocated?.(found);
+                return shown;
+            }, `${describeAndroidTarget(target)} to be visible`);
+            return {};
+        }
+        case 'expect_hidden': {
+            const target = requireTarget(action);
+            await expectWithin(timeout, async () => (await visibleCount(ctx, target)) === 0, `${describeAndroidTarget(target)} to be hidden`);
+            return {};
+        }
+        case 'expect_text': {
+            const target = requireTarget(action);
+            const expected = ctx.render(action.value ?? '');
+            let actual = '';
+            await expectWithin(timeout, async () => {
+                const found = await locate(client, target, 0, ctx.render);
+                if (!found) {
+                    actual = '(not found)';
+                    return false;
+                }
+                actual = await elementText(client, found.elementId);
+                return matches(actual, expected, action.match);
+            }, () => `text of ${describeAndroidTarget(target)} to ${verb(action.match)} "${expected}", found "${clip(actual)}"`);
+            return {};
+        }
+        case 'goto':
+            throw new Unsupported(`'goto' is not an android action; use deep_link`);
+        default:
+            throw new Unsupported(`'${action.type}' is not an android action`);
+    }
+}

package/dist/src/drivers/webdriver/desktop-keys.js

@@ -0,0 +1,141 @@
+import { Unsupported } from '../driver.js';
+/**
+ * The desktop key rule for native macOS and Windows scripts (contracts §M, backend
+ * `KeyRule::Desktop`): a letter, digit, f1-f12 or a named key, optionally after `ctrl+`,
+ * `alt+`, `shift+` or `cmd+` (each at most once).
+ */
+export const DESKTOP_KEYS = [
+    'enter',
+    'return',
+    'tab',
+    'escape',
+    'backspace',
+    'delete',
+    'space',
+    'up',
+    'down',
+    'left',
+    'right',
+    'home',
+    'end',
+    'page_up',
+    'page_down',
+    'insert',
+];
+export const DESKTOP_MODIFIERS = ['ctrl', 'alt', 'shift', 'cmd'];
+/** Parses `ctrl+shift+s` into modifiers and the key; throws `Unsupported` for anything else. */
+export function parseDesktopKey(value) {
+    const raw = value.trim();
+    const parts = raw.split('+');
+    const main = (parts.pop() ?? '').trim();
+    const modifiers = [];
+    for (const part of parts) {
+        const name = part.trim().toLowerCase();
+        if (!DESKTOP_MODIFIERS.includes(name) || modifiers.includes(name))
+            throw new Unsupported(invalidKey(value));
+        modifiers.push(name);
+    }
+    const key = main.toLowerCase();
+    const single = /^[a-z0-9]$/.test(key);
+    const fn = /^f([1-9]|1[0-2])$/.test(key);
+    if (!single && !fn && !DESKTOP_KEYS.includes(key))
+        throw new Unsupported(invalidKey(value));
+    return { modifiers, key };
+}
+function invalidKey(value) {
+    return `'${value}' is not a desktop key; use a letter, digit, f1-f12 or ${DESKTOP_KEYS.join(', ')}, optionally after ctrl+, alt+, shift+ or cmd+`;
+}
+// ---------------------------------------------------------------------------------------------
+// macOS (Mac2): `macos: keys {keys: [{key, modifierFlags}]}`
+// ---------------------------------------------------------------------------------------------
+/** XCUIKeyModifierFlags. `cmd` is Command, `alt` is Option. */
+export const MAC_MODIFIER_FLAGS = {
+    shift: 1 << 1,
+    ctrl: 1 << 2,
+    alt: 1 << 3,
+    cmd: 1 << 4,
+};
+/** Named keys → the XCUIKeyboardKey constant names WebDriverAgentMac resolves. */
+const MAC_KEY_NAMES = {
+    enter: 'XCUIKeyboardKeyReturn',
+    return: 'XCUIKeyboardKeyReturn',
+    tab: 'XCUIKeyboardKeyTab',
+    escape: 'XCUIKeyboardKeyEscape',
+    backspace: 'XCUIKeyboardKeyDelete',
+    delete: 'XCUIKeyboardKeyForwardDelete',
+    space: 'XCUIKeyboardKeySpace',
+    up: 'XCUIKeyboardKeyUpArrow',
+    down: 'XCUIKeyboardKeyDownArrow',
+    left: 'XCUIKeyboardKeyLeftArrow',
+    right: 'XCUIKeyboardKeyRightArrow',
+    home: 'XCUIKeyboardKeyHome',
+    end: 'XCUIKeyboardKeyEnd',
+    page_up: 'XCUIKeyboardKeyPageUp',
+    page_down: 'XCUIKeyboardKeyPageDown',
+    insert: 'XCUIKeyboardKeyHelp',
+};
+/** A chord as the Mac2 driver's `macos: keys` item. */
+export function macKey(chord) {
+    const fn = /^f(\d+)$/.exec(chord.key);
+    const key = fn ? `XCUIKeyboardKeyF${fn[1]}` : (MAC_KEY_NAMES[chord.key] ?? chord.key);
+    const modifierFlags = chord.modifiers.reduce((flags, modifier) => flags | MAC_MODIFIER_FLAGS[modifier], 0);
+    return { key, modifierFlags };
+}
+// ---------------------------------------------------------------------------------------------
+// Windows: `windows: keys {actions: [{virtualKeyCode, down} | {text}]}`
+// ---------------------------------------------------------------------------------------------
+/** Win32 virtual-key codes. `cmd` is the Windows key. */
+export const WINDOWS_MODIFIER_VK = {
+    shift: 0x10,
+    ctrl: 0x11,
+    alt: 0x12,
+    cmd: 0x5b,
+};
+const WINDOWS_KEY_VK = {
+    enter: 0x0d,
+    return: 0x0d,
+    tab: 0x09,
+    escape: 0x1b,
+    backspace: 0x08,
+    delete: 0x2e,
+    space: 0x20,
+    up: 0x26,
+    down: 0x28,
+    left: 0x25,
+    right: 0x27,
+    home: 0x24,
+    end: 0x23,
+    page_up: 0x21,
+    page_down: 0x22,
+    insert: 0x2d,
+};
+/** The virtual-key code of a key: letters `A`-`Z` 0x41-0x5A, digits 0x30-0x39, F1-F12 0x70-0x7B. */
+export function windowsVirtualKey(key) {
+    if (/^[a-z]$/.test(key))
+        return key.toUpperCase().charCodeAt(0);
+    if (/^[0-9]$/.test(key))
+        return key.charCodeAt(0);
+    const fn = /^f(\d+)$/.exec(key);
+    if (fn)
+        return 0x70 + Number(fn[1]) - 1;
+    const code = WINDOWS_KEY_VK[key];
+    if (code === undefined)
+        throw new Unsupported(invalidKey(key));
+    return code;
+}
+/**
+ * A chord as `windows: keys` actions: modifiers down, the key down and up, modifiers up in
+ * reverse. A plain letter or digit is typed as text (keyboard layout independent).
+ */
+export function windowsKeyActions(chord) {
+    if (chord.modifiers.length === 0 && /^[a-z0-9]$/.test(chord.key))
+        return [{ text: chord.key }];
+    const vk = windowsVirtualKey(chord.key);
+    const mods = chord.modifiers.map((modifier) => WINDOWS_MODIFIER_VK[modifier]);
+    return [
+        ...mods.map((virtualKeyCode) => ({ virtualKeyCode, down: true })),
+        { virtualKeyCode: vk, down: true },
+        { virtualKeyCode: vk, down: false },
+        ...[...mods].reverse().map((virtualKeyCode) => ({ virtualKeyCode, down: false })),
+    ];
+}

package/dist/src/drivers/webdriver/dom-locate.js

@@ -0,0 +1,113 @@
+/*
+ * Runner-owned locator script for WebDriver-backed web views (Tauri, contracts §L).
+ * Executed with W3C `execute/sync` as `return (<this file>).apply(null, arguments);`, never
+ * with user-provided script. It takes one request object and returns plain JSON plus DOM
+ * elements, which WebDriver serializes as element references.
+ *
+ * request: { target: { css | text | test_id | xpath, exact? }, limit? }
+ * returns: { count, elements: Element[] (at most `limit`), visible: boolean[] }
+ * throws:  Error('invalid css selector: …' | 'invalid xpath: …' | 'the target names no locator')
+ */
+(function domLocate(request) {
+  const target = (request?.target) || {};
+  const limit = Math.max(1, Math.min(1000, Number((request?.limit) || 50)));
+  const SKIP = { SCRIPT: 1, STYLE: 1, NOSCRIPT: 1, TEMPLATE: 1, HEAD: 1, META: 1, LINK: 1, TITLE: 1 };
+
+  function normalize(value) {
+    return String(value == null ? '' : value)
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  /** The text a text locator compares: button-like inputs use their value. */
+  function textOf(element) {
+    if (element.tagName === 'INPUT') {
+      const type = (element.getAttribute('type') || '').toLowerCase();
+      return type === 'button' || type === 'submit' || type === 'reset' ? normalize(element.value) : '';
+    }
+    return normalize(element.textContent);
+  }
+
+  function textMatches(actual, wanted, exact) {
+    if (!actual) return false;
+    if (exact) return actual === wanted;
+    return actual.toLowerCase().indexOf(wanted.toLowerCase()) >= 0;
+  }
+
+  function isVisible(element) {
+    if (typeof element.checkVisibility === 'function') {
+      if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) return false;
+    } else {
+      const style = window.getComputedStyle(element);
+      if (style.visibility === 'hidden' || style.display === 'none' || style.opacity === '0') return false;
+    }
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+
+  function byText(wanted, exact) {
+    const value = normalize(wanted);
+    const out = [];
+    if (!value || !document.body) return out;
+    const all = document.body.querySelectorAll('*');
+    for (let i = 0; i < all.length; i += 1) {
+      const element = all[i];
+      if (SKIP[element.tagName]) continue;
+      if (!textMatches(textOf(element), value, exact)) continue;
+      // Innermost match only: skip an element when one of its element children matches too.
+      let inner = false;
+      for (let child = element.firstElementChild; child; child = child.nextElementSibling) {
+        if (!SKIP[child.tagName] && textMatches(textOf(child), value, exact)) {
+          inner = true;
+          break;
+        }
+      }
+      if (!inner) out.push(element);
+    }
+    return out;
+  }
+
+  function byCss(selector) {
+    try {
+      return Array.prototype.slice.call(document.querySelectorAll(selector));
+    } catch {
+      throw new Error(`invalid css selector: ${selector}`);
+    }
+  }
+
+  function byXpath(expression) {
+    let result;
+    try {
+      result = document.evaluate(expression, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+    } catch {
+      throw new Error(`invalid xpath: ${expression}`);
+    }
+    const out = [];
+    for (let i = 0; i < result.snapshotLength; i += 1) {
+      const node = result.snapshotItem(i);
+      if (node && node.nodeType === 1) out.push(node);
+    }
+    return out;
+  }
+
+  function byTestId(value) {
+    const out = [];
+    const all = document.querySelectorAll('[data-testid]');
+    for (let i = 0; i < all.length; i += 1) {
+      if (all[i].getAttribute('data-testid') === value) out.push(all[i]);
+    }
+    return out;
+  }
+
+  let found;
+  if (typeof target.css === 'string') found = byCss(target.css);
+  else if (typeof target.text === 'string') found = byText(target.text, target.exact === true);
+  else if (typeof target.test_id === 'string') found = byTestId(target.test_id);
+  else if (typeof target.xpath === 'string') found = byXpath(target.xpath);
+  else throw new Error('the target names no locator');
+
+  const elements = found.slice(0, limit);
+  const visible = [];
+  for (let j = 0; j < elements.length; j += 1) visible.push(isVisible(elements[j]));
+  return { count: found.length, elements: elements, visible: visible };
+})