@allwright.dev/vitest 0.1.22 → 0.1.24

package/README.md

@@ -1,7 +1,7 @@
 # @allwright.dev/vitest
 
 Vitest fixtures for allwright with Playwright-style `browser` and `page`
-injection, plus Android, iOS, and macOS app fixtures for native and hybrid tests.
+injection, plus Android, iOS, macOS, and Windows 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.
 
@@ -44,10 +44,19 @@ test("opens an iOS app", async ({ iosApp }) => {
 test("opens a macOS app", async ({ macosApp }) => {
   await macosApp.getByRole("button", { name: "New Document", exact: true }).click();
 });
+
+test("opens a Windows app", async ({ windowsApp }) => {
+  await windowsApp.getByRole("textbox").fill("Hello from Allwright");
+});
 ```
 
-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).
+Checked-in example specs cover every implemented surface:
+[Web](./examples/basic.spec.ts), [Android](./examples/android-flights.spec.ts),
+[iOS](./examples/ios-flights.spec.ts),
+[macOS](./examples/macos-calculator.spec.ts), and
+[Windows](./examples/windows-notepad.spec.ts). Native specs use the app target
+configured for their surface in `allwright.config.yaml` or
+`allwright.config.json`.
 
 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`.
@@ -167,11 +176,35 @@ test("opens a document window", async ({ macosApp }) => {
 Use `ALLWRIGHT_MAC_AGENT_ENDPOINT` for an external agent or
 `ALLWRIGHT_MAC_APP_ID` to override the configured bundle identifier.
 
+Windows apps use an executable path, command name, or packaged-app AUMID. The
+fixture starts the bundled FlaUI UIA3 agent and launches the app lazily:
+
+```yaml
+# allwright.config.yaml
+desktop:
+  windows:
+    app:
+      id: notepad.exe
+```
+
+```ts
+import { expect, test } from "@allwright.dev/vitest";
+
+test("edits a document", async ({ windowsApp }) => {
+  await windowsApp.getByRole("textbox").fill("Hello from Allwright");
+  await expect(windowsApp.getByRole("textbox")).toContainText("Hello");
+});
+```
+
+Use `ALLWRIGHT_WINDOWS_AGENT_ENDPOINT` for an external agent or
+`ALLWRIGHT_WINDOWS_APP_ID` to override the configured application identifier.
+
 Fixtures are lazy on first use. Injecting `browser`, `page`, `android`,
-`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.
+`androidApp`, `ios`, `iosApp`, `macos`, `macosApp`, `windows`, or `windowsApp`
+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:
 
@@ -183,13 +216,16 @@ Available fixtures:
 - `iosApp`: launched iOS app page
 - `macos`: connected macOS desktop session
 - `macosApp`: launched macOS app page
+- `windows`: connected Windows desktop session
+- `windowsApp`: launched Windows 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`.
+`windowsApp` does the same with `allwright.windows.launchOptions` and `config.desktop.windows`.
 
-Android, iOS, and macOS apps and locators support the native action and expectation
-subset: `click`, `count`, `focus`, `fill`, `press`, `textContent`, `innerText`,
+Android, iOS, macOS, and Windows 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
 as web fixtures. Hover and highlight remain web-only.

package/dist/expectations.d.ts

@@ -1,4 +1,4 @@
-import type { BoundingBox, CommandOptions, Locator, MobileAndroidApp, MobileAndroidLocator, Page, WaitForSelectorOptions } from "@allwright.dev/core";
+import type { BoundingBox, CommandOptions, Locator, NativeApp, NativeAppLocator, Page, WaitForSelectorOptions } from "@allwright.dev/core";
 export interface RetryExpectationOptions {
     timeoutMs?: number;
     intervalMs?: number;
@@ -48,11 +48,11 @@ export interface PageExpectMatchers extends MobilePageExpectMatchers {
     toHaveBoundingBox(selector: string, expected: Partial<BoundingBox> | null, options?: TextExpectationOptions): Promise<void>;
 }
 type Defaults = () => RetryExpectationOptions;
-type AnyLocator = Locator | MobileAndroidLocator;
+type AnyLocator = Locator | NativeAppLocator;
 export declare function createLocatorExpect(locator: Locator, defaults: Defaults, negated?: boolean): LocatorExpectMatchers;
-export declare function createLocatorExpect(locator: MobileAndroidLocator, defaults: Defaults, negated?: boolean): MobileLocatorExpectMatchers;
+export declare function createLocatorExpect(locator: NativeAppLocator, defaults: Defaults, negated?: boolean): MobileLocatorExpectMatchers;
 export declare function createLocatorExpect(locator: AnyLocator, defaults: Defaults, negated?: boolean): MobileLocatorExpectMatchers;
 export declare function createPageExpect(page: Page, defaults: Defaults, negated?: boolean): PageExpectMatchers;
-export declare function createPageExpect(page: MobileAndroidApp, defaults: Defaults, negated?: boolean): MobilePageExpectMatchers;
-export declare function createPageExpect(page: Page | MobileAndroidApp, defaults: Defaults, negated?: boolean): MobilePageExpectMatchers;
+export declare function createPageExpect(page: NativeApp, defaults: Defaults, negated?: boolean): MobilePageExpectMatchers;
+export declare function createPageExpect(page: Page | NativeApp, defaults: Defaults, negated?: boolean): MobilePageExpectMatchers;
 export {};

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 DesktopMacApp, type DesktopMacConnectOptions, type DesktopMacDesktop, type DesktopMacLaunchOptions, 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 NativeApp, type NativeAppLocator, type MobileIosConnectOptions, type MobileIosDevice, type MobileIosLaunchOptions, type MobileIosApp, type DesktopMacApp, type DesktopMacConnectOptions, type DesktopMacDesktop, type DesktopMacLaunchOptions, type DesktopWindowsApp, type DesktopWindowsConnectOptions, type DesktopWindowsDesktop, type DesktopWindowsLaunchOptions, type Browser, type BrowserKind, type LaunchOptions, type Locator, type Page } from "@allwright.dev/core";
 import { expect as vitestExpect, type Assertion } from "vitest";
 export interface AllwrightVitestOptions {
     launchOptions?: LaunchOptions;
@@ -19,6 +19,10 @@ export interface AllwrightVitestOptions {
         connectOptions?: DesktopMacConnectOptions;
         launchOptions?: DesktopMacLaunchOptions;
     };
+    windows?: {
+        connectOptions?: DesktopWindowsConnectOptions;
+        launchOptions?: DesktopWindowsLaunchOptions;
+    };
     configFile?: string;
     suite?: string;
 }
@@ -31,6 +35,8 @@ export interface AllwrightVitestFixtures {
     iosApp: MobileIosApp;
     macos: DesktopMacDesktop;
     macosApp: DesktopMacApp;
+    windows: DesktopWindowsDesktop;
+    windowsApp: DesktopWindowsApp;
 }
 interface LazyResource<T> {
     peek(): T | null;
@@ -41,23 +47,26 @@ export declare const test: import("vitest").TestAPI<{
     browser: Browser;
     page: Page;
     android: MobileAndroidDevice;
-    androidApp: MobileAndroidApp;
+    androidApp: NativeApp;
     ios: MobileIosDevice;
-    iosApp: MobileAndroidApp;
+    iosApp: NativeApp;
     macos: DesktopMacDesktop;
-    macosApp: MobileAndroidApp;
+    macosApp: NativeApp;
+    windows: DesktopWindowsDesktop;
+    windowsApp: NativeApp;
     allwright: AllwrightVitestOptions;
     _browserResource: LazyResource<Browser>;
     _androidResource: LazyResource<MobileAndroidDevice>;
     _iosResource: LazyResource<MobileIosDevice>;
     _macosResource: LazyResource<DesktopMacDesktop>;
+    _windowsResource: LazyResource<DesktopWindowsDesktop>;
 }>;
 type VitestExpect = typeof vitestExpect;
 interface AllwrightExpect extends VitestExpect {
     (actual: Page): PageExpectMatchers;
     (actual: Locator): LocatorExpectMatchers;
-    (actual: MobileAndroidApp): MobilePageExpectMatchers;
-    (actual: MobileAndroidLocator): MobileLocatorExpectMatchers;
+    (actual: NativeApp): MobilePageExpectMatchers;
+    (actual: NativeAppLocator): MobileLocatorExpectMatchers;
     <T>(actual: T): Assertion<T>;
 }
 export declare const expect: AllwrightExpect;

package/dist/index.js

@@ -7,6 +7,8 @@ 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;
+const DEFAULT_WINDOWS_CONNECT_TIMEOUT_MS = 30_000;
+const DEFAULT_WINDOWS_LAUNCH_TIMEOUT_MS = 60_000;
 function createLazyResource(factory) {
     let value = null;
     let promise = null;
@@ -495,6 +497,20 @@ function createLazyMacosDesktop(desktopResource) {
         },
     };
 }
+function createLazyWindowsDesktop(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({});
@@ -540,6 +556,14 @@ export const test = base.extend({
         const macosResource = createLazyResource(async () => desktop.mac.connect(resolveMacosConnectOptions(config, allwright)));
         await use(macosResource);
     },
+    _windowsResource: async ({ allwright }, use) => {
+        const config = resolveVitestConfig(allwright);
+        if (config.serverAddr) {
+            setServerAddr(config.serverAddr);
+        }
+        const windowsResource = createLazyResource(async () => desktop.windows.connect(resolveWindowsConnectOptions(config, allwright)));
+        await use(windowsResource);
+    },
     browser: async ({ _browserResource }, use) => {
         try {
             await use(createLazyBrowser(_browserResource));
@@ -584,6 +608,17 @@ export const test = base.extend({
         });
         await use(createLazyMobileApp(appResource));
     },
+    windows: async ({ _windowsResource }, use) => {
+        await use(createLazyWindowsDesktop(_windowsResource));
+    },
+    windowsApp: async ({ _windowsResource, allwright }, use) => {
+        const appResource = createLazyResource(async () => {
+            const config = resolveVitestConfig(allwright);
+            const launchOptions = resolveWindowsLaunchOptions(config, allwright);
+            return (await _windowsResource.get()).launch(launchOptions);
+        });
+        await use(createLazyMobileApp(appResource));
+    },
 });
 function isPage(value) {
     return !!value && typeof value === "object" && typeof value.locator === "function";
@@ -689,6 +724,28 @@ function resolveMacosLaunchOptions(config, options) {
             DEFAULT_MACOS_LAUNCH_TIMEOUT_MS,
     };
 }
+function resolveWindowsConnectOptions(config, options) {
+    return {
+        agentEndpoint: options.windows?.connectOptions?.agentEndpoint ??
+            process.env.ALLWRIGHT_WINDOWS_AGENT_ENDPOINT,
+        timeoutMs: options.windows?.connectOptions?.timeoutMs ??
+            DEFAULT_WINDOWS_CONNECT_TIMEOUT_MS,
+    };
+}
+function resolveWindowsLaunchOptions(config, options) {
+    const appId = options.windows?.launchOptions?.appId ??
+        process.env.ALLWRIGHT_WINDOWS_APP_ID ??
+        config.desktop.windows?.appId;
+    if (!appId) {
+        throw new Error("windowsApp fixture requires Windows launch options with `appId`, or config.desktop.windows.app configured");
+    }
+    return {
+        appId,
+        terminateRunning: options.windows?.launchOptions?.terminateRunning ?? false,
+        timeoutMs: options.windows?.launchOptions?.timeoutMs ??
+            DEFAULT_WINDOWS_LAUNCH_TIMEOUT_MS,
+    };
+}
 let activeExpectDefaults = {};
 function currentExpectDefaults() {
     return activeExpectDefaults;

package/package.json

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