feat(pointer)!: introduce pointerEventsCheck option (#823)

BREAKING CHANGE: `skipPointerEvents` has been removed.
Use `pointerEventsCheck: PointerEventsCheckLevel.Never` instead.

Author: ph-fritsche

src/clipboard/copy.ts

@@ -1,8 +1,8 @@
 import {fireEvent} from '@testing-library/dom'
-import {Config, UserEvent} from '../setup'
+import {Config, Instance} from '../setup'
 import {copySelection, writeDataTransferToClipboard} from '../utils'
 
-export async function copy(this: UserEvent) {
+export async function copy(this: Instance) {
   const doc = this[Config].document
   const target = doc.activeElement ?? /* istanbul ignore next */ doc.body
 

src/clipboard/cut.ts

@@ -1,13 +1,13 @@
 import {fireEvent} from '@testing-library/dom'
-import {Config, UserEvent} from '../setup'
+import {Config, Instance} from '../setup'
 import {
   copySelection,
   isEditable,
   prepareInput,
   writeDataTransferToClipboard,
 } from '../utils'
 
-export async function cut(this: UserEvent) {
+export async function cut(this: Instance) {
   const doc = this[Config].document
   const target = doc.activeElement ?? /* istanbul ignore next */ doc.body
 

src/clipboard/paste.ts

@@ -1,5 +1,5 @@
 import {fireEvent} from '@testing-library/dom'
-import {Config, UserEvent} from '../setup'
+import {Config, Instance} from '../setup'
 import {
   createDataTransfer,
   getSpaceUntilMaxLength,
@@ -9,7 +9,7 @@ import {
 } from '../utils'
 
 export async function paste(
-  this: UserEvent,
+  this: Instance,
   clipboardData?: DataTransfer | string,
 ) {
   const doc = this[Config].document

src/convenience/click.ts

@@ -1,14 +1,7 @@
 import type {PointerInput} from '../pointer'
-import {hasPointerEvents} from '../utils'
-import {Config, UserEvent} from '../setup'
-
-export async function click(this: UserEvent, element: Element): Promise<void> {
-  if (!this[Config].skipPointerEventsCheck && !hasPointerEvents(element)) {
-    throw new Error(
-      'unable to click element as it has or inherits pointer-events set to "none".',
-    )
-  }
+import {Config, Instance} from '../setup'
 
+export async function click(this: Instance, element: Element): Promise<void> {
   const pointerIn: PointerInput = []
   if (!this[Config].skipHover) {
     pointerIn.push({target: element})
@@ -19,27 +12,15 @@ export async function click(this: UserEvent, element: Element): Promise<void> {
 }
 
 export async function dblClick(
-  this: UserEvent,
+  this: Instance,
   element: Element,
 ): Promise<void> {
-  if (!this[Config].skipPointerEventsCheck && !hasPointerEvents(element)) {
-    throw new Error(
-      'unable to double-click element as it has or inherits pointer-events set to "none".',
-    )
-  }
-
   return this.pointer([{target: element}, '[MouseLeft][MouseLeft]'])
 }
 
 export async function tripleClick(
-  this: UserEvent,
+  this: Instance,
   element: Element,
 ): Promise<void> {
-  if (!this[Config].skipPointerEventsCheck && !hasPointerEvents(element)) {
-    throw new Error(
-      'unable to triple-click element as it has or inherits pointer-events set to "none".',
-    )
-  }
-
   return this.pointer([{target: element}, '[MouseLeft][MouseLeft][MouseLeft]'])
 }

src/convenience/hover.ts

@@ -1,22 +1,9 @@
-import {Config, UserEvent} from '../setup'
-import {hasPointerEvents} from '../utils'
-
-export async function hover(this: UserEvent, element: Element) {
-  if (!this[Config].skipPointerEventsCheck && !hasPointerEvents(element)) {
-    throw new Error(
-      'unable to hover element as it has or inherits pointer-events set to "none".',
-    )
-  }
+import {Instance} from '../setup'
 
+export async function hover(this: Instance, element: Element) {
   return this.pointer({target: element})
 }
 
-export async function unhover(this: UserEvent, element: Element) {
-  if (!this[Config].skipPointerEventsCheck && !hasPointerEvents(element)) {
-    throw new Error(
-      'unable to unhover element as it has or inherits pointer-events set to "none".',
-    )
-  }
-
+export async function unhover(this: Instance, element: Element) {
   return this.pointer({target: element.ownerDocument.body})
 }

src/convenience/tab.ts

@@ -1,7 +1,7 @@
-import type {UserEvent} from '../setup'
+import type {Instance} from '../setup'
 
 export async function tab(
-  this: UserEvent,
+  this: Instance,
   {
     shift,
   }: {

src/index.ts

@@ -1,3 +1,4 @@
 export {userEvent as default} from './setup'
 export type {keyboardKey} from './keyboard'
 export type {pointerKey} from './pointer'
+export {PointerEventsCheckLevel} from './options'

src/keyboard/index.ts

@@ -1,12 +1,12 @@
-import {Config, UserEvent} from '../setup'
+import {Config, Instance} from '../setup'
 import {keyboardAction, KeyboardAction, releaseAllKeys} from './keyboardAction'
 import {parseKeyDef} from './parseKeyDef'
 import type {keyboardState, keyboardKey} from './types'
 
 export {releaseAllKeys}
 export type {keyboardKey, keyboardState}
 
-export async function keyboard(this: UserEvent, text: string): Promise<void> {
+export async function keyboard(this: Instance, text: string): Promise<void> {
   const {keyboardMap} = this[Config]
 
   const actions: KeyboardAction[] = parseKeyDef(keyboardMap, text)

src/options.ts

@@ -3,6 +3,20 @@ import type {pointerKey} from './pointer/types'
 import {defaultKeyMap as defaultKeyboardMap} from './keyboard/keyMap'
 import {defaultKeyMap as defaultPointerMap} from './pointer/keyMap'
 
+export enum PointerEventsCheckLevel {
+  /**
+   * Check pointer events on every user interaction that triggers a bunch of events.
+   * E.g. once for releasing a mouse button even though this triggers `pointerup`, `mouseup`, `click`, etc...
+   */
+  EachTrigger = 4,
+  /** Check each target once per call to pointer (related) API */
+  EachApiCall = 2,
+  /** Check each event target once */
+  EachTarget = 1,
+  /** No pointer events check */
+  Never = 0,
+}
+
 export interface Options {
   /**
    * When using `userEvent.upload`, automatically discard files
@@ -61,6 +75,17 @@ export interface Options {
    */
   pointerMap?: pointerKey[]
 
+  /**
+   * The pointer API includes a check if an element has or inherits `pointer-events: none`.
+   * This check is known to be expensive and very expensive when checking deeply nested nodes.
+   * This option determines how often the pointer related APIs perform the check.
+   *
+   * This is a binary flag option. You can combine multiple Levels.
+   *
+   * @default PointerEventsCheckLevel.EachCall
+   */
+  pointerEventsCheck?: PointerEventsCheckLevel | number
+
   /**
    * `userEvent.type` automatically releases any keys still pressed at the end of the call.
    * This option allows to opt out of this feature.
@@ -85,15 +110,6 @@ export interface Options {
    */
   skipHover?: boolean
 
-  /**
-   * Calling pointer related APIs on an element triggers a check if that element can receive pointer events.
-   * This check is known to be expensive.
-   * This option allows to skip the check.
-   *
-   * @default false
-   */
-  skipPointerEventsCheck?: boolean
-
   /**
    * Write selected data to Clipboard API when a `cut` or `copy` is triggered.
    *
@@ -116,10 +132,10 @@ export const defaultOptionsDirect: Required<Options> = {
   document: global.document,
   keyboardMap: defaultKeyboardMap,
   pointerMap: defaultPointerMap,
+  pointerEventsCheck: PointerEventsCheckLevel.EachApiCall,
   skipAutoClose: false,
   skipClick: false,
   skipHover: false,
-  skipPointerEventsCheck: false,
   writeToClipboard: false,
 }
 

src/pointer/index.ts

@@ -1,4 +1,4 @@
-import {Config, UserEvent} from '../setup'
+import {Config, Instance} from '../setup'
 import {parseKeyDef} from './parseKeyDef'
 import {
   pointerAction,
@@ -16,7 +16,7 @@ type PointerActionInput =
 export type PointerInput = PointerActionInput | Array<PointerActionInput>
 
 export async function pointer(
-  this: UserEvent,
+  this: Instance,
   input: PointerInput,
 ): Promise<void> {
   const {pointerMap} = this[Config]