feat: add userEvent.tripleClick API (#773)

src/click.ts

@@ -45,3 +45,19 @@ export function dblClick(
 
   this.pointer({keys: '[MouseLeft][MouseLeft]', target: element})
 }
+
+export function tripleClick(
+  this: UserEvent,
+  element: Element,
+  init?: MouseEventInit,
+  {skipPointerEventsCheck = false}: clickOptions & PointerOptions = {},
+) {
+  if (!skipPointerEventsCheck && !hasPointerEvents(element)) {
+    throw new Error(
+      'unable to triple-click element as it has or inherits pointer-events set to "none".',
+    )
+  }
+  this.hover(element, init, {skipPointerEventsCheck: true})
+
+  this.pointer({keys: '[MouseLeft][MouseLeft][MouseLeft]', target: element})
+}

src/setup.ts

@@ -1,5 +1,5 @@
 import {clear} from './clear'
-import {click, clickOptions, dblClick} from './click'
+import {click, clickOptions, dblClick, tripleClick} from './click'
 import {prepareDocument} from './document'
 import {hover, unhover} from './hover'
 import {createKeyboardState, keyboard, keyboardOptions} from './keyboard'
@@ -24,6 +24,7 @@ export const userEventApis = {
   pointer,
   selectOptions,
   tab,
+  tripleClick,
   type,
   unhover,
   upload,
@@ -193,6 +194,10 @@ function _setup(
       return tab.call(userEvent, ...args)
     },
 
+    tripleClick: (...args: Parameters<typeof tripleClick>) => {
+      return tripleClick.call(userEvent, ...args)
+    },
+
     // type needs typecasting because of the overloading
     type: ((...args: Parameters<typeof type>) => {
       args[2] = {...typeDefaults, ...args[2]}

tests/click/tripleClick.ts

@@ -0,0 +1,54 @@
+import userEvent from '#src'
+import {getUISelection} from '#src/document'
+import {setup} from '#testHelpers/utils'
+
+test('select input per triple click', () => {
+  const {element, getEventSnapshot} = setup<HTMLInputElement>(
+    `<input value="foo bar"/>`,
+  )
+
+  userEvent.tripleClick(element)
+
+  expect(element).toHaveFocus()
+  expect(getUISelection(element)).toEqual({selectionStart: 0, selectionEnd: 7})
+
+  expect(getEventSnapshot()).toMatchInlineSnapshot(`
+    Events fired on: input[value="foo bar"]
+
+    input[value="foo bar"] - pointerover
+    input[value="foo bar"] - pointerenter
+    input[value="foo bar"] - mouseover
+    input[value="foo bar"] - mouseenter
+    input[value="foo bar"] - pointermove
+    input[value="foo bar"] - mousemove
+    input[value="foo bar"] - pointerdown
+    input[value="foo bar"] - mousedown
+    input[value="foo bar"] - focus
+    input[value="foo bar"] - focusin
+    input[value="foo bar"] - select
+    input[value="foo bar"] - pointerup
+    input[value="foo bar"] - mouseup
+    input[value="foo bar"] - click
+    input[value="foo bar"] - pointerdown
+    input[value="foo bar"] - mousedown
+    input[value="foo bar"] - select
+    input[value="foo bar"] - pointerup
+    input[value="foo bar"] - mouseup
+    input[value="foo bar"] - click
+    input[value="foo bar"] - dblclick
+    input[value="foo bar"] - pointerdown
+    input[value="foo bar"] - mousedown
+    input[value="foo bar"] - select
+    input[value="foo bar"] - pointerup
+    input[value="foo bar"] - mouseup
+    input[value="foo bar"] - click
+  `)
+})
+
+test('check for pointer-events', () => {
+  const {element} = setup<HTMLInputElement>(
+    `<input value="foo bar" style="pointer-events: none"/>`,
+  )
+
+  expect(() => userEvent.tripleClick(element)).toThrow()
+})

tests/setup.ts

@@ -70,7 +70,9 @@ function mockApis(modulePath: string, ...vars: string[]) {
 
 // List of API functions per module
 jest.mock('#src/clear', () => mockApis('#src/clear', 'clear'))
-jest.mock('#src/click', () => mockApis('#src/click', 'click', 'dblClick'))
+jest.mock('#src/click', () =>
+  mockApis('#src/click', 'click', 'dblClick', 'tripleClick'),
+)
 jest.mock('#src/hover', () => mockApis('#src/hover', 'hover', 'unhover'))
 jest.mock('#src/keyboard', () => mockApis('#src/keyboard', 'keyboard'))
 jest.mock('#src/paste', () => mockApis('#src/paste', 'paste'))
@@ -236,6 +238,10 @@ cases<APICase>(
     tab: {
       api: 'tab',
     },
+    tripleClick: {
+      api: 'tripleClick',
+      elementArg: 0,
+    },
     type: {
       api: 'type',
       args: [null, 'foo'],