@allwright.dev/vitest 0.1.15 → 0.1.16

package/README.md

@@ -1,6 +1,7 @@
 # @allwright.dev/vitest
 
-Vitest fixtures for allwright with Playwright-style `browser` and `page` injection, plus Android mobile fixtures for hybrid tests.
+Vitest fixtures for allwright with Playwright-style `browser` and `page`
+injection, plus Android and iOS mobile fixtures for native and hybrid tests.
 
 Wrap the Vitest configuration with `allwrightVitestConfig`. It starts Allwright once before workers run and shuts it down once after the complete test run. Existing user global setup files remain supported and run after Allwright starts, then tear down before Allwright stops.
 
@@ -35,6 +36,10 @@ test("opens a page", async ({ page }) => {
 test("opens an Android app", async ({ androidApp }) => {
   await androidApp.click('Id=com.example.airticket:id/bottom_nav_account');
 });
+
+test("opens an iOS app", async ({ iosApp }) => {
+  await iosApp.locator("text=Login").click();
+});
 ```
 
 A checked-in example spec also lives in [examples/basic.spec.ts](./examples/basic.spec.ts).
@@ -105,7 +110,40 @@ test("hybrid web and android", async ({ page, androidApp }) => {
 });
 ```
 
-Fixtures are lazy on first use. Injecting `browser`, `page`, `android`, or `androidApp` does not launch or connect immediately; the underlying session is created only when the test first performs an action through that fixture. Sync metadata properties like `browser.sessionId` or `android.sessionId` are only available after the lazy fixture has been realized by a prior awaited call.
+iOS uses the same app and locator shape. Configure the native agent endpoint
+and bundle identifier once, then keep platform bootstrap out of test bodies:
+
+```yaml
+# allwright.config.yaml
+mobile:
+  ios:
+    device: iPhone 17 Pro
+    app:
+      binary: https://allwright.dev/Flights-simulator.ipa
+```
+
+Set `ALLWRIGHT_IOS_AGENT_ENDPOINT` when the agent is not reachable at
+`http://127.0.0.1:8100`. The app value may also be a local `.app`, `.zip`, or
+`.ipa`; the fixture downloads/extracts it when needed, installs it on the
+selected simulator, derives its bundle identifier, and launches it. Override
+it with `ALLWRIGHT_IOS_APP_PATH`. No manual installation or polling belongs in
+the test. The test remains platform-client code only:
+
+```ts
+import { expect, test } from "@allwright.dev/vitest";
+
+test("logs in", async ({ iosApp }) => {
+  await iosApp.locator("text=Login").click();
+  await iosApp.locator("className=XCUIElementTypeTextField").fill("user@example.com");
+  await expect(iosApp.locator("text=Welcome back")).toBeVisible();
+});
+```
+
+Fixtures are lazy on first use. Injecting `browser`, `page`, `android`,
+`androidApp`, `ios`, or `iosApp` does not launch or connect immediately; the
+underlying session is created only when the test first performs an action
+through that fixture. Sync metadata properties are only available after the
+lazy fixture has been realized by a prior awaited call.
 
 Available fixtures:
 
@@ -113,10 +151,17 @@ Available fixtures:
 - `page`: initial web page
 - `android`: connected Android device session
 - `androidApp`: launched Android app page
+- `ios`: connected iOS device session
+- `iosApp`: launched iOS app page
 
 `androidApp` launches using `allwright.android.launchOptions` first, then falls back to `config.mobile.android`.
+`iosApp` does the same with `allwright.ios.launchOptions` and `config.mobile.ios`.
 
-Android apps and locators support the Android-applicable action and expectation subset: `click`, `count`, `focus`, `fill`, `press`, `textContent`, `innerText`, `waitForSelector`, and `screenshot`. `expect(androidApp)` and `expect(androidApp.locator(...))` provide `toHaveText`, `toContainText`, `toHaveCount`, and `toBeVisible` with the same retry controls as web fixtures. Hover and highlight remain web-only.
+Android and iOS apps and locators support the mobile action and expectation
+subset: `click`, `count`, `focus`, `fill`, `press`, `textContent`, `innerText`,
+`waitForSelector`, and `screenshot`. Mobile expectations provide `toHaveText`,
+`toContainText`, `toHaveCount`, and `toBeVisible` with the same retry controls
+as web fixtures. Hover and highlight remain web-only.
 
 The opt-in accessibility integration test exercises the public page fixture,
 bundled protobuf, running engine and dynamically loaded web plugin. From this

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { PageExpectMatchers, LocatorExpectMatchers, MobilePageExpectMatchers, MobileLocatorExpectMatchers } from "./expectations.js";
 export type { RetryExpectationOptions, TextExpectationOptions, VisibleExpectationOptions, SelectedOptionExpectation, PageExpectMatchers, LocatorExpectMatchers, MobilePageExpectMatchers, MobileLocatorExpectMatchers } from "./expectations.js";
-import { type MobileAndroidConnectOptions, type MobileAndroidDevice, type MobileAndroidLaunchOptions, type MobileAndroidApp, type Browser, type BrowserKind, type LaunchOptions, type Locator, type MobileAndroidLocator, type Page } from "@allwright.dev/core";
+import { type MobileAndroidConnectOptions, type MobileAndroidDevice, type MobileAndroidLaunchOptions, type MobileAndroidApp, type MobileIosConnectOptions, type MobileIosDevice, type MobileIosLaunchOptions, type MobileIosApp, type Browser, type BrowserKind, type LaunchOptions, type Locator, type MobileAndroidLocator, type Page } from "@allwright.dev/core";
 import { expect as vitestExpect, type Assertion } from "vitest";
 export interface AllwrightVitestOptions {
     launchOptions?: LaunchOptions;
@@ -11,6 +11,10 @@ export interface AllwrightVitestOptions {
         connectOptions?: MobileAndroidConnectOptions;
         launchOptions?: MobileAndroidLaunchOptions;
     };
+    ios?: {
+        connectOptions?: MobileIosConnectOptions;
+        launchOptions?: MobileIosLaunchOptions;
+    };
     configFile?: string;
     suite?: string;
 }
@@ -19,6 +23,8 @@ export interface AllwrightVitestFixtures {
     page: Page;
     android: MobileAndroidDevice;
     androidApp: MobileAndroidApp;
+    ios: MobileIosDevice;
+    iosApp: MobileIosApp;
 }
 interface LazyResource<T> {
     peek(): T | null;
@@ -30,9 +36,12 @@ export declare const test: import("vitest").TestAPI<{
     page: Page;
     android: MobileAndroidDevice;
     androidApp: MobileAndroidApp;
+    ios: MobileIosDevice;
+    iosApp: MobileAndroidApp;
     allwright: AllwrightVitestOptions;
     _browserResource: LazyResource<Browser>;
     _androidResource: LazyResource<MobileAndroidDevice>;
+    _iosResource: LazyResource<MobileIosDevice>;
 }>;
 type VitestExpect = typeof vitestExpect;
 interface AllwrightExpect extends VitestExpect {

package/dist/index.js

@@ -3,6 +3,8 @@ import { launchConfiguredBrowser, mobile, resolveConfig, setServerAddr, } from "
 import { expect as vitestExpect, test as base } from "vitest";
 const DEFAULT_ANDROID_CONNECT_TIMEOUT_MS = 30_000;
 const DEFAULT_ANDROID_LAUNCH_TIMEOUT_MS = 60_000;
+const DEFAULT_IOS_CONNECT_TIMEOUT_MS = 30_000;
+const DEFAULT_IOS_LAUNCH_TIMEOUT_MS = 60_000;
 function createLazyResource(factory) {
     let value = null;
     let promise = null;
@@ -330,13 +332,13 @@ function createLazyBrowser(browserResource) {
     };
     return lazyBrowser;
 }
-function createLazyAndroidApp(appResource) {
+function createLazyMobileApp(appResource) {
     const lazyApp = {
         get sessionId() {
             return getLazySyncProperty(appResource, "sessionId");
         },
         locator(selector) {
-            return createLazyAndroidLocator(appResource, async () => selector);
+            return createLazyMobileLocator(appResource, async () => selector);
         },
         async registerHook(type) {
             return (await appResource.get()).registerHook(type);
@@ -374,13 +376,13 @@ function createLazyAndroidApp(appResource) {
     };
     return lazyApp;
 }
-function createLazyAndroidLocator(appResource, selectorFactory) {
+function createLazyMobileLocator(appResource, selectorFactory) {
     const lazyLocator = {
         get page() {
-            return createLazyAndroidApp(appResource);
+            return createLazyMobileApp(appResource);
         },
         get selector() {
-            throw new Error("lazy Android locator selector is not available before the app fixture is initialized");
+            throw new Error("lazy mobile locator selector is not available before the app fixture is initialized");
         },
         async click(options) {
             return (await appResource.get()).locator(await selectorFactory()).click(options);
@@ -407,7 +409,7 @@ function createLazyAndroidLocator(appResource, selectorFactory) {
             return (await appResource.get()).locator(await selectorFactory()).waitFor(options);
         },
         locator(selector) {
-            return createLazyAndroidLocator(appResource, async () => (await appResource.get()).locator(await selectorFactory()).locator(selector).selector);
+            return createLazyMobileLocator(appResource, async () => (await appResource.get()).locator(await selectorFactory()).locator(selector).selector);
         },
     };
     return lazyLocator;
@@ -419,10 +421,10 @@ function createLazyAndroidDevice(deviceResource) {
             return getLazySyncProperty(deviceResource, "sessionId");
         },
         app() {
-            return createLazyAndroidApp(initialAppResource);
+            return createLazyMobileApp(initialAppResource);
         },
         initialApp() {
-            return createLazyAndroidApp(initialAppResource);
+            return createLazyMobileApp(initialAppResource);
         },
         async launch(options) {
             return (await deviceResource.get()).launch(options);
@@ -430,6 +432,23 @@ function createLazyAndroidDevice(deviceResource) {
     };
     return lazyDevice;
 }
+function createLazyIosDevice(deviceResource) {
+    const initialAppResource = createLazyResource(async () => (await deviceResource.get()).app());
+    return {
+        get sessionId() {
+            return getLazySyncProperty(deviceResource, "sessionId");
+        },
+        app() {
+            return createLazyMobileApp(initialAppResource);
+        },
+        initialApp() {
+            return createLazyMobileApp(initialAppResource);
+        },
+        async launch(options) {
+            return (await deviceResource.get()).launch(options);
+        },
+    };
+}
 export const test = base.extend({
     allwright: async ({}, use) => {
         await use({});
@@ -459,6 +478,14 @@ export const test = base.extend({
         const androidResource = createLazyResource(async () => mobile.android.connect(resolveAndroidConnectOptions(config, allwright)));
         await use(androidResource);
     },
+    _iosResource: async ({ allwright }, use) => {
+        const config = resolveVitestConfig(allwright);
+        if (config.serverAddr) {
+            setServerAddr(config.serverAddr);
+        }
+        const iosResource = createLazyResource(async () => mobile.ios.connect(resolveIosConnectOptions(config, allwright)));
+        await use(iosResource);
+    },
     browser: async ({ _browserResource }, use) => {
         try {
             await use(createLazyBrowser(_browserResource));
@@ -479,7 +506,18 @@ export const test = base.extend({
             const launchOptions = resolveAndroidLaunchOptions(config, allwright);
             return (await _androidResource.get()).launch(launchOptions);
         });
-        await use(createLazyAndroidApp(appResource));
+        await use(createLazyMobileApp(appResource));
+    },
+    ios: async ({ _iosResource }, use) => {
+        await use(createLazyIosDevice(_iosResource));
+    },
+    iosApp: async ({ _iosResource, allwright }, use) => {
+        const appResource = createLazyResource(async () => {
+            const config = resolveVitestConfig(allwright);
+            const launchOptions = resolveIosLaunchOptions(config, allwright);
+            return (await _iosResource.get()).launch(launchOptions);
+        });
+        await use(createLazyMobileApp(appResource));
     },
 });
 function isPage(value) {
@@ -498,7 +536,7 @@ function resolveVitestConfig(options) {
     });
     return {
         ...config,
-        serverAddr: options.serverAddr ?? config.serverAddr,
+        serverAddr: options.serverAddr ?? process.env.ALLWRIGHT_SERVER_ADDR ?? config.serverAddr,
         browserName: options.browser ?? config.browserName,
         browserBinary: options.browserBinary ?? config.browserBinary,
         launchOptions: {
@@ -535,6 +573,35 @@ function resolveAndroidLaunchOptions(config, options) {
     }
     return launchOptions;
 }
+function resolveIosConnectOptions(config, options) {
+    return {
+        device: options.ios?.connectOptions?.device ??
+            process.env.ALLWRIGHT_IOS_DEVICE ??
+            config.mobile.ios?.device,
+        agentEndpoint: options.ios?.connectOptions?.agentEndpoint ??
+            process.env.ALLWRIGHT_IOS_AGENT_ENDPOINT,
+        preserveAppState: options.ios?.connectOptions?.preserveAppState ?? false,
+        timeoutMs: options.ios?.connectOptions?.timeoutMs ??
+            DEFAULT_IOS_CONNECT_TIMEOUT_MS,
+    };
+}
+function resolveIosLaunchOptions(config, options) {
+    const launchOptions = {
+        appPath: options.ios?.launchOptions?.appPath ??
+            process.env.ALLWRIGHT_IOS_APP_PATH ??
+            config.mobile.ios?.appBinary,
+        appId: options.ios?.launchOptions?.appId ??
+            process.env.ALLWRIGHT_IOS_APP_ID ??
+            config.mobile.ios?.appId,
+        stopBeforeLaunch: options.ios?.launchOptions?.stopBeforeLaunch ?? false,
+        timeoutMs: options.ios?.launchOptions?.timeoutMs ??
+            DEFAULT_IOS_LAUNCH_TIMEOUT_MS,
+    };
+    if (!launchOptions.appPath && !launchOptions.appId) {
+        throw new Error("iosApp fixture requires iOS launch options with `appPath` or `appId`, or config.mobile.ios.app configured");
+    }
+    return launchOptions;
+}
 let activeExpectDefaults = {};
 function currentExpectDefaults() {
     return activeExpectDefaults;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allwright.dev/vitest",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Vitest fixtures for the allwright TypeScript client.",
   "license": "MIT",
   "type": "module",
@@ -47,7 +47,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@allwright.dev/core": "0.1.15"
+    "@allwright.dev/core": "0.1.16"
   },
   "devDependencies": {
     "typescript": "^5.9.2",