feat(hover): Add hover API (fixes #254)

README.md

@@ -50,7 +50,6 @@ change the state of the checkbox.
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-
 - [Installation](#installation)
 - [API](#api)
   - [`click(element)`](#clickelement)
@@ -61,6 +60,8 @@ change the state of the checkbox.
   - [`selectOptions(element, values)`](#selectoptionselement-values)
   - [`toggleSelectOptions(element, values)`](#toggleselectoptionselement-values)
   - [`tab({shift, focusTrap})`](#tabshift-focustrap)
+  - [`async hover(element)`](#async-hoverelement)
+  - [`async unhover(element)`](#async-unhoverelement)
 - [Issues](#issues)
   - [🐛 Bugs](#-bugs)
   - [💡 Feature Requests](#-feature-requests)
@@ -398,6 +399,56 @@ it('should cycle elements in document tab order', () => {
 })
 ```
 
+### `async hover(element)`
+
+Hovers over `element`.
+
+```jsx
+import React from 'react'
+import {render, screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+test('hover', async () => {
+  const handler = jest.fn()
+  render(
+    <button
+      data-testid="button"
+      onMouseEnter={handler}
+      onMouseOver={handler}
+      onMouseMove={handler}
+    />,
+  )
+
+  await userEvent.hover(screen.getByTestId('button'))
+  expect(handler).toHaveBeenCalledTimes(3)
+})
+```
+
+### `async unhover(element)`
+
+Unhovers out of `element`.
+
+```jsx
+import React from 'react'
+import {render, screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+test('unhover', async () => {
+  const handler = jest.fn()
+  render(
+    <button
+      data-testid="button"
+      onMouseMove={handler}
+      onMouseOut={handler}
+      onMouseLeave={handler}
+    />,
+  )
+
+  await userEvent.unhover(screen.getByTestId('button'))
+  expect(handler).toHaveBeenCalledTimes(3)
+})
+```
+
 ## Issues
 
 _Looking to contribute? Look for the [Good First Issue][good-first-issue]
@@ -482,6 +533,7 @@ Thanks goes to these people ([emoji key][emojis]):
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors][all-contributors] specification.

src/__tests__/hover.js

@@ -0,0 +1,31 @@
+import React from 'react'
+import {render, screen} from '@testing-library/react'
+import userEvent from '..'
+import {setup} from './helpers/utils'
+
+test('hover', async () => {
+  const {element, getEventCalls} = setup(<button />)
+
+  await userEvent.hover(element)
+  expect(getEventCalls()).toMatchInlineSnapshot(`
+    mouseenter: Left (0)
+    mouseover: Left (0)
+    mousemove: Left (0)
+  `)
+})
+
+test('hover should fire events', async () => {
+  const handler = jest.fn()
+  render(
+    // eslint-disable-next-line jsx-a11y/mouse-events-have-key-events
+    <button
+      data-testid="button"
+      onMouseEnter={handler}
+      onMouseOver={handler}
+      onMouseMove={handler}
+    />,
+  )
+
+  await userEvent.hover(screen.getByTestId('button'))
+  expect(handler).toHaveBeenCalledTimes(3)
+})

src/__tests__/unhover.js

@@ -0,0 +1,31 @@
+import React from 'react'
+import {render, screen} from '@testing-library/react'
+import userEvent from '..'
+import {setup} from './helpers/utils'
+
+test('unhover', async () => {
+  const {element, getEventCalls} = setup(<button />)
+
+  await userEvent.unhover(element)
+  expect(getEventCalls()).toMatchInlineSnapshot(`
+    mousemove: Left (0)
+    mouseout: Left (0)
+    mouseleave: Left (0)
+  `)
+})
+
+test('unhover should fire events', async () => {
+  const handler = jest.fn()
+  render(
+    // eslint-disable-next-line jsx-a11y/mouse-events-have-key-events
+    <button
+      data-testid="button"
+      onMouseMove={handler}
+      onMouseOut={handler}
+      onMouseLeave={handler}
+    />,
+  )
+
+  await userEvent.unhover(screen.getByTestId('button'))
+  expect(handler).toHaveBeenCalledTimes(3)
+})

src/index.js

@@ -1,5 +1,6 @@
 import {fireEvent} from '@testing-library/dom'
 import {type} from './type'
+import {tick} from './tick'
 
 function isMousePressEvent(event) {
   return (
@@ -451,6 +452,24 @@ function tab({shift = false, focusTrap = document} = {}) {
   }
 }
 
+async function hover(element, init) {
+  await tick()
+  fireEvent.mouseEnter(element, getMouseEventOptions('mouseenter', init))
+  await tick()
+  fireEvent.mouseOver(element, getMouseEventOptions('mouseover', init))
+  await tick()
+  fireEvent.mouseMove(element, getMouseEventOptions('mousemove', init))
+}
+
+async function unhover(element, init) {
+  await tick()
+  fireEvent.mouseMove(element, getMouseEventOptions('mousemove', init))
+  await tick()
+  fireEvent.mouseOut(element, getMouseEventOptions('mouseout', init))
+  await tick()
+  fireEvent.mouseLeave(element, getMouseEventOptions('mouseleave', init))
+}
+
 const userEvent = {
   click,
   dblClick,
@@ -460,6 +479,8 @@ const userEvent = {
   type,
   upload,
   tab,
+  hover,
+  unhover,
 }
 
 export default userEvent

typings/index.d.ts

@@ -45,6 +45,8 @@ declare const userEvent: {
     userOpts?: ITypeOpts,
   ) => Promise<void>
   tab: (userOpts?: ITabUserOptions) => void
+  hover: (element: TargetElement, init?: MouseEventInit) => Promise<void>
+  unhover: (element: TargetElement, init?: MouseEventInit) => Promise<void>
 }
 
 export default userEvent