feat(browser): add userEvent.wheel API

Author: macarie

packages/browser-playwright/src/commands/index.ts

@@ -16,12 +16,14 @@ import {
 } from './trace'
 import { type } from './type'
 import { upload } from './upload'
+import { wheel } from './wheel'
 
 export default {
   __vitest_upload: upload as typeof upload,
   __vitest_click: click as typeof click,
   __vitest_dblClick: dblClick as typeof dblClick,
   __vitest_tripleClick: tripleClick as typeof tripleClick,
+  __vitest_wheel: wheel as typeof wheel,
   __vitest_takeScreenshot: takeScreenshot as typeof takeScreenshot,
   __vitest_type: type as typeof type,
   __vitest_clear: clear as typeof clear,

packages/browser-playwright/src/commands/wheel.ts

@@ -0,0 +1,21 @@
+import type { Locator, WheelOptionsWithDelta } from 'vitest/browser'
+import type { UserEventCommand } from './utils'
+import { hover } from './hover'
+
+type WheelCommand = (element: Locator | Element, options: WheelOptionsWithDelta) => Promise<void>
+
+export const wheel: UserEventCommand<WheelCommand> = async (
+  context,
+  selector,
+  options,
+) => {
+  await hover(context, selector)
+
+  const times = options.times ?? 1
+  const deltaX = options.delta.x ?? 0
+  const deltaY = options.delta.y ?? 0
+
+  for (let count = 0; count < times; count += 1) {
+    await context.page.mouse.wheel(deltaX, deltaY)
+  }
+}

packages/browser-webdriverio/src/commands/index.ts

@@ -10,12 +10,14 @@ import { tab } from './tab'
 import { type } from './type'
 import { upload } from './upload'
 import { viewport } from './viewport'
+import { wheel } from './wheel'
 
 export default {
   __vitest_upload: upload as typeof upload,
   __vitest_click: click as typeof click,
   __vitest_dblClick: dblClick as typeof dblClick,
   __vitest_tripleClick: tripleClick as typeof tripleClick,
+  __vitest_wheel: wheel as typeof wheel,
   __vitest_takeScreenshot: takeScreenshot as typeof takeScreenshot,
   __vitest_type: type as typeof type,
   __vitest_clear: clear as typeof clear,

packages/browser-webdriverio/src/commands/wheel.ts

@@ -0,0 +1,28 @@
+import type { Locator, WheelOptionsWithDelta } from 'vitest/browser'
+import type { UserEventCommand } from './utils'
+
+type WheelCommand = (element: Locator | Element, options: WheelOptionsWithDelta) => Promise<void>
+
+export const wheel: UserEventCommand<WheelCommand> = async (
+  context,
+  selector,
+  options,
+) => {
+  const browser = context.browser
+  const times = options.times ?? 1
+  const deltaX = options.delta.x ?? 0
+  const deltaY = options.delta.y ?? 0
+
+  let action = browser.action('wheel')
+  const wheelOptions: Parameters<typeof action['scroll']>[0] = {
+    deltaX,
+    deltaY,
+    origin: browser.$(selector),
+  }
+
+  for (let count = 0; count < times; count += 1) {
+    action = action.scroll(wheelOptions)
+  }
+
+  await action.perform()
+}

packages/browser/context.d.ts

@@ -1,5 +1,5 @@
 import { SerializedConfig } from 'vitest'
-import { StringifyOptions, BrowserCommands } from 'vitest/internal/browser'
+import { AtLeastOneOf, ExactlyOneOf, StringifyOptions, BrowserCommands } from 'vitest/internal/browser'
 import { ARIARole } from './aria-role.js'
 import {} from './matchers.js'
 
@@ -207,6 +207,24 @@ 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>
+  /**
+   * Simulates wheel events 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.
+   *
+   * @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: WheelOptions): 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.
@@ -344,6 +362,43 @@ export interface UserEventDoubleClickOptions {}
 export interface UserEventTripleClickOptions {}
 export interface UserEventDragAndDropOptions {}
 export interface UserEventUploadOptions {}
+/**
+ * Options for simulating wheel events.
+ *
+ * Specify scrolling using either `delta` for precise pixel values, or `direction` for semantic scrolling. These are mutually exclusive.
+ *
+ * @example
+ * // Precise control with delta
+ * { delta: { y: -100 } }
+ *
+ * @example
+ * // Semantic scrolling with direction
+ * { direction: 'down', times: 3 }
+ */
+export type WheelOptions = ExactlyOneOf<
+  {
+    /**
+     * 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: AtLeastOneOf<{ x: number, y: number }>,
+    /**
+     * Semantic scroll direction. Use this for readable tests when exact pixel values don't matter.
+     */
+    direction: 'up' | 'down' | 'left' | 'right',
+    /**
+     * Number of wheel events to fire. Defaults to `1`.
+     *
+     * Useful for simulating multiple scroll steps in a single call.
+     */
+    times?: number,
+  },
+  'delta' | 'direction'
+>
+
+export type WheelOptionsWithDelta = Extract<WheelOptions, { delta: { x?: number; y?: number } }>
 
 export interface LocatorOptions {
   /**
@@ -489,6 +544,24 @@ export interface Locator extends LocatorSelectors {
    * @see {@link https://vitest.dev/api/browser/interactivity#userevent-tripleclick}
    */
   tripleClick(options?: UserEventTripleClickOptions): Promise<void>
+  /**
+   * Simulates wheel events 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.
+   *
+   * @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: WheelOptions): Promise<void>
   /**
    * Clears the input element content
    * @see {@link https://vitest.dev/api/browser/interactivity#userevent-clear}

packages/browser/src/client/tester/context.ts

@@ -9,14 +9,16 @@ import type {
   Locator,
   LocatorSelectors,
   UserEvent,
+  WheelOptions,
+  WheelOptionsWithDelta,
 } from 'vitest/browser'
 import type { StringifyOptions } from 'vitest/internal/browser'
 import type { IframeViewportEvent } from '../client'
 import type { BrowserRunnerState } from '../utils'
 import type { Locator as LocatorAPI } from './locators/index'
 import { __INTERNAL, stringify } from 'vitest/internal/browser'
 import { ensureAwaited, getBrowserState, getWorkerState } from '../utils'
-import { convertToSelector, processTimeoutOptions } from './tester-utils'
+import { convertToSelector, isLocator, processTimeoutOptions } from './tester-utils'
 
 // this file should not import anything directly, only types and utils
 
@@ -25,6 +27,44 @@ const provider = __vitest_browser_runner__.provider
 const sessionId = getBrowserState().sessionId
 const channel = new BroadcastChannel(`vitest:${sessionId}`)
 
+const DEFAULT_SCROLL_DISTANCE = 100
+
+function resolveWheelOptions(options: WheelOptions): WheelOptionsWithDelta {
+  let delta: WheelOptionsWithDelta['delta']
+
+  if (options.delta) {
+    delta = options.delta
+  }
+  else {
+    switch (options.direction) {
+      case 'up': {
+        delta = { x: 0, y: -DEFAULT_SCROLL_DISTANCE }
+        break
+      }
+
+      case 'down': {
+        delta = { x: 0, y: DEFAULT_SCROLL_DISTANCE }
+        break
+      }
+
+      case 'left': {
+        delta = { x: -DEFAULT_SCROLL_DISTANCE, y: 0 }
+        break
+      }
+
+      case 'right': {
+        delta = { x: DEFAULT_SCROLL_DISTANCE, y: 0 }
+        break
+      }
+    }
+  }
+
+  return {
+    delta,
+    times: options.times,
+  }
+}
+
 function triggerCommand<T>(command: string, args: any[], error?: Error) {
   return getBrowserState().commands.triggerCommand<T>(command, args, error)
 }
@@ -69,6 +109,22 @@ export function createUserEvent(__tl_user_event_base__?: TestingLibraryUserEvent
     tripleClick(element, options) {
       return convertToLocator(element).tripleClick(options)
     },
+    wheel(elementOrOptions: Element | Locator, options: WheelOptions) {
+      return ensureAwaited<void>(async () => {
+        await convertToLocator(elementOrOptions).wheel(resolveWheelOptions(options))
+
+        const browser = getBrowserState().config.browser.name
+
+        // looks like on Chromium the scroll event gets dispatched a frame later
+        if (browser === 'chromium' || browser === 'chrome') {
+          return new Promise((resolve) => {
+            requestAnimationFrame(() => {
+              resolve()
+            })
+          })
+        }
+      })
+    },
     selectOptions(element, value, options) {
       return convertToLocator(element).selectOptions(value, options)
     },
@@ -230,6 +286,27 @@ function createPreviewUserEvent(userEventBase: TestingLibraryUserEvent, options:
     async paste() {
       await userEvent.paste(clipboardData)
     },
+    async wheel(element: Element | Locator, options: WheelOptions) {
+      const resolvedElement = isLocator(element) ? element.element() : element
+      const resolvedOptions = resolveWheelOptions(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,
+      })
+
+      resolvedElement.dispatchEvent(wheelEvent)
+    },
   }
 
   for (const [name, fn] of Object.entries(vitestUserEvent)) {

packages/browser/src/client/tester/locators/index.ts

@@ -10,6 +10,7 @@ import type {
   UserEventHoverOptions,
   UserEventSelectOptions,
   UserEventUploadOptions,
+  WheelOptions,
 } from 'vitest/browser'
 import {
   asLocator,
@@ -86,6 +87,10 @@ export abstract class Locator {
     return this.triggerCommand<void>('__vitest_tripleClick', this.selector, options)
   }
 
+  public wheel(options: WheelOptions): Promise<void> {
+    return this.triggerCommand<void>('__vitest_wheel', this.selector, options)
+  }
+
   public clear(options?: UserEventClearOptions): Promise<void> {
     return this.triggerCommand<void>('__vitest_clear', this.selector, options)
   }

packages/utils/src/index.ts

@@ -4,9 +4,11 @@ export type { SafeTimers } from './timers'
 export type {
   ArgumentsType,
   Arrayable,
+  AtLeastOneOf,
   Awaitable,
   Constructable,
   DeepMerge,
+  ExactlyOneOf,
   MergeInsertions,
   Nullable,
   ParsedStack,

packages/utils/src/types.ts

@@ -43,3 +43,51 @@ export interface TestError extends SerializedError {
   actual?: string
   expected?: string
 }
+
+/**
+ * Requires at least one of the specified keys to be present.
+ * Other keys in the set remain optional.
+ *
+ * @template T - The object type.
+ * @template K - The keys of which at least one is required. Defaults to all keys.
+ *
+ * @example
+ * type Point = AtLeastOneOf<{ x: number; y: number }>
+ *
+ * const a: Point = { x: 1 }
+ * const b: Point = { y: 2 }
+ * const c: Point = { x: 1, y: 2 }
+ *
+ * @example
+ *  type Action = AtLeastOneOf<{ id: number; name: string; force: boolean }, 'id' | 'name'>
+ *
+ * const a: Action = { id: 1, force: false }
+ * const b: Action = { name: 'foo', force: true }
+ * const c: Action = { id: 1, name: 'foo', force: true }
+ */
+export type AtLeastOneOf<T extends Record<PropertyKey, unknown>, K extends keyof T = keyof T> = {
+  [Key in K]: Required<Pick<T, Key>> & Partial<Pick<T, Exclude<K, Key>>>
+}[K] & Omit<T, K>
+
+/**
+ * Requires exactly one of the specified keys to be present.
+ * Other keys in the set are forbidden.
+ *
+ * @template T - The object type.
+ * @template K - The keys of which exactly one is required. Defaults to all keys.
+ *
+ * @example
+ * type Input = ExactlyOneOf<{ a: string; b: string }>
+ *
+ * const a: Input = { a: 'foo' }
+ * const b: Input = { b: 'bar' }
+ *
+ *  @example
+ * type Query = ExactlyOneOf<{ id: number; path: string; all: boolean }, 'id' | 'path'>
+ *
+ * const a: Query = { id: 1, all: true }
+ * const b: Query = { path: 'foo', fall: false }
+ */
+export type ExactlyOneOf<T extends Record<PropertyKey, unknown>, K extends keyof T = keyof T> = {
+  [Key in K]: Required<Pick<T, Key>> & Partial<Record<Exclude<K, Key>, never>>
+}[K] & Omit<T, K>

packages/vitest/src/public/browser.ts

@@ -10,7 +10,7 @@ export {
 } from '../runtime/setup-common'
 export { collectTests, startTests } from '@vitest/runner'
 export * as SpyModule from '@vitest/spy'
-export type { LoupeOptions, ParsedStack, StringifyOptions } from '@vitest/utils'
+export type { AtLeastOneOf, ExactlyOneOf, LoupeOptions, ParsedStack, StringifyOptions } from '@vitest/utils'
 export {
   format,
   inspect,