@allwright.dev/vitest 0.1.13 → 0.1.14

package/README.md

@@ -164,3 +164,27 @@ Both locators must belong to the same page. `.not(other)` removes matching nodes
 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.
+
+### Retrying state expectations
+
+Assert against the page or locator so each attempt reads fresh state:
+
+```ts
+await expect(page).toHaveURL('https://example.com/dashboard');
+await expect(page).toHaveURL(/\/dashboard(?:\?|$)/, { timeoutMs: 10_000 });
+await expect(page.locator('input')).toHaveValue(/ready/i);
+await expect(page.locator('select')).toHaveSelectedOptions(['a', 'b']);
+await expect(page.locator('select')).toHaveSelectedOptions([{ value: 'a', label: /Alpha/ }]);
+await expect(page.locator('textarea')).toHaveSelectedText('selected words');
+await expect(page.locator('input[type=checkbox]')).toBeChecked();
+await expect(page.locator('h1')).toHaveText('Welcome');
+await expect(page.locator('a')).toHaveAttribute('href', /dashboard/);
+await expect(page.locator('button')).toHaveBoundingBox({ width: 100, height: 40 });
+await expect(page.locator('input[type=radio]')).not().toBeChecked();
+```
+
+Every element matcher also has a page form, such as `expect(page).toHaveValue('#name', 'Alice')` or `expect(page).toHaveAttribute('a', 'href', '/home')`. These state matchers are web-only; Android retains its text/count/visibility matchers.
+
+All Allwright page/app/locator expectations retry until they match or the timeout expires, including `.not` and `.not()`. Defaults come from the shared assertion configuration, falling back to 5 seconds and a 100 ms interval. Override these with `{ timeoutMs, intervalMs }`. In-flight reads and nested command timeout hints are bounded by the remaining assertion budget; `timeoutMs: 0` makes one observation without polling. Ordinary assertions on already captured values, such as `expect(await page.url()).toBe(...)`, use standard Vitest behavior and do not re-read the page.
+
+String URL expectations match the complete URL exactly; regex expectations match the current URL on every attempt without modifying the regex's `lastIndex`. Values, selected text, and attributes also accept strings or regexes. `null` asserts a missing attribute or unsupported textbox selection; an empty string is distinct. Selected-option arrays match in order and require the same number of options. Entries can be exact values, value regexes, or objects specifying value, label, and/or index. Bounding-box expectations compare only the supplied coordinates/dimensions exactly in viewport CSS pixels; `null` expects no visible box. `.not.toBeChecked()` expects an unchecked control. Missing elements and read errors cannot satisfy negation.

package/dist/expectations.d.ts

@@ -1,4 +1,4 @@
-import type { CommandOptions, Locator, MobileAndroidApp, MobileAndroidLocator, Page, WaitForSelectorOptions } from "@allwright.dev/core";
+import type { BoundingBox, CommandOptions, Locator, MobileAndroidApp, MobileAndroidLocator, Page, WaitForSelectorOptions } from "@allwright.dev/core";
 export interface RetryExpectationOptions {
     timeoutMs?: number;
     intervalMs?: number;
@@ -9,22 +9,50 @@ export interface TextExpectationOptions extends RetryExpectationOptions {
 export interface VisibleExpectationOptions extends RetryExpectationOptions {
     command?: WaitForSelectorOptions;
 }
-export interface PageExpectMatchers {
-    readonly not: PageExpectMatchers & (() => PageExpectMatchers);
+export interface MobilePageExpectMatchers {
+    readonly not: MobilePageExpectMatchers & (() => MobilePageExpectMatchers);
     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);
+export interface MobileLocatorExpectMatchers {
+    readonly not: MobileLocatorExpectMatchers & (() => MobileLocatorExpectMatchers);
     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>;
 }
+export type SelectedOptionExpectation = string | RegExp | {
+    value?: string | RegExp;
+    label?: string | RegExp;
+    index?: number;
+};
+export interface LocatorExpectMatchers extends MobileLocatorExpectMatchers {
+    readonly not: LocatorExpectMatchers & (() => LocatorExpectMatchers);
+    toHaveValue(expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
+    toHaveSelectedOptions(expected: SelectedOptionExpectation[], options?: TextExpectationOptions): Promise<void>;
+    toHaveSelectedText(expected: string | RegExp | null, options?: TextExpectationOptions): Promise<void>;
+    toBeChecked(options?: TextExpectationOptions): Promise<void>;
+    toHaveAttribute(name: string, expected: string | RegExp | null, options?: TextExpectationOptions): Promise<void>;
+    toHaveBoundingBox(expected: Partial<BoundingBox> | null, options?: TextExpectationOptions): Promise<void>;
+}
+export interface PageExpectMatchers extends MobilePageExpectMatchers {
+    readonly not: PageExpectMatchers & (() => PageExpectMatchers);
+    toHaveURL(expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
+    toHaveValue(selector: string, expected: string | RegExp, options?: TextExpectationOptions): Promise<void>;
+    toHaveSelectedOptions(selector: string, expected: SelectedOptionExpectation[], options?: TextExpectationOptions): Promise<void>;
+    toHaveSelectedText(selector: string, expected: string | RegExp | null, options?: TextExpectationOptions): Promise<void>;
+    toBeChecked(selector: string, options?: TextExpectationOptions): Promise<void>;
+    toHaveAttribute(selector: string, name: string, expected: string | RegExp | null, options?: TextExpectationOptions): Promise<void>;
+    toHaveBoundingBox(selector: string, expected: Partial<BoundingBox> | null, options?: TextExpectationOptions): 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 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: 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 {};

package/dist/expectations.js

@@ -9,19 +9,41 @@ async function retryExpectation(callback, options, defaults) {
         throw new Error("Expectation timeoutMs and intervalMs must be finite non-negative numbers");
     }
     const deadline = Date.now() + timeoutMs;
+    let lastError;
     while (true) {
+        let timer;
         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())) });
+            // The assertion owns polling and bounds both the command hint and in-flight read.
+            const attempt = callback({ timeoutMs: Math.max(1, Math.min(options.command?.timeoutMs ?? Math.max(1, intervalMs), deadline - Date.now())) });
+            if (timeoutMs === 0)
+                await attempt; // One observation, without polling.
+            else
+                await Promise.race([
+                    attempt,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(lastError ?? new Error(`Expectation timed out after ${timeoutMs}ms while reading state`)), Math.max(0, deadline - Date.now()));
+                    }),
+                ]);
             return;
         }
         catch (error) {
-            if (Date.now() + intervalMs >= deadline)
-                throw error;
-            await new Promise(resolve => setTimeout(resolve, intervalMs));
+            lastError = error;
         }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw lastError;
+        await new Promise(resolve => setTimeout(resolve, Math.min(intervalMs, remaining)));
+        if (Date.now() >= deadline)
+            throw lastError;
     }
 }
+function expectedText(expected) {
+    return expected instanceof RegExp ? vitestExpect.stringMatching(new RegExp(expected.source, expected.flags)) : expected;
+}
 async function isVisible(locator, command) {
     if ("filter" in locator) {
         return (await locator.filter({ visible: true }).count(command)).count > 0;
@@ -41,7 +63,7 @@ async function isVisible(locator, command) {
 }
 export function createLocatorExpect(locator, defaults, negated = false) {
     const assertion = (value) => negated ? vitestExpect(value).not : vitestExpect(value);
-    return {
+    const common = {
         get not() { return callableMatchers(createLocatorExpect(locator, defaults, !negated)); },
         async toHaveText(expected, options = {}) {
             await retryExpectation(async (command) => {
@@ -72,14 +94,76 @@ export function createLocatorExpect(locator, defaults, negated = false) {
             }, options, defaults());
         },
     };
+    if (!("inputValue" in locator))
+        return common;
+    const web = {
+        toHaveText: common.toHaveText,
+        toContainText: common.toContainText,
+        toHaveCount: common.toHaveCount,
+        toBeVisible: common.toBeVisible,
+        get not() { return callableMatchers(createLocatorExpect(locator, defaults, !negated)); },
+        async toHaveValue(expected, options = {}) {
+            await retryExpectation(async (command) => assertion(await locator.inputValue(command)).toEqual(expectedText(expected)), options, defaults());
+        },
+        async toHaveSelectedOptions(expected, options = {}) {
+            await retryExpectation(async (command) => {
+                const wanted = expected.map(option => {
+                    if (typeof option === "string" || option instanceof RegExp)
+                        return vitestExpect.objectContaining({ value: expectedText(option) });
+                    return vitestExpect.objectContaining({
+                        ...(option.value !== undefined ? { value: expectedText(option.value) } : {}),
+                        ...(option.label !== undefined ? { label: expectedText(option.label) } : {}),
+                        ...(option.index !== undefined ? { index: option.index } : {}),
+                    });
+                });
+                assertion(await locator.selectedOptions(command)).toEqual(wanted);
+            }, options, defaults());
+        },
+        async toHaveSelectedText(expected, options = {}) {
+            await retryExpectation(async (command) => assertion(await locator.selectedText(command)).toEqual(expectedText(expected)), options, defaults());
+        },
+        async toBeChecked(options = {}) {
+            await retryExpectation(async (command) => assertion(await locator.isChecked(command)).toBe(true), options, defaults());
+        },
+        async toHaveAttribute(name, expected, options = {}) {
+            await retryExpectation(async (command) => assertion(await locator.getAttribute(name, command)).toEqual(expectedText(expected)), options, defaults());
+        },
+        async toHaveBoundingBox(expected, options = {}) {
+            await retryExpectation(async (command) => assertion(await locator.boundingBox(command)).toEqual(expected === null ? null : vitestExpect.objectContaining(expected)), options, defaults());
+        },
+    };
+    return web;
 }
 export function createPageExpect(page, defaults, negated = false) {
     const matcher = (selector) => createLocatorExpect(page.locator(selector), defaults, negated);
-    return {
+    const common = {
         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),
     };
+    if (!("url" in page))
+        return common;
+    const webMatcher = (selector) => createLocatorExpect(page.locator(selector), defaults, negated);
+    const web = {
+        toHaveText: common.toHaveText,
+        toContainText: common.toContainText,
+        toHaveCount: common.toHaveCount,
+        toBeVisible: common.toBeVisible,
+        get not() { return callableMatchers(createPageExpect(page, defaults, !negated)); },
+        async toHaveURL(expected, options = {}) {
+            await retryExpectation(async (command) => {
+                const url = await page.url(command);
+                (negated ? vitestExpect(url).not : vitestExpect(url)).toEqual(expectedText(expected));
+            }, options, defaults());
+        },
+        toHaveValue: (selector, expected, options) => webMatcher(selector).toHaveValue(expected, options),
+        toHaveSelectedOptions: (selector, expected, options) => webMatcher(selector).toHaveSelectedOptions(expected, options),
+        toHaveSelectedText: (selector, expected, options) => webMatcher(selector).toHaveSelectedText(expected, options),
+        toBeChecked: (selector, options) => webMatcher(selector).toBeChecked(options),
+        toHaveAttribute: (selector, name, expected, options) => webMatcher(selector).toHaveAttribute(name, expected, options),
+        toHaveBoundingBox: (selector, expected, options) => webMatcher(selector).toHaveBoundingBox(expected, options),
+    };
+    return web;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { PageExpectMatchers, LocatorExpectMatchers } from "./expectations.js";
-export type { RetryExpectationOptions, TextExpectationOptions, VisibleExpectationOptions, PageExpectMatchers, LocatorExpectMatchers } from "./expectations.js";
+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 { expect as vitestExpect, type Assertion } from "vitest";
 export interface AllwrightVitestOptions {
@@ -38,8 +38,8 @@ type VitestExpect = typeof vitestExpect;
 interface AllwrightExpect extends VitestExpect {
     (actual: Page): PageExpectMatchers;
     (actual: Locator): LocatorExpectMatchers;
-    (actual: MobileAndroidApp): PageExpectMatchers;
-    (actual: MobileAndroidLocator): LocatorExpectMatchers;
+    (actual: MobileAndroidApp): MobilePageExpectMatchers;
+    (actual: MobileAndroidLocator): MobileLocatorExpectMatchers;
     <T>(actual: T): Assertion<T>;
 }
 export declare const expect: AllwrightExpect;

package/dist/index.js

@@ -80,6 +80,24 @@ function createLazyLocator(pageResource, selectorFactory) {
         async press(key, options) {
             return (await pageResource.get()).locator(await selectorFactory()).press(key, options);
         },
+        async inputValue(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).inputValue(options);
+        },
+        async selectedOptions(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).selectedOptions(options);
+        },
+        async selectedText(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).selectedText(options);
+        },
+        async isChecked(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).isChecked(options);
+        },
+        async getAttribute(name, options) {
+            return (await pageResource.get()).locator(await selectorFactory()).getAttribute(name, options);
+        },
+        async boundingBox(options) {
+            return (await pageResource.get()).locator(await selectorFactory()).boundingBox(options);
+        },
         async textContent(options) {
             return (await pageResource.get()).locator(await selectorFactory()).textContent(options);
         },
@@ -172,6 +190,27 @@ function createLazyPage(pageResource) {
         async press(selector, key, options) {
             return (await pageResource.get()).press(selector, key, options);
         },
+        async url(options) {
+            return (await pageResource.get()).url(options);
+        },
+        async inputValue(selector, options) {
+            return (await pageResource.get()).inputValue(selector, options);
+        },
+        async selectedOptions(selector, options) {
+            return (await pageResource.get()).selectedOptions(selector, options);
+        },
+        async selectedText(selector, options) {
+            return (await pageResource.get()).selectedText(selector, options);
+        },
+        async isChecked(selector, options) {
+            return (await pageResource.get()).isChecked(selector, options);
+        },
+        async getAttribute(selector, name, options) {
+            return (await pageResource.get()).getAttribute(selector, name, options);
+        },
+        async boundingBox(selector, options) {
+            return (await pageResource.get()).boundingBox(selector, options);
+        },
         async textContent(selector, options) {
             return (await pageResource.get()).textContent(selector, options);
         },

package/package.json

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