mobile-wdio-kit 0.1.0

package/template/scripts/run-mcp-android-smoke.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+# Starts Appium in the background, waits until /status is ready, runs MCP smoke, stops Appium.
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+# shellcheck source=android-env.sh
+. "$SCRIPT_DIR/android-env.sh"
+
+PROJECT_ROOT=$(android_env_project_root)
+cd "$PROJECT_ROOT"
+android_env_prepare_paths
+
+APPIUM_HOST="${APPIUM_HOST:-127.0.0.1}"
+APPIUM_PORT="${APPIUM_PORT:-4723}"
+STATUS_URL="http://${APPIUM_HOST}:${APPIUM_PORT}/status"
+
+"$PROJECT_ROOT/node_modules/.bin/appium" --address "$APPIUM_HOST" --port "$APPIUM_PORT" &
+APPIUM_PID=$!
+
+cleanup() {
+  if kill -0 "$APPIUM_PID" 2>/dev/null; then
+    kill "$APPIUM_PID" 2>/dev/null || true
+    wait "$APPIUM_PID" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT INT TERM
+
+i=0
+while [ "$i" -lt 120 ]; do
+  # Appium can answer /status before the HTTP listener and drivers are fully ready;
+  # require JSON "ready":true so new sessions are accepted reliably.
+  if curl -sf "$STATUS_URL" | grep -q '"ready":true'; then
+    break
+  fi
+  i=$((i + 1))
+  sleep 1
+done
+
+if ! curl -sf "$STATUS_URL" | grep -q '"ready":true'; then
+  echo "Appium did not become ready at $STATUS_URL" >&2
+  exit 1
+fi
+
+# Brief settle after ready flag (driver init / listener wiring).
+sleep 2
+
+node "$PROJECT_ROOT/tests/mcp-android-login-smoke.mjs"

package/template/src/env/buildEnv.test.ts

@@ -0,0 +1,126 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  buildEnv,
+  requireCloudCredentialsFrom,
+} from "./buildEnv.ts";
+
+const cwd = "/project/root";
+
+describe("buildEnv", () => {
+  it("uses defaults when vars are empty", () => {
+    const e = buildEnv({}, cwd);
+    expect(e.appiumHost).toBe("127.0.0.1");
+    expect(e.appiumPort).toBe(4723);
+    expect(e.artifactsDir).toBe("./artifacts");
+    expect(e.mobileUsername).toBe("test@webdriver.io");
+    expect(e.mobilePassword).toBe("Test1234!");
+    expect(e.buildName).toBe("wdio-mobile");
+    expect(e.cloudHostname).toBe("mobile-hub.lambdatest.com");
+    expect(e.cloudPath).toBe("/wd/hub");
+    expect(e.android.deviceName).toBe("Android Emulator");
+    expect(e.android.udid).toBe("");
+    expect(e.android.appPath).toBe(
+      resolve(cwd, "apps/android.wdio.native.app.v2.0.0.apk"),
+    );
+    expect(e.android.cloudDevice).toBe("Galaxy S24");
+    expect(e.android.cloudPlatformVersion).toBe("14");
+    expect(e.android.cloudApp).toBe("");
+    expect(e.ios.deviceName).toBe("iPhone 15");
+    expect(e.ios.appPath).toBe(resolve(cwd, "apps/ios-demo.app"));
+    expect(e.ios.bundleId).toBe("com.example.demo");
+    expect(e.ios.cloudDevice).toBe("iPhone 15");
+    expect(e.ios.cloudPlatformVersion).toBe("17");
+    expect(e.ios.cloudApp).toBe("");
+    expect(e.cloudUsername).toBe("");
+    expect(e.cloudAccessKey).toBe("");
+  });
+
+  it("reads explicit vars and resolves app paths", () => {
+    const e = buildEnv(
+      {
+        APPIUM_HOST: "10.0.0.2",
+        APPIUM_PORT: "9000",
+        ARTIFACTS_DIR: "./out",
+        MOBILE_USERNAME: "u@x.com",
+        MOBILE_PASSWORD: "secret",
+        BUILD_NAME: "ci-1",
+        CLOUD_USERNAME: "cu",
+        CLOUD_ACCESS_KEY: "ck",
+        CLOUD_HOSTNAME: "hub.example.com",
+        CLOUD_PATH: "/hub",
+        ANDROID_DEVICE_NAME: "Pixel",
+        ANDROID_UDID: "emulator-5554",
+        ANDROID_APP_PATH: "./custom/app.apk",
+        ANDROID_CLOUD_DEVICE: "Nexus",
+        ANDROID_CLOUD_PLATFORM_VERSION: "15",
+        ANDROID_CLOUD_APP: "lt://android-app",
+        IOS_DEVICE_NAME: "iPhone 16",
+        IOS_APP_PATH: "./build/My.app",
+        IOS_BUNDLE_ID: "com.app.id",
+        IOS_CLOUD_DEVICE: "iPhone 14",
+        IOS_CLOUD_PLATFORM_VERSION: "16",
+        IOS_CLOUD_APP: "lt://ios-app",
+      },
+      cwd,
+    );
+    expect(e.appiumHost).toBe("10.0.0.2");
+    expect(e.appiumPort).toBe(9000);
+    expect(e.artifactsDir).toBe("./out");
+    expect(e.mobileUsername).toBe("u@x.com");
+    expect(e.mobilePassword).toBe("secret");
+    expect(e.buildName).toBe("ci-1");
+    expect(e.cloudUsername).toBe("cu");
+    expect(e.cloudAccessKey).toBe("ck");
+    expect(e.cloudHostname).toBe("hub.example.com");
+    expect(e.cloudPath).toBe("/hub");
+    expect(e.android.deviceName).toBe("Pixel");
+    expect(e.android.udid).toBe("emulator-5554");
+    expect(e.android.appPath).toBe(resolve(cwd, "custom/app.apk"));
+    expect(e.android.cloudDevice).toBe("Nexus");
+    expect(e.android.cloudPlatformVersion).toBe("15");
+    expect(e.android.cloudApp).toBe("lt://android-app");
+    expect(e.ios.deviceName).toBe("iPhone 16");
+    expect(e.ios.appPath).toBe(resolve(cwd, "build/My.app"));
+    expect(e.ios.bundleId).toBe("com.app.id");
+    expect(e.ios.cloudDevice).toBe("iPhone 14");
+    expect(e.ios.cloudPlatformVersion).toBe("16");
+    expect(e.ios.cloudApp).toBe("lt://ios-app");
+  });
+
+  it("falls back APPIUM_PORT when not a finite number", () => {
+    expect(buildEnv({ APPIUM_PORT: "nope" }, cwd).appiumPort).toBe(4723);
+    expect(buildEnv({ APPIUM_PORT: "Infinity" }, cwd).appiumPort).toBe(4723);
+    expect(buildEnv({ APPIUM_PORT: "12.5" }, cwd).appiumPort).toBe(12.5);
+  });
+
+  it("uses default Android APK when ANDROID_APP_PATH is empty string", () => {
+    const e = buildEnv({ ANDROID_APP_PATH: "" }, cwd);
+    expect(e.android.appPath).toBe(
+      resolve(cwd, "apps/android.wdio.native.app.v2.0.0.apk"),
+    );
+  });
+});
+
+describe("requireCloudCredentialsFrom", () => {
+  it("returns user and key when set", () => {
+    expect(
+      requireCloudCredentialsFrom({
+        CLOUD_USERNAME: "user",
+        CLOUD_ACCESS_KEY: "key",
+      }),
+    ).toEqual({ user: "user", key: "key" });
+  });
+
+  it("throws when CLOUD_USERNAME is missing", () => {
+    expect(() =>
+      requireCloudCredentialsFrom({ CLOUD_ACCESS_KEY: "k" }),
+    ).toThrowError("Missing required environment variable: CLOUD_USERNAME");
+  });
+
+  it("throws when CLOUD_ACCESS_KEY is missing", () => {
+    expect(() =>
+      requireCloudCredentialsFrom({ CLOUD_USERNAME: "u" }),
+    ).toThrowError("Missing required environment variable: CLOUD_ACCESS_KEY");
+  });
+});

package/template/src/env/buildEnv.ts

@@ -0,0 +1,81 @@
+import { resolve } from "node:path";
+
+const optional = (
+  vars: NodeJS.ProcessEnv,
+  name: string,
+  fallback = "",
+): string => vars[name] ?? fallback;
+
+const required = (vars: NodeJS.ProcessEnv, name: string): string => {
+  const value = vars[name];
+  if (!value) throw new Error(`Missing required environment variable: ${name}`);
+  return value;
+};
+
+const toNumber = (value: string, fallback: number): number => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+export type MobileEnv = ReturnType<typeof buildEnv>;
+
+/** Build env from a process-like map (testable; no dotenv). */
+export function buildEnv(
+  vars: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+) {
+  return {
+    appiumHost: optional(vars, "APPIUM_HOST", "127.0.0.1"),
+    appiumPort: toNumber(optional(vars, "APPIUM_PORT", "4723"), 4723),
+    artifactsDir: optional(vars, "ARTIFACTS_DIR", "./artifacts"),
+    mobileUsername: optional(vars, "MOBILE_USERNAME", "test@webdriver.io"),
+    mobilePassword: optional(vars, "MOBILE_PASSWORD", "Test1234!"),
+
+    buildName: optional(vars, "BUILD_NAME", "wdio-mobile"),
+    cloudUsername: optional(vars, "CLOUD_USERNAME"),
+    cloudAccessKey: optional(vars, "CLOUD_ACCESS_KEY"),
+    cloudHostname: optional(vars, "CLOUD_HOSTNAME", "mobile-hub.lambdatest.com"),
+    cloudPath: optional(vars, "CLOUD_PATH", "/wd/hub"),
+
+    android: {
+      deviceName: optional(vars, "ANDROID_DEVICE_NAME", "Android Emulator"),
+      udid: optional(vars, "ANDROID_UDID"),
+      appPath: (() => {
+        const p = optional(vars, "ANDROID_APP_PATH");
+        return p
+          ? resolve(cwd, p)
+          : resolve(cwd, "apps/android.wdio.native.app.v2.0.0.apk");
+      })(),
+      cloudDevice: optional(vars, "ANDROID_CLOUD_DEVICE", "Galaxy S24"),
+      cloudPlatformVersion: optional(
+        vars,
+        "ANDROID_CLOUD_PLATFORM_VERSION",
+        "14",
+      ),
+      cloudApp: optional(vars, "ANDROID_CLOUD_APP"),
+    },
+
+    ios: {
+      deviceName: optional(vars, "IOS_DEVICE_NAME", "iPhone 15"),
+      appPath: (() => {
+        const p = optional(vars, "IOS_APP_PATH", "./apps/ios-demo.app");
+        return resolve(cwd, p);
+      })(),
+      bundleId: optional(vars, "IOS_BUNDLE_ID", "com.example.demo"),
+      cloudDevice: optional(vars, "IOS_CLOUD_DEVICE", "iPhone 15"),
+      cloudPlatformVersion: optional(
+        vars,
+        "IOS_CLOUD_PLATFORM_VERSION",
+        "17",
+      ),
+      cloudApp: optional(vars, "IOS_CLOUD_APP"),
+    },
+  };
+}
+
+export function requireCloudCredentialsFrom(vars: NodeJS.ProcessEnv) {
+  return {
+    user: required(vars, "CLOUD_USERNAME"),
+    key: required(vars, "CLOUD_ACCESS_KEY"),
+  };
+}

package/template/src/env.ts

@@ -0,0 +1,13 @@
+import "dotenv/config";
+import {
+  buildEnv,
+  requireCloudCredentialsFrom,
+} from "./env/buildEnv.ts";
+
+/** Central env for WDIO configs and specs. No hidden defaults beyond these. */
+export const env = buildEnv(process.env, process.cwd());
+
+export const requireCloudCredentials = () =>
+  requireCloudCredentialsFrom(process.env);
+
+export type { MobileEnv } from "./env/buildEnv.ts";

package/template/src/lib/safeFilePart.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { safeFilePart } from "./safeFilePart.ts";
+
+describe("safeFilePart", () => {
+  it("keeps alphanumerics underscore and hyphen", () => {
+    expect(safeFilePart("login-flow_ok")).toBe("login-flow_ok");
+  });
+
+  it("replaces other characters with single hyphen runs", () => {
+    expect(safeFilePart("a  b::c")).toBe("a-b-c");
+    expect(safeFilePart("foo---bar")).toBe("foo-bar");
+  });
+
+  it("handles empty string", () => {
+    expect(safeFilePart("")).toBe("");
+  });
+});

package/template/src/lib/safeFilePart.ts

@@ -0,0 +1,4 @@
+/** Sanitize a string for use as a single filename segment (screenshots, etc.). */
+export function safeFilePart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/-+/g, "-");
+}

package/template/src/locators/locators.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { loginLocators } from "./login.locators.ts";
+import { nativeAlertLocators } from "./nativeAlert.locators.ts";
+import { tabBarLocators } from "./tabBar.locators.ts";
+
+describe("loginLocators", () => {
+  it("has matching keys for android and ios", () => {
+    expect(Object.keys(loginLocators.android).sort()).toEqual(
+      Object.keys(loginLocators.ios).sort(),
+    );
+    expect(loginLocators.android.screenTitle).toContain("Login");
+    expect(loginLocators.android.signInButton).toBeTruthy();
+  });
+});
+
+describe("tabBarLocators", () => {
+  it("has home and login tabs for both platforms", () => {
+    expect(tabBarLocators.android.homeTab).toBe("~Home");
+    expect(tabBarLocators.android.loginTab).toBe("~Login");
+    expect(tabBarLocators.ios).toEqual(tabBarLocators.android);
+  });
+});
+
+describe("nativeAlertLocators", () => {
+  it("defines android title, message, and OK", () => {
+    expect(nativeAlertLocators.android.alertTitle).toContain("alert_title");
+    expect(nativeAlertLocators.android.alertMessage).toContain("message");
+    expect(nativeAlertLocators.android.okButton).toContain("OK");
+  });
+
+  it("defines ios alert predicate and OK accessibility id", () => {
+    expect(nativeAlertLocators.ios.alert).toContain("XCUIElementTypeAlert");
+    expect(nativeAlertLocators.ios.okButton).toBe("~OK");
+  });
+});

package/template/src/locators/login.locators.ts

@@ -0,0 +1,18 @@
+type PlatformLocators = Record<"android" | "ios", Record<string, string>>;
+
+export const loginLocators: PlatformLocators = {
+  android: {
+    screenTitle: "~Login-screen",
+    loginContainerButton: "~button-login-container",
+    usernameField: "~input-email",
+    passwordField: "~input-password",
+    signInButton: "~button-LOGIN",
+  },
+  ios: {
+    screenTitle: "~Login-screen",
+    loginContainerButton: "~button-login-container",
+    usernameField: "~input-email",
+    passwordField: "~input-password",
+    signInButton: "~button-LOGIN",
+  },
+};

package/template/src/locators/nativeAlert.locators.ts

@@ -0,0 +1,13 @@
+type PlatformLocators = Record<"android" | "ios", Record<string, string>>;
+
+export const nativeAlertLocators: PlatformLocators = {
+  android: {
+    alertTitle: '*//android.widget.TextView[@resource-id="com.wdiodemoapp:id/alert_title"]',
+    alertMessage: '*//android.widget.TextView[@resource-id="android:id/message"]',
+    okButton: '*//android.widget.Button[@text="OK"]',
+  },
+  ios: {
+    alert: "-ios predicate string:type == 'XCUIElementTypeAlert'",
+    okButton: "~OK",
+  },
+};

package/template/src/locators/tabBar.locators.ts

@@ -0,0 +1,12 @@
+type PlatformLocators = Record<"android" | "ios", Record<string, string>>;
+
+export const tabBarLocators: PlatformLocators = {
+  android: {
+    homeTab: "~Home",
+    loginTab: "~Login",
+  },
+  ios: {
+    homeTab: "~Home",
+    loginTab: "~Login",
+  },
+};

package/template/src/pages/Login.page.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { loginLocators } from "../locators/login.locators.ts";
+import { setupWdioTestContext } from "../test-utils/wdioTestGlobals.ts";
+import { LoginPage } from "./Login.page.ts";
+
+const L = loginLocators.android;
+
+describe("LoginPage", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("waitForDisplay waits on screen title", async () => {
+    setupWdioTestContext({ isAndroid: true, isIOS: false });
+    const page = new LoginPage();
+    await page.waitForDisplay();
+    const title = globalThis.$(L.screenTitle);
+    expect(title.waitForDisplayed).toHaveBeenCalledWith({ timeout: 20_000 });
+  });
+
+  it("openLoginForm waits then taps login container", async () => {
+    setupWdioTestContext({ isAndroid: true, isIOS: false });
+    const page = new LoginPage();
+    await page.openLoginForm();
+    expect(globalThis.$(L.loginContainerButton).click).toHaveBeenCalled();
+  });
+
+  it("login on Android sets credentials, dismisses keyboard via title tap, scrolls and taps sign in", async () => {
+    const { chainFor } = setupWdioTestContext({
+      isAndroid: true,
+      isIOS: false,
+    });
+    const page = new LoginPage();
+    await page.login("user@x.com", "pw");
+
+    expect(chainFor(L.usernameField).setValue).toHaveBeenCalledWith(
+      "user@x.com",
+    );
+    expect(chainFor(L.passwordField).setValue).toHaveBeenCalledWith("pw");
+    expect(chainFor(L.screenTitle).click).toHaveBeenCalled();
+    expect(chainFor(L.signInButton).scrollIntoView).toHaveBeenCalledWith({
+      scrollableElement: chainFor(L.screenTitle),
+    });
+    expect(chainFor(L.signInButton).click).toHaveBeenCalled();
+  });
+
+  it("login on iOS without keyboard skips title tap for keyboard dismissal", async () => {
+    const { chainFor } = setupWdioTestContext({
+      isAndroid: false,
+      isIOS: true,
+      keyboardShown: false,
+    });
+    const page = new LoginPage();
+    await page.login("a@b.co", "x");
+
+    expect(chainFor(L.usernameField).setValue).toHaveBeenCalled();
+    expect(chainFor(L.screenTitle).click).not.toHaveBeenCalled();
+    expect(chainFor(L.signInButton).click).toHaveBeenCalled();
+  });
+
+  it("login on iOS with keyboard taps title to dismiss", async () => {
+    const { chainFor } = setupWdioTestContext({
+      isAndroid: false,
+      isIOS: true,
+      keyboardShown: true,
+    });
+    const page = new LoginPage();
+    await page.login("a@b.co", "x");
+
+    expect(globalThis.driver.isKeyboardShown).toHaveBeenCalled();
+    expect(chainFor(L.screenTitle).click).toHaveBeenCalled();
+  });
+});

package/template/src/pages/Login.page.ts

@@ -0,0 +1,37 @@
+import { loginLocators } from "../locators/login.locators.ts";
+
+const platform = (): "android" | "ios" => (driver.isIOS ? "ios" : "android");
+
+const sel = (name: keyof (typeof loginLocators)["android"]): string =>
+  loginLocators[platform()][name];
+
+export class LoginPage {
+  async waitForDisplay(): Promise<void> {
+    await $(sel("screenTitle")).waitForDisplayed({ timeout: 20_000 });
+  }
+
+  async openLoginForm(): Promise<void> {
+    await this.waitForDisplay();
+    await $(sel("loginContainerButton")).click();
+  }
+
+  async login(username: string, password: string): Promise<void> {
+    await this.waitForDisplay();
+    await $(sel("usernameField")).setValue(username);
+    await $(sel("passwordField")).setValue(password);
+
+    // Android: avoid isKeyboardShown() — it shells out to `dumpsys input_method` (huge, slow, fails if adb/device flakes).
+    if (driver.isAndroid) {
+      await $(sel("screenTitle")).click();
+    } else if (await driver.isKeyboardShown()) {
+      await $(sel("screenTitle")).click();
+    }
+
+    await $(sel("signInButton")).scrollIntoView({
+      scrollableElement: await $(sel("screenTitle")),
+    });
+    await $(sel("signInButton")).click();
+  }
+}
+
+export const loginPage = new LoginPage();

package/template/src/pages/NativeAlert.page.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { nativeAlertLocators } from "../locators/nativeAlert.locators.ts";
+import {
+  setupWdioTestContext,
+  stubExpectWebdriverStyle,
+} from "../test-utils/wdioTestGlobals.ts";
+import { NativeAlertPage } from "./NativeAlert.page.ts";
+
+describe("NativeAlertPage", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("waitForDisplay on iOS waits for alert element", async () => {
+    setupWdioTestContext({ isAndroid: false, isIOS: true });
+    const page = new NativeAlertPage();
+    await page.waitForDisplay();
+    const alertSel = nativeAlertLocators.ios.alert;
+    expect(globalThis.$(alertSel).waitForExist).toHaveBeenCalledWith({
+      timeout: 11_000,
+    });
+  });
+
+  it("waitForDisplay on Android waits for alert title", async () => {
+    setupWdioTestContext({ isAndroid: true, isIOS: false });
+    const page = new NativeAlertPage();
+    await page.waitForDisplay();
+    const titleSel = nativeAlertLocators.android.alertTitle;
+    expect(globalThis.$(titleSel).waitForExist).toHaveBeenCalledWith({
+      timeout: 11_000,
+    });
+  });
+
+  describe("expectSuccessMessage", () => {
+    let toHaveText: ReturnType<typeof stubExpectWebdriverStyle>["toHaveText"];
+
+    beforeEach(() => {
+      ({ toHaveText } = stubExpectWebdriverStyle());
+    });
+
+    it("on iOS uses expect().toHaveText(stringContaining)", async () => {
+      setupWdioTestContext({ isAndroid: false, isIOS: true });
+      const page = new NativeAlertPage();
+      await page.expectSuccessMessage();
+      expect(toHaveText).toHaveBeenCalled();
+    });
+
+    it("on Android asserts title and message contain Success", async () => {
+      setupWdioTestContext({
+        isAndroid: true,
+        isIOS: false,
+      });
+      const titleSel = nativeAlertLocators.android.alertTitle;
+      const msgSel = nativeAlertLocators.android.alertMessage;
+      globalThis.$(titleSel);
+      globalThis.$(msgSel);
+      vi.mocked(globalThis.$(titleSel).getText).mockResolvedValue("Done");
+      vi.mocked(globalThis.$(msgSel).getText).mockResolvedValue(
+        "Success — logged in",
+      );
+      const page = new NativeAlertPage();
+      await expect(page.expectSuccessMessage()).resolves.toBeUndefined();
+    });
+
+    it("on Android throws when Success is absent", async () => {
+      setupWdioTestContext({
+        isAndroid: true,
+        isIOS: false,
+      });
+      const titleSel = nativeAlertLocators.android.alertTitle;
+      const msgSel = nativeAlertLocators.android.alertMessage;
+      globalThis.$(titleSel);
+      globalThis.$(msgSel);
+      vi.mocked(globalThis.$(titleSel).getText).mockResolvedValue("Nope");
+      vi.mocked(globalThis.$(msgSel).getText).mockResolvedValue("Try again");
+      const page = new NativeAlertPage();
+      await expect(page.expectSuccessMessage()).rejects.toThrow(
+        /Expected string to contain/,
+      );
+    });
+  });
+
+  it("confirm clicks OK for current platform", async () => {
+    setupWdioTestContext({ isAndroid: true, isIOS: false });
+    const page = new NativeAlertPage();
+    await page.confirm();
+    expect(
+      globalThis.$(nativeAlertLocators.android.okButton).click,
+    ).toHaveBeenCalled();
+  });
+});

package/template/src/pages/NativeAlert.page.ts

@@ -0,0 +1,35 @@
+import { nativeAlertLocators } from "../locators/nativeAlert.locators.ts";
+
+const platform = (): "android" | "ios" => (driver.isIOS ? "ios" : "android");
+
+export class NativeAlertPage {
+  async waitForDisplay(): Promise<void> {
+    if (driver.isIOS) {
+      await $(nativeAlertLocators[platform()].alert).waitForExist({ timeout: 11_000 });
+      return;
+    }
+
+    await $(nativeAlertLocators[platform()].alertTitle).waitForExist({
+      timeout: 11_000,
+    });
+  }
+
+  async expectSuccessMessage(): Promise<void> {
+    if (driver.isIOS) {
+      await expect($(nativeAlertLocators[platform()].alert)).toHaveText(
+        expect.stringContaining("Success"),
+      );
+      return;
+    }
+
+    const title = await $(nativeAlertLocators[platform()].alertTitle).getText();
+    const message = await $(nativeAlertLocators[platform()].alertMessage).getText();
+    expect(`${title}\n${message}`).toContain("Success");
+  }
+
+  async confirm(): Promise<void> {
+    await $(nativeAlertLocators[platform()].okButton).click();
+  }
+}
+
+export const nativeAlertPage = new NativeAlertPage();

package/template/src/pages/TabBar.page.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { tabBarLocators } from "../locators/tabBar.locators.ts";
+import { setupWdioTestContext } from "../test-utils/wdioTestGlobals.ts";
+import { TabBarPage } from "./TabBar.page.ts";
+
+const T = tabBarLocators.android;
+
+describe("TabBarPage", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("waitForDisplay waits on home tab", async () => {
+    setupWdioTestContext({ isAndroid: true, isIOS: false });
+    const page = new TabBarPage();
+    await page.waitForDisplay();
+    expect(globalThis.$(T.homeTab).waitForDisplayed).toHaveBeenCalledWith({
+      timeout: 20_000,
+    });
+  });
+
+  it("openLogin taps login tab after home is visible", async () => {
+    setupWdioTestContext({ isAndroid: true, isIOS: false });
+    const page = new TabBarPage();
+    await page.openLogin();
+    expect(globalThis.$(T.loginTab).click).toHaveBeenCalled();
+  });
+
+  it("uses iOS locators when driver.isIOS is true", async () => {
+    setupWdioTestContext({ isAndroid: false, isIOS: true });
+    const page = new TabBarPage();
+    await page.openLogin();
+    expect(globalThis.$(T.loginTab).click).toHaveBeenCalled();
+  });
+});

package/template/src/pages/TabBar.page.ts

@@ -0,0 +1,19 @@
+import { tabBarLocators } from "../locators/tabBar.locators.ts";
+
+const platform = (): "android" | "ios" => (driver.isIOS ? "ios" : "android");
+
+const sel = (name: keyof (typeof tabBarLocators)["android"]): string =>
+  tabBarLocators[platform()][name];
+
+export class TabBarPage {
+  async waitForDisplay(): Promise<void> {
+    await $(sel("homeTab")).waitForDisplayed({ timeout: 20_000 });
+  }
+
+  async openLogin(): Promise<void> {
+    await this.waitForDisplay();
+    await $(sel("loginTab")).click();
+  }
+}
+
+export const tabBarPage = new TabBarPage();