diff --git a/docs/user-event/api-convenience.mdx b/docs/user-event/api-convenience.mdx index deeea5fc2..aa2876ce1 100644 --- a/docs/user-event/api-convenience.mdx +++ b/docs/user-event/api-convenience.mdx @@ -18,6 +18,22 @@ click(element: Element): Promise pointer([{target: element}, {keys: '[MouseLeft]', target: element}]) ``` +```js +test('click', async () => { + const onChange = jest.fn() + const user = userEvent.setup() + + render() + + const checkbox = screen.getByRole('checkbox') + + await user.click(checkbox) + + expect(onChange).toHaveBeenCalledTimes(1) + expect(checkbox).toBeChecked() +}) +``` + The first action might be skipped per [`skipHover`](options.mdx#skiphover). ### dblClick() @@ -30,6 +46,22 @@ dblClick(element: Element): Promise pointer([{target: element}, {keys: '[MouseLeft][MouseLeft]', target: element}]) ``` +```js +test('double click', async () => { + const onChange = jest.fn() + const user = userEvent.setup() + + render() + + const checkbox = screen.getByRole('checkbox') + + await user.dblClick(checkbox) + + expect(onChange).toHaveBeenCalledTimes(2) + expect(checkbox).not.toBeChecked() +}) +``` + ### tripleClick() ```ts @@ -43,6 +75,22 @@ pointer([ ]) ``` +```js +test('triple click', async () => { + const onChange = jest.fn() + const user = userEvent.setup() + + render() + + const checkbox = screen.getByRole('checkbox') + + await user.tripleClick(checkbox) + + expect(onChange).toHaveBeenCalledTimes(3) + expect(checkbox).toBeChecked() +}) +``` + ## Mouse movement ### hover() @@ -55,6 +103,33 @@ hover(element: Element): Promise pointer({target: element}) ``` +```js +test('hover/unhover', async () => { + const user = userEvent.setup() + render(
Hover
) + + const hoverBox = screen.getByText('Hover') + let isHover = false + + hoverBox.addEventListener('mouseover', () => { + isHover = true + }) + hoverBox.addEventListener('mouseout', () => { + isHover = false + }) + + expect(isHover).toBeFalsy() + + await user.hover(hoverBox) + + expect(isHover).toBeTruthy() + + await user.unhover(hoverBox) + + expect(isHover).toBeFalsy() +}) +``` + ### unhover() ```ts @@ -81,3 +156,43 @@ keyboard('{Shift>}{Tab}{/Shift}') // with shift=false keyboard('[/ShiftLeft][/ShiftRight]{Tab}') ``` + +```js +test('tab', async () => { + const user = userEvent.setup() + render( +
+ + + +
, + ) + + const checkbox = screen.getByRole('checkbox') + const radio = screen.getByRole('radio') + const number = screen.getByRole('spinbutton') + + expect(document.body).toHaveFocus() + + await user.tab() + + expect(checkbox).toHaveFocus() + + await user.tab() + + expect(radio).toHaveFocus() + + await user.tab() + + expect(number).toHaveFocus() + + await user.tab() + + // cycle goes back to the body element + expect(document.body).toHaveFocus() + + await user.tab() + + expect(checkbox).toHaveFocus() +}) +```