@allwright.dev/vitest 0.0.52 → 0.0.53

package/README.md

@@ -12,13 +12,15 @@ bun add -d vitest @allwright.dev/vitest
 import { expect, test } from "@allwright.dev/vitest";
 
 test("opens a page", async ({ page }) => {
-  await page.goto("https://example.com");
-  const title = await page.textContent("h1");
-  expect(title.text).toContain("Example");
+  await page.goto("https://themoderninternet.vercel.app");
+  await page.click(
+    "xpath=//div[contains(@class,'card')][.//h2[normalize-space()='Form Inputs']]//button[normalize-space()='Visit page']",
+  );
+  await expect(page.locator('xpath=//h1[text()="Form Inputs"]')).toHaveText("Form Inputs");
 });
 
-test("opens an Android app", async ({ androidPage }) => {
-  await androidPage.click('Id=com.example.airticket:id/bottom_nav_account');
+test("opens an Android app", async ({ androidApp }) => {
+  await androidApp.click('Id=com.example.airticket:id/bottom_nav_account');
 });
 ```
 
@@ -77,21 +79,23 @@ test.use({
   },
 });
 
-test("android only", async ({ androidPage }) => {
-  await androidPage.fill('xpath=//*[@text="Email"]', "user@example.com");
+test("android only", async ({ androidApp }) => {
+  await androidApp.fill('xpath=//*[@text="Email"]', "user@example.com");
 });
 
-test("hybrid web and android", async ({ page, androidPage }) => {
-  await page.goto("https://example.com");
-  await androidPage.click('Id=com.example.airticket:id/bottom_nav_account');
+test("hybrid web and android", async ({ page, androidApp }) => {
+  await page.goto("https://themoderninternet.vercel.app");
+  await androidApp.click('Id=com.example.airticket:id/bottom_nav_account');
 });
 ```
 
+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.
+
 Available fixtures:
 
 - `browser`: launched web browser
 - `page`: initial web page
 - `android`: connected Android device session
-- `androidPage`: launched Android app page
+- `androidApp`: launched Android app page
 
-`androidPage` launches using `allwright.android.launchOptions` first, then falls back to `config.mobile.android`.
+`androidApp` launches using `allwright.android.launchOptions` first, then falls back to `config.mobile.android`.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type MobileAndroidConnectOptions, type MobileAndroidDevice, type MobileAndroidLaunchOptions, type MobileAndroidPage, type Browser, type BrowserKind, type LaunchOptions, type Locator, type Page, type WaitForSelectorOptions } from "@allwright.dev/core";
+import { type MobileAndroidConnectOptions, type MobileAndroidDevice, type MobileAndroidLaunchOptions, type MobileAndroidApp, type Browser, type BrowserKind, type LaunchOptions, type Locator, type Page, type WaitForSelectorOptions } from "@allwright.dev/core";
 import { expect as vitestExpect } from "vitest";
 export interface AllwrightVitestOptions {
     launchOptions?: LaunchOptions;
@@ -16,7 +16,7 @@ export interface AllwrightVitestFixtures {
     browser: Browser;
     page: Page;
     android: MobileAndroidDevice;
-    androidPage: MobileAndroidPage;
+    androidApp: MobileAndroidApp;
 }
 export interface RetryExpectationOptions {
     timeoutMs?: number;
@@ -42,12 +42,19 @@ export interface LocatorExpectMatchers {
     toHaveCount(expected: number, options?: RetryExpectationOptions): Promise<void>;
     toBeVisible(options?: VisibleExpectationOptions): Promise<void>;
 }
+interface LazyResource<T> {
+    peek(): T | null;
+    get(): Promise<T>;
+    realized(): boolean;
+}
 export declare const test: import("vitest").TestAPI<{
-    browser: Browser;
     page: Page;
+    browser: Browser;
     android: MobileAndroidDevice;
-    androidPage: MobileAndroidPage;
+    androidApp: MobileAndroidApp;
     allwright: AllwrightVitestOptions;
+    _browserResource: LazyResource<Browser>;
+    _androidResource: LazyResource<MobileAndroidDevice>;
 }>;
 type VitestExpect = typeof vitestExpect;
 type VitestMatcherReturn = ReturnType<VitestExpect>;

package/dist/index.js

@@ -2,39 +2,319 @@ import { launchConfiguredBrowser, mobile, resolveConfig, setServerAddr, shutdown
 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;
+function createLazyResource(factory) {
+    let value = null;
+    let promise = null;
+    return {
+        peek() {
+            return value;
+        },
+        get() {
+            if (value) {
+                return Promise.resolve(value);
+            }
+            if (!promise) {
+                promise = factory().then((resolved) => {
+                    value = resolved;
+                    return resolved;
+                });
+            }
+            return promise;
+        },
+        realized() {
+            return value !== null;
+        },
+    };
+}
+function getLazySyncProperty(resource, property) {
+    const value = resource.peek();
+    if (value) {
+        return value[property];
+    }
+    throw new Error(`fixture property ${String(property)} is not available before the lazy resource is initialized; use an async method first`);
+}
+function createLazyLocator(pageResource, selectorFactory) {
+    const lazyLocator = {
+        get page() {
+            return createLazyPage(pageResource);
+        },
+        get selector() {
+            throw new Error("lazy locator selector is not available before the page fixture is initialized");
+        },
+        async click(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).click(options);
+        },
+        async count(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).count(options);
+        },
+        async highlight(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).highlight(options);
+        },
+        async focus(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).focus(options);
+        },
+        async fill(value, options) {
+            return (await pageResource.get()).locator(await selectorFactory()).fill(value, options);
+        },
+        async hover(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).hover(options);
+        },
+        async press(key, options) {
+            return (await pageResource.get()).locator(await selectorFactory()).press(key, options);
+        },
+        async textContent(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).textContent(options);
+        },
+        async innerText(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).innerText(options);
+        },
+        async waitFor(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).waitFor(options);
+        },
+        locator(selector) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).locator(selector).selector);
+        },
+    };
+    return lazyLocator;
+}
+function createLazyPage(pageResource) {
+    const lazyPage = {
+        get sessionId() {
+            return getLazySyncProperty(pageResource, "sessionId");
+        },
+        get browserSessionId() {
+            return getLazySyncProperty(pageResource, "browserSessionId");
+        },
+        locator(selector) {
+            return createLazyLocator(pageResource, async () => selector);
+        },
+        async goto(url, options) {
+            return (await pageResource.get()).goto(url, options);
+        },
+        async navigate(url, options) {
+            return (await pageResource.get()).navigate(url, options);
+        },
+        async click(selector, options) {
+            return (await pageResource.get()).click(selector, options);
+        },
+        async count(selector, options) {
+            return (await pageResource.get()).count(selector, options);
+        },
+        async highlight(selector, options) {
+            return (await pageResource.get()).highlight(selector, options);
+        },
+        async focus(selector, options) {
+            return (await pageResource.get()).focus(selector, options);
+        },
+        async fill(selector, value, options) {
+            return (await pageResource.get()).fill(selector, value, options);
+        },
+        async hover(selector, options) {
+            return (await pageResource.get()).hover(selector, options);
+        },
+        async press(selector, key, options) {
+            return (await pageResource.get()).press(selector, key, options);
+        },
+        async textContent(selector, options) {
+            return (await pageResource.get()).textContent(selector, options);
+        },
+        async innerText(selector, options) {
+            return (await pageResource.get()).innerText(selector, options);
+        },
+        async waitForSelector(selector, options) {
+            return (await pageResource.get()).waitForSelector(selector, options);
+        },
+        async close() {
+            await (await pageResource.get()).close();
+        },
+        async ping(message) {
+            return (await pageResource.get()).ping(message);
+        },
+        pageInfo() {
+            const page = pageResource.peek();
+            if (page) {
+                return page.pageInfo();
+            }
+            return {
+                sessionId: getLazySyncProperty(pageResource, "sessionId"),
+                browserSessionId: getLazySyncProperty(pageResource, "browserSessionId"),
+            };
+        },
+    };
+    return lazyPage;
+}
+function createLazyBrowser(browserResource) {
+    const lazyBrowser = {
+        get sessionId() {
+            return getLazySyncProperty(browserResource, "sessionId");
+        },
+        get browserName() {
+            return getLazySyncProperty(browserResource, "browserName");
+        },
+        get launchNote() {
+            return getLazySyncProperty(browserResource, "launchNote");
+        },
+        get cdpWebSocketURL() {
+            return getLazySyncProperty(browserResource, "cdpWebSocketURL");
+        },
+        get userDataDir() {
+            return getLazySyncProperty(browserResource, "userDataDir");
+        },
+        page() {
+            return createLazyPage(createLazyResource(async () => (await browserResource.get()).page()));
+        },
+        initialPage() {
+            return createLazyPage(createLazyResource(async () => (await browserResource.get()).initialPage()));
+        },
+        initialTab() {
+            return createLazyPage(createLazyResource(async () => (await browserResource.get()).initialTab()));
+        },
+        pages() {
+            const browser = browserResource.peek();
+            if (!browser) {
+                return [this.page()];
+            }
+            return browser.pages();
+        },
+        async newPage(options) {
+            return (await browserResource.get()).newPage(options);
+        },
+        async newTab(options) {
+            return (await browserResource.get()).newTab(options);
+        },
+        async close() {
+            await (await browserResource.get()).close();
+        },
+        async ping(message) {
+            return (await browserResource.get()).ping(message);
+        },
+        browserInfo() {
+            const browser = browserResource.peek();
+            if (browser) {
+                return browser.browserInfo();
+            }
+            return {
+                sessionId: getLazySyncProperty(browserResource, "sessionId"),
+                browserName: getLazySyncProperty(browserResource, "browserName"),
+                launchNote: getLazySyncProperty(browserResource, "launchNote"),
+                cdpWebSocketURL: getLazySyncProperty(browserResource, "cdpWebSocketURL"),
+                userDataDir: getLazySyncProperty(browserResource, "userDataDir"),
+            };
+        },
+    };
+    return lazyBrowser;
+}
+function createLazyAndroidApp(appResource) {
+    const lazyApp = {
+        get sessionId() {
+            return getLazySyncProperty(appResource, "sessionId");
+        },
+        locator(selector) {
+            return createLazyAndroidLocator(appResource, async () => selector);
+        },
+        async click(selector, options) {
+            return (await appResource.get()).click(selector, options);
+        },
+        async fill(selector, value, options) {
+            return (await appResource.get()).fill(selector, value, options);
+        },
+    };
+    return lazyApp;
+}
+function createLazyAndroidLocator(appResource, selectorFactory) {
+    const lazyLocator = {
+        get page() {
+            return createLazyAndroidApp(appResource);
+        },
+        get selector() {
+            throw new Error("lazy Android locator selector is not available before the app fixture is initialized");
+        },
+        async click(options) {
+            return (await appResource.get()).locator(await selectorFactory()).click(options);
+        },
+        async fill(value, options) {
+            return (await appResource.get()).locator(await selectorFactory()).fill(value, options);
+        },
+        locator(selector) {
+            return createLazyAndroidLocator(appResource, async () => (await appResource.get()).locator(await selectorFactory()).locator(selector).selector);
+        },
+    };
+    return lazyLocator;
+}
+function createLazyAndroidDevice(deviceResource) {
+    const initialAppResource = createLazyResource(async () => (await deviceResource.get()).app());
+    const lazyDevice = {
+        get sessionId() {
+            return getLazySyncProperty(deviceResource, "sessionId");
+        },
+        app() {
+            return createLazyAndroidApp(initialAppResource);
+        },
+        initialApp() {
+            return createLazyAndroidApp(initialAppResource);
+        },
+        async launch(options) {
+            return (await deviceResource.get()).launch(options);
+        },
+    };
+    return lazyDevice;
+}
 export const test = base.extend({
     allwright: async ({}, use) => {
         await use({});
     },
-    browser: async ({ allwright }, use) => {
+    _browserResource: async ({ allwright }, use) => {
         const config = resolveVitestConfig(allwright);
         if (config.serverAddr) {
             setServerAddr(config.serverAddr);
         }
         activeExpectDefaults = config.expect;
-        const browser = await launchConfiguredBrowser(config);
+        const browserResource = createLazyResource(async () => launchConfiguredBrowser(config));
         try {
-            await use(browser);
+            await use(browserResource);
         }
         finally {
             activeExpectDefaults = {};
-            await browser.close().catch(() => undefined);
+            if (browserResource.realized()) {
+                await browserResource.get().then((resolved) => resolved.close()).catch(() => undefined);
+            }
             await shutdown();
         }
     },
+    _androidResource: async ({ allwright }, use) => {
+        const config = resolveVitestConfig(allwright);
+        if (config.serverAddr) {
+            setServerAddr(config.serverAddr);
+        }
+        const androidResource = createLazyResource(async () => mobile.android.connect(resolveAndroidConnectOptions(config, allwright)));
+        try {
+            await use(androidResource);
+        }
+        finally {
+            await shutdown();
+        }
+    },
+    browser: async ({ _browserResource }, use) => {
+        try {
+            await use(createLazyBrowser(_browserResource));
+        }
+        finally {
+            // resource lifecycle is owned by _browserResource
+        }
+    },
     page: async ({ browser }, use) => {
         await use(browser.page());
     },
-    android: async ({ allwright }, use) => {
-        const config = resolveVitestConfig(allwright);
-        const android = await mobile.android.connect(resolveAndroidConnectOptions(config, allwright));
-        await use(android);
+    android: async ({ _androidResource }, use) => {
+        await use(createLazyAndroidDevice(_androidResource));
     },
-    androidPage: async ({ android, allwright }, use) => {
-        const config = resolveVitestConfig(allwright);
-        const launchOptions = resolveAndroidLaunchOptions(config, allwright);
-        const page = await android.launch(launchOptions);
-        await use(page);
+    androidApp: async ({ _androidResource, allwright }, use) => {
+        const appResource = createLazyResource(async () => {
+            const config = resolveVitestConfig(allwright);
+            const launchOptions = resolveAndroidLaunchOptions(config, allwright);
+            return (await _androidResource.get()).launch(launchOptions);
+        });
+        await use(createLazyAndroidApp(appResource));
     },
 });
 const DEFAULT_EXPECT_TIMEOUT_MS = 5_000;
@@ -88,7 +368,7 @@ function resolveAndroidLaunchOptions(config, options) {
             DEFAULT_ANDROID_LAUNCH_TIMEOUT_MS,
     };
     if (!launchOptions.apkPath && !launchOptions.appId) {
-        throw new Error("androidPage fixture requires android launch options with `apkPath` or `appId`, or config.mobile.android.app configured");
+        throw new Error("androidApp fixture requires android launch options with `apkPath` or `appId`, or config.mobile.android.app configured");
     }
     return launchOptions;
 }

package/package.json

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