@allwright.dev/vitest 0.1.20 → 0.1.22

package/README.md

@@ -1,7 +1,7 @@
 # @allwright.dev/vitest
 
 Vitest fixtures for allwright with Playwright-style `browser` and `page`
-injection, plus Android and iOS mobile fixtures for native and hybrid tests.
+injection, plus Android, iOS, and macOS app 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.
 
@@ -40,9 +40,14 @@ test("opens an Android app", async ({ androidApp }) => {
 test("opens an iOS app", async ({ iosApp }) => {
   await iosApp.getByRole("button", { name: "Login", exact: true }).click();
 });
+
+test("opens a macOS app", async ({ macosApp }) => {
+  await macosApp.getByRole("button", { name: "New Document", exact: true }).click();
+});
 ```
 
-A checked-in example spec also lives in [examples/basic.spec.ts](./examples/basic.spec.ts).
+Checked-in example specs live in [examples/basic.spec.ts](./examples/basic.spec.ts)
+and [examples/ios-flights.spec.ts](./examples/ios-flights.spec.ts).
 
 The fixture package reads the shared stack-agnostic config format through `@allwright.dev/core`.
 Use `allwright.config.yaml` by default, or `allwright.config.json` if you prefer. Both follow the same root schema in `allwright.schema.json`.
@@ -139,11 +144,34 @@ test("logs in", async ({ iosApp }) => {
 });
 ```
 
+macOS apps use an installed application bundle identifier. The fixture starts
+the bundled desktop XCUITest runner and launches the configured app lazily:
+
+```yaml
+# allwright.config.yaml
+desktop:
+  mac:
+    app:
+      id: com.apple.TextEdit
+```
+
+```ts
+import { expect, test } from "@allwright.dev/vitest";
+
+test("opens a document window", async ({ macosApp }) => {
+  await macosApp.getByRole("button", { name: "New Document", exact: true }).click();
+  await expect(macosApp.getByRole("textField")).toBeVisible();
+});
+```
+
+Use `ALLWRIGHT_MAC_AGENT_ENDPOINT` for an external agent or
+`ALLWRIGHT_MAC_APP_ID` to override the configured bundle identifier.
+
 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.
+`androidApp`, `ios`, `iosApp`, `macos`, or `macosApp` 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:
 
@@ -153,11 +181,14 @@ Available fixtures:
 - `androidApp`: launched Android app page
 - `ios`: connected iOS device session
 - `iosApp`: launched iOS app page
+- `macos`: connected macOS desktop session
+- `macosApp`: launched macOS 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`.
+`macosApp` does the same with `allwright.macos.launchOptions` and `config.desktop.mac`.
 
-Android and iOS apps and locators support the mobile action and expectation
+Android, iOS, and macOS apps and locators support the native 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

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 MobileIosConnectOptions, type MobileIosDevice, type MobileIosLaunchOptions, type MobileIosApp, 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 DesktopMacApp, type DesktopMacConnectOptions, type DesktopMacDesktop, type DesktopMacLaunchOptions, 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;
@@ -15,6 +15,10 @@ export interface AllwrightVitestOptions {
         connectOptions?: MobileIosConnectOptions;
         launchOptions?: MobileIosLaunchOptions;
     };
+    macos?: {
+        connectOptions?: DesktopMacConnectOptions;
+        launchOptions?: DesktopMacLaunchOptions;
+    };
     configFile?: string;
     suite?: string;
 }
@@ -25,6 +29,8 @@ export interface AllwrightVitestFixtures {
     androidApp: MobileAndroidApp;
     ios: MobileIosDevice;
     iosApp: MobileIosApp;
+    macos: DesktopMacDesktop;
+    macosApp: DesktopMacApp;
 }
 interface LazyResource<T> {
     peek(): T | null;
@@ -38,10 +44,13 @@ export declare const test: import("vitest").TestAPI<{
     androidApp: MobileAndroidApp;
     ios: MobileIosDevice;
     iosApp: MobileAndroidApp;
+    macos: DesktopMacDesktop;
+    macosApp: MobileAndroidApp;
     allwright: AllwrightVitestOptions;
     _browserResource: LazyResource<Browser>;
     _androidResource: LazyResource<MobileAndroidDevice>;
     _iosResource: LazyResource<MobileIosDevice>;
+    _macosResource: LazyResource<DesktopMacDesktop>;
 }>;
 type VitestExpect = typeof vitestExpect;
 interface AllwrightExpect extends VitestExpect {

package/dist/index.js

@@ -1,10 +1,12 @@
 import { createLocatorExpect, createPageExpect } from "./expectations.js";
-import { launchConfiguredBrowser, mobile, resolveConfig, setServerAddr, } from "@allwright.dev/core";
+import { launchConfiguredBrowser, desktop, mobile, resolveConfig, setServerAddr, } from "@allwright.dev/core";
 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;
+const DEFAULT_MACOS_CONNECT_TIMEOUT_MS = 30_000;
+const DEFAULT_MACOS_LAUNCH_TIMEOUT_MS = 60_000;
 function createLazyResource(factory) {
     let value = null;
     let promise = null;
@@ -479,6 +481,20 @@ function createLazyIosDevice(deviceResource) {
         },
     };
 }
+function createLazyMacosDesktop(desktopResource) {
+    const initialAppResource = createLazyResource(async () => (await desktopResource.get()).app());
+    return {
+        get sessionId() {
+            return getLazySyncProperty(desktopResource, "sessionId");
+        },
+        app() {
+            return createLazyMobileApp(initialAppResource);
+        },
+        async launch(options) {
+            return (await desktopResource.get()).launch(options);
+        },
+    };
+}
 export const test = base.extend({
     allwright: async ({}, use) => {
         await use({});
@@ -516,6 +532,14 @@ export const test = base.extend({
         const iosResource = createLazyResource(async () => mobile.ios.connect(resolveIosConnectOptions(config, allwright)));
         await use(iosResource);
     },
+    _macosResource: async ({ allwright }, use) => {
+        const config = resolveVitestConfig(allwright);
+        if (config.serverAddr) {
+            setServerAddr(config.serverAddr);
+        }
+        const macosResource = createLazyResource(async () => desktop.mac.connect(resolveMacosConnectOptions(config, allwright)));
+        await use(macosResource);
+    },
     browser: async ({ _browserResource }, use) => {
         try {
             await use(createLazyBrowser(_browserResource));
@@ -549,6 +573,17 @@ export const test = base.extend({
         });
         await use(createLazyMobileApp(appResource));
     },
+    macos: async ({ _macosResource }, use) => {
+        await use(createLazyMacosDesktop(_macosResource));
+    },
+    macosApp: async ({ _macosResource, allwright }, use) => {
+        const appResource = createLazyResource(async () => {
+            const config = resolveVitestConfig(allwright);
+            const launchOptions = resolveMacosLaunchOptions(config, allwright);
+            return (await _macosResource.get()).launch(launchOptions);
+        });
+        await use(createLazyMobileApp(appResource));
+    },
 });
 function isPage(value) {
     return !!value && typeof value === "object" && typeof value.locator === "function";
@@ -632,6 +667,28 @@ function resolveIosLaunchOptions(config, options) {
     }
     return launchOptions;
 }
+function resolveMacosConnectOptions(config, options) {
+    return {
+        agentEndpoint: options.macos?.connectOptions?.agentEndpoint ??
+            process.env.ALLWRIGHT_MAC_AGENT_ENDPOINT,
+        timeoutMs: options.macos?.connectOptions?.timeoutMs ??
+            DEFAULT_MACOS_CONNECT_TIMEOUT_MS,
+    };
+}
+function resolveMacosLaunchOptions(config, options) {
+    const appId = options.macos?.launchOptions?.appId ??
+        process.env.ALLWRIGHT_MAC_APP_ID ??
+        config.desktop.mac?.appId;
+    if (!appId) {
+        throw new Error("macosApp fixture requires macOS launch options with `appId`, or config.desktop.mac.app configured");
+    }
+    return {
+        appId,
+        terminateRunning: options.macos?.launchOptions?.terminateRunning ?? false,
+        timeoutMs: options.macos?.launchOptions?.timeoutMs ??
+            DEFAULT_MACOS_LAUNCH_TIMEOUT_MS,
+    };
+}
 let activeExpectDefaults = {};
 function currentExpectDefaults() {
     return activeExpectDefaults;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allwright.dev/vitest",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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.20"
+    "@allwright.dev/core": "0.1.22"
   },
   "devDependencies": {
     "typescript": "^5.9.2",