nativeproof 0.1.1

package/dist/text.js

@@ -0,0 +1,129 @@
+import { $, browser, driver, expect } from "@wdio/globals";
+/**
+ * Cross-platform text/selector layer.
+ *
+ * Resolves the same human-readable control name to the right native selector on
+ * each platform (Android `UiSelector`, iOS predicate strings), preferring
+ * accessibility names with visible-text fallbacks. This is the single place a
+ * brittle selector becomes a stable automation id once the app teams add them.
+ * App-agnostic framework core.
+ */
+const DEFAULT_WAIT_MS = 15_000;
+export function exactText(text) {
+    if (driver.isAndroid) {
+        return `android=new UiSelector().text(${JSON.stringify(text)})`;
+    }
+    const literal = iosLiteral(text);
+    return `-ios predicate string:name == ${literal} OR label == ${literal} OR value == ${literal}`;
+}
+export function textContaining(text) {
+    if (driver.isAndroid) {
+        return `android=new UiSelector().textContains(${JSON.stringify(text)})`;
+    }
+    const literal = iosLiteral(text);
+    return `-ios predicate string:name CONTAINS ${literal} OR label CONTAINS ${literal} OR value CONTAINS ${literal}`;
+}
+export function accessibleName(text) {
+    return `~${text}`;
+}
+/** A trimmed, non-empty environment credential, or undefined when not configured. */
+export function configuredCredential(name) {
+    const value = process.env[name]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
+export function firstTextInput() {
+    if (driver.isAndroid) {
+        return 'android=new UiSelector().className("android.widget.EditText").instance(0)';
+    }
+    return "-ios class chain:**/XCUIElementTypeTextField[1]";
+}
+export function firstPasswordInput() {
+    if (driver.isAndroid) {
+        return 'android=new UiSelector().className("android.widget.EditText").instance(1)';
+    }
+    return "-ios class chain:**/XCUIElementTypeSecureTextField[1]";
+}
+export async function tapVisibleText(text, timeout = DEFAULT_WAIT_MS) {
+    const element = await visibleElementMatchingText(text, timeout);
+    await element.click();
+}
+export async function tapTextIfVisible(text, timeout = 1_000) {
+    try {
+        const element = await visibleElementMatchingText(text, timeout);
+        await element.click();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function expectVisibleText(text, timeout = DEFAULT_WAIT_MS) {
+    const element = await visibleElementMatchingText(text, timeout);
+    await expect(element).toBeDisplayed();
+}
+export async function waitForAnyVisibleText(labels, timeout = DEFAULT_WAIT_MS) {
+    const deadline = Date.now() + timeout;
+    let lastError;
+    while (Date.now() < deadline) {
+        for (const label of labels) {
+            try {
+                const element = await visibleElementMatchingText(label, 500);
+                return { label, element };
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        await browser.pause(500);
+    }
+    throw new Error(`None of these labels became visible: ${labels.join(", ")}${lastError instanceof Error ? `; last error: ${lastError.message}` : ""}`);
+}
+export async function waitForPageSourceToMention(phrases, timeout = DEFAULT_WAIT_MS) {
+    await browser.waitUntil(async () => {
+        const source = await driver.getPageSource();
+        return phrases.some((phrase) => source.toLowerCase().includes(phrase.toLowerCase()));
+    }, { timeout, timeoutMsg: `Page source did not mention any of: ${phrases.join(", ")}` });
+}
+export async function expectPageSourceToMention(phrases) {
+    const source = await driver.getPageSource();
+    const matched = phrases.some((phrase) => source.toLowerCase().includes(phrase.toLowerCase()));
+    await expect(matched).toBe(true);
+}
+export async function typeInto(selector, value) {
+    const input = await $(selector);
+    await input.waitForDisplayed({ timeout: DEFAULT_WAIT_MS });
+    await input.click();
+    await input.setValue(value);
+}
+async function visibleElementMatchingText(text, timeout) {
+    const deadline = Date.now() + timeout;
+    let lastError;
+    while (Date.now() < deadline) {
+        for (const selector of [accessibleName(text), exactText(text)]) {
+            try {
+                const element = await $(selector);
+                if ((await element.isDisplayed()) && (await elementCenterIsInsideViewport(element))) {
+                    return element;
+                }
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        await browser.pause(300);
+    }
+    throw new Error(`No visible element for "${text}"${lastError instanceof Error ? `; last error: ${lastError.message}` : ""}`);
+}
+async function elementCenterIsInsideViewport(element) {
+    const [location, size, viewport] = await Promise.all([
+        element.getLocation(),
+        element.getSize(),
+        driver.getWindowRect(),
+    ]);
+    const centerX = location.x + size.width / 2;
+    const centerY = location.y + size.height / 2;
+    return centerX >= 0 && centerX <= viewport.width && centerY >= 0 && centerY <= viewport.height;
+}
+function iosLiteral(text) {
+    return `"${text.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}

package/dist/wait.d.ts

@@ -0,0 +1,14 @@
+import { $ } from "@wdio/globals";
+/**
+ * Selector waiting helpers built on the WebdriverIO runner globals.
+ *
+ * `waitForAnyDisplayed` resolves the first of several candidate selectors to
+ * appear — essential on screens that render one of multiple possible states
+ * (e.g. an onboarding "Later" sheet vs. the role-selection home).
+ */
+export type DisplayedMatch = {
+    selector: string;
+    element: ReturnType<typeof $>;
+};
+export declare function waitAndClick(selector: string, timeout?: number): Promise<void>;
+export declare function waitForAnyDisplayed(selectors: string[], timeout?: number): Promise<DisplayedMatch>;

package/dist/wait.js

@@ -0,0 +1,26 @@
+import { $, browser } from "@wdio/globals";
+export async function waitAndClick(selector, timeout = 10000) {
+    const element = await $(selector);
+    await element.waitForDisplayed({ timeout });
+    await element.click();
+}
+export async function waitForAnyDisplayed(selectors, timeout = 30000) {
+    let matched;
+    await browser.waitUntil(async () => {
+        for (const selector of selectors) {
+            const element = $(selector);
+            const displayed = await element.isDisplayed().catch(() => false);
+            if (displayed) {
+                matched = { selector, element };
+                return true;
+            }
+        }
+        return false;
+    }, {
+        timeout,
+        interval: 500,
+        timeoutMsg: `None of the selectors became displayed within ${timeout}ms: ${selectors.join(", ")}`,
+    });
+    // waitUntil only resolves once the predicate set `matched`.
+    return matched;
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "nativeproof",
+  "version": "0.1.1",
+  "license": "MIT",
+  "type": "module",
+  "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",
+  "keywords": [
+    "appium",
+    "webdriverio",
+    "e2e",
+    "end-to-end",
+    "mobile",
+    "android",
+    "ios",
+    "testing",
+    "test-framework",
+    "playwright",
+    "xcuitest",
+    "uiautomator2"
+  ],
+  "author": "Ben Sheridan-Edwards",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BenSheridanEdwards/NativeProof.git"
+  },
+  "homepage": "https://github.com/BenSheridanEdwards/NativeProof#readme",
+  "bugs": {
+    "url": "https://github.com/BenSheridanEdwards/NativeProof/issues"
+  },
+  "bin": {
+    "nativeproof": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check . && tsc --noEmit",
+    "test": "node --import tsx --test 'test/**/*.test.ts'",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "dependencies": {
+    "@wdio/globals": "^9.17.0",
+    "webdriverio": "^9.21.1",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@types/node": "^24.10.1",
+    "@types/ws": "^8.18.1",
+    "@wdio/mocha-framework": "^9.21.0",
+    "expect-webdriverio": "^5.5.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}