@allwright.dev/vitest 0.1.1 → 0.1.3

package/README.md

@@ -117,3 +117,50 @@ Available fixtures:
 `androidApp` launches using `allwright.android.launchOptions` first, then falls back to `config.mobile.android`.
 
 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.
+
+The opt-in accessibility integration test exercises the public page fixture,
+bundled protobuf, running engine and dynamically loaded web plugin. From this
+repository, after building the packages, run:
+
+```sh
+ALLWRIGHT_TEST_BROWSER=chromium bun run --cwd typescript/vitest vitest run tests/accessibility.spec.ts
+ALLWRIGHT_TEST_BROWSER=firefox bun run --cwd typescript/vitest vitest run tests/accessibility.spec.ts
+```
+
+Set `ALLWRIGHT_TEST_LIVE_SITE=1` to reproduce the Form Inputs navigation on the
+public example site. The default fixture is a local data URL. Use
+`ALLWRIGHT_CLI_PATH` and `ALLWRIGHT_SERVER_ADDR` to select the runtime under test;
+client, engine and installed web plugin versions must match.
+
+### Negated assertions and locator exclusion
+
+Every Allwright page/app and locator matcher supports both Vitest's `.not` form
+and the callable `.not()` alias. Negation retries the opposite condition using
+the same timeout and interval options:
+
+```ts
+await expect(page.getByRole('status')).not.toHaveText('Loading');
+await expect(page.getByTestId('spinner')).not().toBeVisible();
+await expect(page).not.toHaveCount('.error', 1);
+await expect(androidApp.locator('text="Loading"')).not().toBeVisible();
+```
+
+Negative visibility succeeds when the element is hidden or absent. Selector,
+transport, and session errors still fail; they are not evidence of invisibility.
+Negative text assertions require a successful text read. Matcher objects are
+immutable, and a second `.not` toggles back to positive assertions. Ordinary
+Vitest value assertions retain their native `.not` syntax.
+
+Web locators also support exclusion by element identity, with further chaining:
+
+```ts
+const enabledActions = page.getByRole('button')
+  .not(page.getByRole('button', { disabled: true }));
+await expect(enabledActions).not().toHaveCount(0);
+```
+
+Both locators must belong to the same page. `.not(other)` removes matching nodes;
+`filter({ hasNot: other })` removes candidates containing matching descendants.
+The same exclusion API is available in the core web clients as TypeScript/Java
+`.not(other)`, Go `.Not(other)`, Rust `.not(&other)`, and Python `.not_(other)`.
+Native Android locator exclusion is not exposed by this web selector API.

package/dist/expectations.d.ts

@@ -0,0 +1,30 @@
+import type { CommandOptions, Locator, MobileAndroidApp, MobileAndroidLocator, Page, WaitForSelectorOptions } from "@allwright.dev/core";
+export interface RetryExpectationOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+}
+export interface TextExpectationOptions extends RetryExpectationOptions {
+    command?: CommandOptions;
+}
+export interface VisibleExpectationOptions extends RetryExpectationOptions {
+    command?: WaitForSelectorOptions;
+}
+export interface PageExpectMatchers {
+    readonly not: PageExpectMatchers & (() => PageExpectMatchers);
+    toHaveText(selector: string, expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
+    toContainText(selector: string, expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
+    toHaveCount(selector: string, expected: number, options?: RetryExpectationOptions): Promise<void>;
+    toBeVisible(selector: string, options?: VisibleExpectationOptions): Promise<void>;
+}
+export interface LocatorExpectMatchers {
+    readonly not: LocatorExpectMatchers & (() => LocatorExpectMatchers);
+    toHaveText(expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
+    toContainText(expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
+    toHaveCount(expected: number, options?: RetryExpectationOptions): Promise<void>;
+    toBeVisible(options?: VisibleExpectationOptions): Promise<void>;
+}
+type Defaults = () => RetryExpectationOptions;
+type AnyLocator = Locator | MobileAndroidLocator;
+export declare function createLocatorExpect(locator: AnyLocator, defaults: Defaults, negated?: boolean): LocatorExpectMatchers;
+export declare function createPageExpect(page: Page | MobileAndroidApp, defaults: Defaults, negated?: boolean): PageExpectMatchers;
+export {};

package/dist/expectations.js

@@ -0,0 +1,85 @@
+import { expect as vitestExpect } from "vitest";
+function callableMatchers(matchers) {
+    return Object.defineProperties(() => matchers, Object.getOwnPropertyDescriptors(matchers));
+}
+async function retryExpectation(callback, options, defaults) {
+    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs ?? 5_000;
+    const intervalMs = options.intervalMs ?? defaults.intervalMs ?? 100;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || !Number.isFinite(intervalMs) || intervalMs < 0) {
+        throw new Error("Expectation timeoutMs and intervalMs must be finite non-negative numbers");
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        try {
+            // The assertion owns retrying; do not let a nested command use the server's full default timeout.
+            await callback({ timeoutMs: Math.max(1, Math.min(options.command?.timeoutMs ?? Math.max(1, intervalMs), deadline - Date.now())) });
+            return;
+        }
+        catch (error) {
+            if (Date.now() + intervalMs >= deadline)
+                throw error;
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+        }
+    }
+}
+async function isVisible(locator, command) {
+    if ("filter" in locator) {
+        return (await locator.filter({ visible: true }).count(command)).count > 0;
+    }
+    // Android has no visibility-filter query. An absent node is not visible; only
+    // its explicit native visibility failure is a negative observation.
+    if ((await locator.count(command)).count === 0)
+        return false;
+    try {
+        return (await locator.waitFor({ ...command, visible: true })).visible;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("selector found but not visible: "))
+            return false;
+        throw error;
+    }
+}
+export function createLocatorExpect(locator, defaults, negated = false) {
+    const assertion = (value) => negated ? vitestExpect(value).not : vitestExpect(value);
+    return {
+        get not() { return callableMatchers(createLocatorExpect(locator, defaults, !negated)); },
+        async toHaveText(expected, options = {}) {
+            await retryExpectation(async (command) => {
+                const { text } = await locator.textContent(command);
+                if (expected instanceof RegExp)
+                    assertion(text).toMatch(new RegExp(expected.source, expected.flags));
+                else
+                    assertion(text).toBe(expected);
+            }, options, defaults());
+        },
+        async toContainText(expected, options = {}) {
+            await retryExpectation(async (command) => {
+                const { text } = await locator.textContent(command);
+                if (expected instanceof RegExp)
+                    assertion(text).toMatch(new RegExp(expected.source, expected.flags));
+                else
+                    assertion(text).toContain(expected);
+            }, options, defaults());
+        },
+        async toHaveCount(expected, options = {}) {
+            await retryExpectation(async (command) => {
+                assertion((await locator.count(command)).count).toBe(expected);
+            }, options, defaults());
+        },
+        async toBeVisible(options = {}) {
+            await retryExpectation(async (command) => {
+                assertion(await isVisible(locator, command)).toBe(true);
+            }, options, defaults());
+        },
+    };
+}
+export function createPageExpect(page, defaults, negated = false) {
+    const matcher = (selector) => createLocatorExpect(page.locator(selector), defaults, negated);
+    return {
+        get not() { return callableMatchers(createPageExpect(page, defaults, !negated)); },
+        toHaveText: (selector, expected, options) => matcher(selector).toHaveText(expected, options),
+        toContainText: (selector, expected, options) => matcher(selector).toContainText(expected, options),
+        toHaveCount: (selector, expected, options) => matcher(selector).toHaveCount(expected, options),
+        toBeVisible: (selector, options) => matcher(selector).toBeVisible(options),
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { type MobileAndroidConnectOptions, type MobileAndroidDevice, type MobileAndroidLaunchOptions, type MobileAndroidApp, type Browser, type BrowserKind, type LaunchOptions, type Locator, type MobileAndroidLocator, type Page, type WaitForSelectorOptions } from "@allwright.dev/core";
-import { expect as vitestExpect } from "vitest";
+import type { PageExpectMatchers, LocatorExpectMatchers } from "./expectations.js";
+export type { RetryExpectationOptions, TextExpectationOptions, VisibleExpectationOptions, PageExpectMatchers, LocatorExpectMatchers } 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 { expect as vitestExpect, type Assertion } from "vitest";
 export interface AllwrightVitestOptions {
     launchOptions?: LaunchOptions;
     serverAddr?: string;
@@ -18,30 +20,6 @@ export interface AllwrightVitestFixtures {
     android: MobileAndroidDevice;
     androidApp: MobileAndroidApp;
 }
-export interface RetryExpectationOptions {
-    timeoutMs?: number;
-    intervalMs?: number;
-}
-export interface TextExpectationOptions extends RetryExpectationOptions {
-    command?: {
-        timeoutMs?: number;
-    };
-}
-export interface VisibleExpectationOptions extends RetryExpectationOptions {
-    command?: WaitForSelectorOptions;
-}
-export interface PageExpectMatchers {
-    toHaveText(selector: string, expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
-    toContainText(selector: string, expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
-    toHaveCount(selector: string, expected: number, options?: RetryExpectationOptions): Promise<void>;
-    toBeVisible(selector: string, options?: VisibleExpectationOptions): Promise<void>;
-}
-export interface LocatorExpectMatchers {
-    toHaveText(expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
-    toContainText(expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
-    toHaveCount(expected: number, options?: RetryExpectationOptions): Promise<void>;
-    toBeVisible(options?: VisibleExpectationOptions): Promise<void>;
-}
 interface LazyResource<T> {
     peek(): T | null;
     get(): Promise<T>;
@@ -57,13 +35,12 @@ export declare const test: import("vitest").TestAPI<{
     _androidResource: LazyResource<MobileAndroidDevice>;
 }>;
 type VitestExpect = typeof vitestExpect;
-type VitestMatcherReturn = ReturnType<VitestExpect>;
 interface AllwrightExpect extends VitestExpect {
     (actual: Page): PageExpectMatchers;
     (actual: Locator): LocatorExpectMatchers;
     (actual: MobileAndroidApp): PageExpectMatchers;
     (actual: MobileAndroidLocator): LocatorExpectMatchers;
-    <T>(actual: T): VitestMatcherReturn;
+    <T>(actual: T): Assertion<T>;
 }
 export declare const expect: AllwrightExpect;
 export { vitestExpect };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createLocatorExpect, createPageExpect } from "./expectations.js";
 import { launchConfiguredBrowser, mobile, resolveConfig, setServerAddr, } from "@allwright.dev/core";
 import { expect as vitestExpect, test as base } from "vitest";
 const DEFAULT_ANDROID_CONNECT_TIMEOUT_MS = 30_000;
@@ -33,6 +34,17 @@ function getLazySyncProperty(resource, property) {
     }
     throw new Error(`fixture property ${String(property)} is not available before the lazy resource is initialized; use an async method first`);
 }
+const lazyLocatorSources = new WeakMap();
+async function resolveFilterLocator(locator, page) {
+    if (!locator)
+        return undefined;
+    const source = lazyLocatorSources.get(locator);
+    if (!source)
+        return locator;
+    if (source.page !== page)
+        throw new Error('Filter locators must belong to the same page');
+    return (await page.get()).locator(await source.selector());
+}
 function createLazyLocator(pageResource, selectorFactory) {
     const lazyLocator = {
         get page() {
@@ -71,10 +83,45 @@ function createLazyLocator(pageResource, selectorFactory) {
         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);
+        locator(selector, options) {
+            const result = createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).locator(selector).selector);
+            return options ? result.filter(options) : result;
+        },
+        getByRole(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).getByRole(...args).selector);
+        },
+        getByText(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).getByText(...args).selector);
+        },
+        getByLabel(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).getByLabel(...args).selector);
+        },
+        getByPlaceholder(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).getByPlaceholder(...args).selector);
+        },
+        getByAltText(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).getByAltText(...args).selector);
+        },
+        getByTitle(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).getByTitle(...args).selector);
+        },
+        getByTestId(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).getByTestId(...args).selector);
         },
+        not(other) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).not((await resolveFilterLocator(other, pageResource))).selector);
+        },
+        filter(options = {}) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).filter({ ...options,
+                has: await resolveFilterLocator(options.has, pageResource),
+                hasNot: await resolveFilterLocator(options.hasNot, pageResource),
+            }).selector);
+        },
+        nth(index) { return createLazyLocator(pageResource, async () => (await pageResource.get()).locator(await selectorFactory()).nth(index).selector); },
+        first() { return this.nth(0); },
+        last() { return this.nth(-1); },
     };
+    lazyLocatorSources.set(lazyLocator, { page: pageResource, selector: selectorFactory });
     return lazyLocator;
 }
 function createLazyPage(pageResource) {
@@ -85,8 +132,9 @@ function createLazyPage(pageResource) {
         get browserSessionId() {
             return getLazySyncProperty(pageResource, "browserSessionId");
         },
-        locator(selector) {
-            return createLazyLocator(pageResource, async () => selector);
+        locator(selector, options) {
+            const result = createLazyLocator(pageResource, async () => selector);
+            return options ? result.filter(options) : result;
         },
         async goto(url, options) {
             return (await pageResource.get()).goto(url, options);
@@ -146,6 +194,27 @@ function createLazyPage(pageResource) {
                 browserSessionId: getLazySyncProperty(pageResource, "browserSessionId"),
             };
         },
+        getByRole(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).getByRole(...args).selector);
+        },
+        getByText(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).getByText(...args).selector);
+        },
+        getByLabel(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).getByLabel(...args).selector);
+        },
+        getByPlaceholder(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).getByPlaceholder(...args).selector);
+        },
+        getByAltText(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).getByAltText(...args).selector);
+        },
+        getByTitle(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).getByTitle(...args).selector);
+        },
+        getByTestId(...args) {
+            return createLazyLocator(pageResource, async () => (await pageResource.get()).getByTestId(...args).selector);
+        },
     };
     return lazyPage;
 }
@@ -356,8 +425,6 @@ export const test = base.extend({
         await use(createLazyAndroidApp(appResource));
     },
 });
-const DEFAULT_EXPECT_TIMEOUT_MS = 5_000;
-const DEFAULT_EXPECT_INTERVAL_MS = 100;
 function isPage(value) {
     return !!value && typeof value === "object" && typeof value.locator === "function";
 }
@@ -411,114 +478,16 @@ function resolveAndroidLaunchOptions(config, options) {
     }
     return launchOptions;
 }
-async function retryExpectation(callback, options = {}, defaults = {}) {
-    const timeoutMs = options.timeoutMs ?? defaults.timeoutMs ?? DEFAULT_EXPECT_TIMEOUT_MS;
-    const intervalMs = options.intervalMs ?? defaults.intervalMs ?? DEFAULT_EXPECT_INTERVAL_MS;
-    const deadline = Date.now() + timeoutMs;
-    let lastError;
-    while (Date.now() <= deadline) {
-        try {
-            await callback();
-            return;
-        }
-        catch (error) {
-            lastError = error;
-            if (Date.now() + intervalMs > deadline) {
-                break;
-            }
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
-        }
-    }
-    throw lastError instanceof Error ? lastError : new Error(String(lastError));
-}
-function createPageExpect(page) {
-    return {
-        async toHaveText(selector, expected, options = {}) {
-            await retryExpectation(async () => {
-                const result = await page.textContent(selector, options.command ?? {});
-                if (expected instanceof RegExp) {
-                    vitestExpect(result.text).toMatch(expected);
-                    return;
-                }
-                vitestExpect(result.text).toBe(expected);
-            }, options, currentExpectDefaults());
-        },
-        async toContainText(selector, expected, options = {}) {
-            await retryExpectation(async () => {
-                const result = await page.textContent(selector, options.command ?? {});
-                if (expected instanceof RegExp) {
-                    vitestExpect(result.text).toMatch(expected);
-                    return;
-                }
-                vitestExpect(result.text).toContain(expected);
-            }, options, currentExpectDefaults());
-        },
-        async toHaveCount(selector, expected, options = {}) {
-            await retryExpectation(async () => {
-                const result = await page.count(selector, {});
-                vitestExpect(result.count).toBe(expected);
-            }, options, currentExpectDefaults());
-        },
-        async toBeVisible(selector, options = {}) {
-            await retryExpectation(async () => {
-                const result = await page.waitForSelector(selector, {
-                    visible: true,
-                    ...(options.command ?? {}),
-                });
-                vitestExpect(result.visible).toBe(true);
-            }, options, currentExpectDefaults());
-        },
-    };
-}
-function createLocatorExpect(locator) {
-    return {
-        async toHaveText(expected, options = {}) {
-            await retryExpectation(async () => {
-                const result = await locator.textContent(options.command ?? {});
-                if (expected instanceof RegExp) {
-                    vitestExpect(result.text).toMatch(expected);
-                    return;
-                }
-                vitestExpect(result.text).toBe(expected);
-            }, options, currentExpectDefaults());
-        },
-        async toContainText(expected, options = {}) {
-            await retryExpectation(async () => {
-                const result = await locator.textContent(options.command ?? {});
-                if (expected instanceof RegExp) {
-                    vitestExpect(result.text).toMatch(expected);
-                    return;
-                }
-                vitestExpect(result.text).toContain(expected);
-            }, options, currentExpectDefaults());
-        },
-        async toHaveCount(expected, options = {}) {
-            await retryExpectation(async () => {
-                const result = await locator.count({});
-                vitestExpect(result.count).toBe(expected);
-            }, options, currentExpectDefaults());
-        },
-        async toBeVisible(options = {}) {
-            await retryExpectation(async () => {
-                const result = await locator.waitFor({
-                    visible: true,
-                    ...(options.command ?? {}),
-                });
-                vitestExpect(result.visible).toBe(true);
-            }, options, currentExpectDefaults());
-        },
-    };
-}
 let activeExpectDefaults = {};
 function currentExpectDefaults() {
     return activeExpectDefaults;
 }
 const expectImpl = ((actual) => {
     if (isLocator(actual)) {
-        return createLocatorExpect(actual);
+        return createLocatorExpect(actual, currentExpectDefaults);
     }
     if (isPage(actual)) {
-        return createPageExpect(actual);
+        return createPageExpect(actual, currentExpectDefaults);
     }
     return vitestExpect(actual);
 });

package/package.json

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