@voidzero-dev/vite-plus-test 0.1.8 → 0.1.10

package/dist/@vitest/browser/context.d.ts

@@ -1,5 +1,5 @@
 import { SerializedConfig } from '../../index.js'
-import { StringifyOptions, BrowserCommands } from '../../browser.js'
+import { StringifyOptions, CDPSession, BrowserCommands } from '../../browser.js'
 import { ARIARole } from './aria-role.js'
 import {} from './matchers.js'
 
@@ -17,11 +17,12 @@ export type BufferEncoding =
   | 'binary'
   | 'hex'
 
-export interface CDPSession {
-  // methods are defined by the provider type augmentation
-}
+export { CDPSession };
 
-export interface ScreenshotOptions {
+export interface ScreenshotOptions extends SelectorOptions {
+  /**
+   * The HTML element to screeshot.
+   */
   element?: Element | Locator
   /**
    * Path relative to the current test file.
@@ -40,6 +41,14 @@ export interface ScreenshotOptions {
   save?: boolean
 }
 
+export interface MarkOptions {
+  /**
+   * Optional stack string used to resolve marker location.
+   * Useful for wrapper libraries that need to forward the end-user callsite.
+   */
+  stack?: string
+}
+
 interface StandardScreenshotComparators {
   pixelmatch: {
     /**
@@ -157,7 +166,7 @@ export interface ScreenshotMatcherOptions<
   comparatorOptions?: ScreenshotComparatorRegistry[ComparatorName]
   screenshotOptions?: Omit<
     ScreenshotOptions,
-    'element' | 'base64' | 'path' | 'save' | 'type'
+    'element' | 'base64' | 'path' | 'save' | 'type' | 'strict' | 'timeout'
   >
   /**
    * Time to wait until a stable screenshot is found.
@@ -168,6 +177,13 @@ export interface ScreenshotMatcherOptions<
    * @default 5000
    */
   timeout?: number
+  /**
+   * Allow only a single element with the same locator.
+   *
+   * If Vitest finds multiple elements, it will throw an error immediately without retrying.
+   * @default true
+   */
+  strict?: boolean
 }
 
 export interface UserEvent {
@@ -207,6 +223,25 @@ export interface UserEvent {
    * @see {@link https://testing-library.com/docs/user-event/convenience/#tripleclick} testing-library API
    */
   tripleClick: (element: Element | Locator, options?: UserEventTripleClickOptions) => Promise<void>
+  /**
+   * Triggers a {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/wheel_event|`wheel` event} on an element.
+   *
+   * @param element - The target element to receive wheel events.
+   * @param options - Scroll configuration using `delta` or `direction`.
+   * @returns A promise that resolves when all wheel events have been dispatched.
+   *
+   * @since 4.1.0
+   * @see {@link https://vitest.dev/api/browser/interactivity#userevent-wheel}
+   *
+   * @example
+   * // Scroll down by 100 pixels
+   * await userEvent.wheel(container, { delta: { y: 100 } })
+   *
+   * @example
+   * // Scroll up 5 times
+   * await userEvent.wheel(container, { direction: 'up', times: 5 })
+   */
+  wheel(element: Element | Locator, options: UserEventWheelOptions): Promise<void>
   /**
    * Choose one or more values from a select element. Uses provider's API under the hood.
    * If select doesn't have `multiple` attribute, only the first value will be selected.
@@ -345,6 +380,58 @@ export interface UserEventTripleClickOptions {}
 export interface UserEventDragAndDropOptions {}
 export interface UserEventUploadOptions {}
 
+/**
+ * Base options shared by all wheel event configurations.
+ *
+ * @since 4.1.0
+ */
+export interface UserEventWheelBaseOptions {
+  /**
+   * Number of wheel events to fire. Defaults to `1`.
+   *
+   * Useful for triggering multiple scroll steps in a single call.
+   */
+  times?: number
+}
+
+/**
+ * Wheel options using pixel-based `delta` values for precise scroll control.
+ *
+ * @since 4.1.0
+ */
+export interface UserEventWheelDeltaOptions extends UserEventWheelBaseOptions {
+  /**
+   * Precise scroll delta values in pixels. At least one axis must be specified.
+   *
+   * - Positive `y` scrolls down, negative `y` scrolls up.
+   * - Positive `x` scrolls right, negative `x` scrolls left.
+   */
+  delta: { x: number; y?: number } | { x?: number; y: number }
+  direction?: undefined
+}
+
+/**
+ * Wheel options using semantic `direction` values for simpler scroll control.
+ *
+ * @since 4.1.0
+ */
+export interface UserEventWheelDirectionOptions extends UserEventWheelBaseOptions {
+  /**
+   * Semantic scroll direction. Use this for readable tests when exact pixel values don't matter.
+   */
+  direction: 'up' | 'down' | 'left' | 'right'
+  delta?: undefined
+}
+
+/**
+ * Options for triggering wheel events.
+ *
+ * Specify scrolling using either `delta` for precise pixel values, or `direction` for semantic scrolling. These are mutually exclusive.
+ *
+ * @since 4.1.0
+ */
+export type UserEventWheelOptions = UserEventWheelDeltaOptions | UserEventWheelDirectionOptions
+
 export interface LocatorOptions {
   /**
    * Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
@@ -408,7 +495,7 @@ export interface LocatorByRoleOptions extends LocatorOptions {
   selected?: boolean
 }
 
-interface LocatorScreenshotOptions extends Omit<ScreenshotOptions, 'element'> {}
+export interface LocatorScreenshotOptions extends Omit<ScreenshotOptions, 'element'> {}
 
 export interface LocatorSelectors {
   /**
@@ -443,7 +530,7 @@ export interface LocatorSelectors {
    */
   getByTitle: (text: string | RegExp, options?: LocatorOptions) => Locator
   /**
-   * Creates a locator capable of finding an element that matches the specified test id attribute. You can configure the attribute name with [`browser.locators.testIdAttribute`](/config/#browser-locators-testidattribute).
+   * Creates a locator capable of finding an element that matches the specified test id attribute. You can configure the attribute name with [`browser.locators.testIdAttribute`](https://vitest.dev/config/browser/locators#browser-locators-testidattribute).
    * @see {@link https://vitest.dev/api/browser/locators#getbytestid}
    */
   getByTestId: (text: string | RegExp) => Locator
@@ -451,6 +538,22 @@ export interface LocatorSelectors {
 
 export interface FrameLocator extends LocatorSelectors {}
 
+export interface SelectorOptions {
+  /**
+   * How long to wait until a single element is found. By default, this has the same timeout as the test.
+   *
+   * Vitest will try to find the element in ever increasing intervals: 0, 20, 50, 100, 100, 500.
+   */
+  timeout?: number
+  /**
+   * Allow only a single element with the same locator.
+   *
+   * If Vitest finds multiple elements, it will throw an error immediately without retrying.
+   * @default true
+   */
+  strict?: boolean
+}
+
 export interface Locator extends LocatorSelectors {
   /**
    * Selector string that will be used to locate the element by the browser provider.
@@ -489,6 +592,24 @@ export interface Locator extends LocatorSelectors {
    * @see {@link https://vitest.dev/api/browser/interactivity#userevent-tripleclick}
    */
   tripleClick(options?: UserEventTripleClickOptions): Promise<void>
+  /**
+   * Triggers a {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/wheel_event|`wheel` event} on an element.
+   *
+   * @param options - Scroll configuration using `delta` or `direction`.
+   * @returns A promise that resolves when all wheel events have been dispatched.
+   *
+   * @since 4.1.0
+   * @see {@link https://vitest.dev/api/browser/interactivity#userevent-wheel}
+   *
+   * @example
+   * // Scroll down by 100 pixels
+   * await container.wheel({ delta: { y: 100 } })
+   *
+   * @example
+   * // Scroll up 5 times
+   * await container.wheel({ direction: 'up', times: 5 })
+   */
+  wheel(options: UserEventWheelOptions): Promise<void>
   /**
    * Clears the input element content
    * @see {@link https://vitest.dev/api/browser/interactivity#userevent-clear}
@@ -538,6 +659,12 @@ export interface Locator extends LocatorSelectors {
   }>
   screenshot(options?: LocatorScreenshotOptions): Promise<string>
 
+  /**
+   * Add a trace marker for this locator when browser tracing is enabled.
+   * @see {@link https://vitest.dev/api/browser/locators#mark}
+   */
+  mark(name: string, options?: MarkOptions): Promise<void>
+
   /**
    * Returns an element matching the selector.
    *
@@ -600,13 +727,27 @@ export interface Locator extends LocatorSelectors {
    * @see {@link https://vitest.dev/api/browser/locators#filter}
    */
   filter(options: LocatorOptions): Locator
+  /**
+   * This method returns an element matching the locator.
+   * Unlike [`.element()`](https://vitest.dev/api/browser/locators#element),
+   * this method will wait and retry until a matching element appears in the DOM,
+   * using increasing intervals (0, 20, 50, 100, 100, 500ms).
+   *
+   * **WARNING:**
+   *
+   * This is an escape hatch for library authors and 3d-party APIs that do not support locators directly.
+   * If you are interacting with the element, use builtin methods instead.
+   * @since 4.1.0
+   * @see {@link https://vitest.dev/api/browser/locators#findelement}
+   */
+  findElement(options?: SelectorOptions): Promise<HTMLElement | SVGElement>
 }
 
 export interface UserEventTabOptions {
   shift?: boolean
 }
 
-export interface UserEventTypeOptions {
+export interface UserEventTypeOptions extends SelectorOptions {
   skipClick?: boolean
   skipAutoClose?: boolean
 }
@@ -687,6 +828,16 @@ export interface BrowserPage extends LocatorSelectors {
     path: string
     base64: string
   }>
+  /**
+   * Add a trace marker when browser tracing is enabled.
+   * @see {@link https://vitest.dev/api/browser/context#mark}
+   */
+  mark(name: string, options?: MarkOptions): Promise<void>
+  /**
+   * Group multiple operations under a trace marker when browser tracing is enabled.
+   * @see {@link https://vitest.dev/api/browser/context#mark}
+   */
+  mark<T>(name: string, body: () => T | Promise<T>, options?: MarkOptions): Promise<T>
   /**
    * Extend default `page` object with custom methods.
    */
@@ -777,7 +928,6 @@ export const utils: {
   /**
    * Configures default options of `prettyDOM` and `debug` functions.
    * This will also affect `vitest-browser-{framework}` package.
-   * @experimental
    */
   configurePrettyDOM(options: StringifyOptions): void
   /**

package/dist/@vitest/browser/context.js

@@ -23,9 +23,11 @@ function ensureAwaited(promise) {
       return (promiseResult ||= promise(sourceError)).then(onFulfilled, onRejected);
     },
     catch(onRejected) {
+      awaited = true;
       return (promiseResult ||= promise(sourceError)).catch(onRejected);
     },
     finally(onFinally) {
+      awaited = true;
       return (promiseResult ||= promise(sourceError)).finally(onFinally);
     },
     [Symbol.toStringTag]: "Promise"
@@ -46,7 +48,6 @@ function getWorkerState() {
   return state;
 }
 
-const provider$1 = getBrowserState().provider;
 /* @__NO_SIDE_EFFECTS__ */
 function convertElementToCssSelector(element) {
   if (!element || !(element instanceof Element)) {
@@ -119,9 +120,9 @@ function getParent(el) {
   }
   return parent;
 }
-const now = Date.now;
+const now = globalThis.performance ? globalThis.performance.now.bind(globalThis.performance) : Date.now;
 function processTimeoutOptions(options_) {
-  if (options_ && options_.timeout != null || provider$1 !== "playwright") {
+  if (options_ && options_.timeout != null) {
     return options_;
   }
   // if there is a default action timeout, use it
@@ -141,7 +142,7 @@ function processTimeoutOptions(options_) {
   options_ = options_ || {};
   const currentTime = now();
   const endTime = startTime + timeout;
-  const remainingTime = endTime - currentTime;
+  const remainingTime = Math.floor(endTime - currentTime);
   if (remainingTime <= 0) {
     return options_;
   }
@@ -149,7 +150,9 @@ function processTimeoutOptions(options_) {
   options_.timeout = remainingTime - 100;
   return options_;
 }
-function convertToSelector(elementOrLocator) {
+const provider$1 = getBrowserState().provider;
+const kElementLocator = Symbol.for("$$vitest:locator-resolved");
+async function convertToSelector(elementOrLocator, options) {
   if (!elementOrLocator) {
     throw new Error("Expected element or locator to be defined.");
   }
@@ -157,7 +160,11 @@ function convertToSelector(elementOrLocator) {
     return convertElementToCssSelector(elementOrLocator);
   }
   if (isLocator(elementOrLocator)) {
-    return elementOrLocator.selector;
+    if (provider$1 === "playwright" || kElementLocator in elementOrLocator) {
+      return elementOrLocator.selector;
+    }
+    const element = await elementOrLocator.findElement(options);
+    return convertElementToCssSelector(element);
   }
   throw new Error("Expected element or locator to be an instance of Element or Locator.");
 }
@@ -165,6 +172,36 @@ const kLocator = Symbol.for("$$vitest:locator");
 function isLocator(element) {
   return !!element && typeof element === "object" && kLocator in element;
 }
+const DEFAULT_WHEEL_DELTA = 100;
+function resolveUserEventWheelOptions(options) {
+  let delta;
+  if (options.delta) {
+    delta = options.delta;
+  } else {
+    switch (options.direction) {
+      case "up": {
+        delta = { y: -DEFAULT_WHEEL_DELTA };
+        break;
+      }
+      case "down": {
+        delta = { y: DEFAULT_WHEEL_DELTA };
+        break;
+      }
+      case "left": {
+        delta = { x: -DEFAULT_WHEEL_DELTA };
+        break;
+      }
+      case "right": {
+        delta = { x: DEFAULT_WHEEL_DELTA };
+        break;
+      }
+    }
+  }
+  return {
+    delta,
+    times: options.times
+  };
+}
 
 // this file should not import anything directly, only types and utils
 // @ts-expect-error not typed global
@@ -186,10 +223,10 @@ function createUserEvent(__tl_user_event_base__, options) {
     setup() {
       return createUserEvent();
     },
-    async cleanup() {
+    cleanup() {
       // avoid cleanup rpc call if there is nothing to cleanup
       if (!keyboard.unreleased.length) {
-        return;
+        return Promise.resolve();
       }
       return ensureAwaited(async (error) => {
         await triggerCommand("__vitest_cleanup", [keyboard], error);
@@ -205,6 +242,9 @@ function createUserEvent(__tl_user_event_base__, options) {
     tripleClick(element, options) {
       return convertToLocator(element).tripleClick(options);
     },
+    wheel(elementOrOptions, options) {
+      return convertToLocator(elementOrOptions).wheel(options);
+    },
     selectOptions(element, value, options) {
       return convertToLocator(element).selectOptions(value, options);
     },
@@ -228,9 +268,9 @@ function createUserEvent(__tl_user_event_base__, options) {
       const targetLocator = convertToLocator(target);
       return sourceLocator.dropTo(targetLocator, options);
     },
-    async type(element, text, options) {
+    type(element, text, options) {
       return ensureAwaited(async (error) => {
-        const selector = convertToSelector(element);
+        const selector = await convertToSelector(element, options);
         const { unreleased } = await triggerCommand("__vitest_type", [
           selector,
           text,
@@ -245,20 +285,20 @@ function createUserEvent(__tl_user_event_base__, options) {
     tab(options = {}) {
       return ensureAwaited((error) => triggerCommand("__vitest_tab", [options], error));
     },
-    async keyboard(text) {
+    keyboard(text) {
       return ensureAwaited(async (error) => {
         const { unreleased } = await triggerCommand("__vitest_keyboard", [text, keyboard], error);
         keyboard.unreleased = unreleased;
       });
     },
-    async copy() {
-      await userEvent.keyboard(`{${modifier}>}{c}{/${modifier}}`);
+    copy() {
+      return userEvent.keyboard(`{${modifier}>}{c}{/${modifier}}`);
     },
-    async cut() {
-      await userEvent.keyboard(`{${modifier}>}{x}{/${modifier}}`);
+    cut() {
+      return userEvent.keyboard(`{${modifier}>}{x}{/${modifier}}`);
     },
-    async paste() {
-      await userEvent.keyboard(`{${modifier}>}{v}{/${modifier}}`);
+    paste() {
+      return userEvent.keyboard(`{${modifier}>}{v}{/${modifier}}`);
     }
   };
   return userEvent;
@@ -339,6 +379,26 @@ function createPreviewUserEvent(userEventBase, options) {
     },
     async paste() {
       await userEvent.paste(clipboardData);
+    },
+    async wheel(element, options) {
+      const resolvedElement = isLocator(element) ? element.element() : element;
+      const resolvedOptions = resolveUserEventWheelOptions(options);
+      const rect = resolvedElement.getBoundingClientRect();
+      const centerX = rect.left + rect.width / 2;
+      const centerY = rect.top + rect.height / 2;
+      const wheelEvent = new WheelEvent("wheel", {
+        clientX: centerX,
+        clientY: centerY,
+        deltaY: resolvedOptions.delta.y ?? 0,
+        deltaX: resolvedOptions.delta.x ?? 0,
+        deltaMode: 0,
+        bubbles: true,
+        cancelable: true
+      });
+      const times = options.times ?? 1;
+      for (let count = 0; count < times; count += 1) {
+        resolvedElement.dispatchEvent(wheelEvent);
+      }
     }
   };
   for (const [name, fn] of Object.entries(vitestUserEvent)) {
@@ -390,18 +450,47 @@ const page = {
     screenshotIds[repeatCount] ??= {};
     screenshotIds[repeatCount][taskName] = number + 1;
     const name = options.path || `${taskName.replace(/[^a-z0-9]/gi, "-")}-${number}.png`;
+    const [element, ...mask] = await Promise.all([options.element ? convertToSelector(options.element, options) : undefined, ..."mask" in options ? options.mask.map((el) => convertToSelector(el, options)) : []]);
     const normalizedOptions = "mask" in options ? {
       ...options,
-      mask: options.mask.map(convertToSelector)
+      mask
     } : options;
     return ensureAwaited((error) => triggerCommand("__vitest_screenshot", [name, processTimeoutOptions(
       {
         ...normalizedOptions,
-        element: options.element ? convertToSelector(options.element) : undefined
+        element
       }
       /** TODO */
     )], error));
   },
+  mark(name, bodyOrOptions, options) {
+    const currentTest = getWorkerState().current;
+    const hasActiveTrace = !!currentTest && getBrowserState().activeTraceTaskIds.has(currentTest.id);
+    if (typeof bodyOrOptions === "function") {
+      return ensureAwaited(async (error) => {
+        if (hasActiveTrace) {
+          await triggerCommand("__vitest_groupTraceStart", [{
+            name,
+            stack: options?.stack ?? error?.stack
+          }], error);
+        }
+        try {
+          return await bodyOrOptions();
+        } finally {
+          if (hasActiveTrace) {
+            await triggerCommand("__vitest_groupTraceEnd", [], error);
+          }
+        }
+      });
+    }
+    if (!hasActiveTrace) {
+      return Promise.resolve();
+    }
+    return ensureAwaited((error) => triggerCommand("__vitest_markTrace", [{
+      name,
+      stack: bodyOrOptions?.stack ?? error?.stack
+    }], error));
+  },
   getByRole() {
     throw new Error(`Method "getByRole" is not supported by the "${provider}" provider.`);
   },
@@ -524,9 +613,6 @@ function getElementError(selector, container) {
   error.name = "VitestBrowserElementError";
   return error;
 }
-/**
-* @experimental
-*/
 function configurePrettyDOM(options) {
   defaultOptions = options;
 }