Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit c3a01d8

Browse files
committedMar 25, 2022
docs: update user-event references
1 parent 3db2384 commit c3a01d8

File tree

14 files changed

+92
-90
lines changed

14 files changed

+92
-90
lines changed
 

‎docs/dom-testing-library/api-events.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem'
1010
>
1111
> Most projects have a few use cases for `fireEvent`, but the majority of the
1212
> time you should probably use
13-
> [`@testing-library/user-event`](ecosystem-user-event.mdx).
13+
> [`@testing-library/user-event`](user-event/intro.mdx).
1414
1515
## `fireEvent`
1616

‎docs/dom-testing-library/install.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ install the wrapper:
3333

3434
`DOM Testing Library` works well with these companion libraries:
3535

36-
- [user-event](ecosystem-user-event.mdx) browser event simulation
36+
- [user-event](user-event/intro.mdx) browser event simulation
3737
- [jest-dom](ecosystem-jest-dom.mdx) custom Jest matchers
3838
- [bs-jest-dom](ecosystem-bs-jest-dom.mdx) companion library for
3939
`bs-react-testing-library`

‎docs/ecosystem-user-event.mdx

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,10 @@ import TabItem from '@theme/TabItem'
1010
advanced simulation of browser interactions than the built-in
1111
[`fireEvent`](dom-testing-library/api-events.mdx#fireevent) method.
1212

13-
> This page describes `user-event@13.5.0`.
14-
If you are starting or actively working on a project,
15-
we recommend to use [`user-event@14.0.0-beta`](user-event/intro.mdx) instead, as it includes important bug fixes and new features.
13+
> This page describes `user-event@13.5.0`.
14+
> This version is no longer maintained. Please use
15+
> [`user-event@14`](user-event/intro.mdx) instead, as it includes important bug
16+
> fixes and new features.
1617
1718
## Installation
1819

@@ -222,7 +223,7 @@ import {render, screen} from '@testing-library/react'
222223
import userEvent from '@testing-library/user-event'
223224

224225
test('prepend text', () => {
225-
render(<input defaultValue="World!"/>)
226+
render(<input defaultValue="World!" />)
226227
const element = screen.getByRole('textbox')
227228

228229
// Prepend text

‎docs/example-findByText.md

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ import userEvent from '@testing-library/user-event'
1414
// i.e. `.toBeVisible`
1515
import '@testing-library/jest-dom'
1616

17-
const renderContent = el => {
17+
function renderApp() {
18+
const el = document.body.appendChild(document.createElement('div'))
1819
el.innerHTML = `
1920
<form id='login_form' method='post' name='login'>
2021
<label for='username'>User Name:</label>
@@ -88,20 +89,15 @@ const renderContent = el => {
8889
window.history.back()
8990
})
9091

91-
return el
92+
return { user: userEvent.setup() }
9293
}
9394

94-
describe('findByText Examples', () => {
95-
let div
96-
let container
97-
98-
beforeEach(() => {
99-
div = document.createElement('div')
100-
container = renderContent(div)
101-
})
95+
afterEach(() => document.body.innerHTML = ``)
10296

97+
describe('findByText Examples', () => {
10398
it('should show a required field warning for each empty input field', async () => {
104-
userEvent.click(
99+
const {user} = renderApp()
100+
await user.click(
105101
getByRole(container, 'button', {
106102
name: 'Login',
107103
}),
@@ -113,19 +109,20 @@ describe('findByText Examples', () => {
113109
})
114110

115111
it('should show invalid field errors for each invalid input field', async () => {
112+
const {user} = renderApp()
116113
const userNameField = getByPlaceholderText(container, 'Enter user name')
117114
const passwordField = getByPlaceholderText(container, 'Enter password')
118115

119116
expect(await findByText(container, 'Invalid Password')).not.toBeVisible()
120117
expect(await findByText(container, 'Invalid User Name')).not.toBeVisible()
121118

122-
userEvent.type(userNameField, 'Philchard')
123-
userEvent.type(passwordField, 'theCat')
119+
await user.type(userNameField, 'Philchard')
120+
await user.type(passwordField, 'theCat')
124121

125122
expect(userNameField).toHaveValue('Philchard')
126123
expect(passwordField).toHaveValue('theCat')
127124

128-
userEvent.click(
125+
await user.click(
129126
getByRole(container, 'button', {
130127
name: 'Login',
131128
}),

‎docs/example-formik.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -63,12 +63,13 @@ import {MyForm} from './myForm.js'
6363
test('rendering and submitting a basic Formik form', async () => {
6464
const handleSubmit = jest.fn()
6565
render(<MyForm onSubmit={handleSubmit} />)
66+
const user = userEvent.setup()
6667

67-
userEvent.type(screen.getByLabelText(/first name/i), 'John')
68-
userEvent.type(screen.getByLabelText(/last name/i), 'Dee')
69-
userEvent.type(screen.getByLabelText(/email/i), 'john.dee@someemail.com')
68+
await user.type(screen.getByLabelText(/first name/i), 'John')
69+
await user.type(screen.getByLabelText(/last name/i), 'Dee')
70+
await user.type(screen.getByLabelText(/email/i), 'john.dee@someemail.com')
7071

71-
userEvent.click(screen.getByRole('button', {name: /submit/i}))
72+
await user.click(screen.getByRole('button', {name: /submit/i}))
7273

7374
await waitFor(() =>
7475
expect(handleSubmit).toHaveBeenCalledWith({

‎docs/example-input-event.mdx

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@ sidebar_label: Input Event
77
> **Note**
88
>
99
> If you want to simulate a more natural typing behaviour while testing your
10-
> component, consider the companion library
11-
> [`user-event`](ecosystem-user-event.mdx)
10+
> component, consider the companion library [`user-event`](user-event/intro.mdx)
1211
1312
```jsx
1413
import React, {useState} from 'react'

‎docs/example-react-router.mdx

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -55,19 +55,19 @@ import '@testing-library/jest-dom'
5555

5656
import {App, LocationDisplay} from './app'
5757

58-
test('full app rendering/navigating', () => {
58+
test('full app rendering/navigating', async () => {
5959
const history = createMemoryHistory()
6060
render(
6161
<Router history={history}>
6262
<App />
6363
</Router>,
6464
)
65+
const user = userEvent.setup()
6566
// verify page content for expected route
6667
// often you'd use a data-testid or role query, but this is also possible
6768
expect(screen.getByText(/you are home/i)).toBeInTheDocument()
6869

69-
const leftClick = {button: 0}
70-
userEvent.click(screen.getByText(/about/i), leftClick)
70+
await user.click(screen.getByText(/about/i))
7171

7272
// check that the content changed to the new page
7373
expect(screen.getByText(/you are on the about page/i)).toBeInTheDocument()
@@ -127,18 +127,20 @@ test('full app rendering/navigating', () => {
127127
const renderWithRouter = (ui, {route = '/'} = {}) => {
128128
window.history.pushState({}, 'Test page', route)
129129

130-
return render(ui, {wrapper: BrowserRouter})
130+
return {
131+
user: userEvent.setup(),
132+
...render(ui, {wrapper: BrowserRouter}),
133+
}
131134
}
132135
```
133136

134137
```jsx
135138
// app.test.js
136-
test('full app rendering/navigating', () => {
137-
renderWithRouter(<App />)
139+
test('full app rendering/navigating', async () => {
140+
const {user} = renderWithRouter(<App />)
138141
expect(screen.getByText(/you are home/i)).toBeInTheDocument()
139142

140-
const leftClick = {button: 0}
141-
userEvent.click(screen.getByText(/about/i), leftClick)
143+
await user.click(screen.getByText(/about/i))
142144

143145
expect(screen.getByText(/you are on the about page/i)).toBeInTheDocument()
144146
})

‎docs/guide-events.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ simply using `fireEvent.click` is worth it.
3838
We will describe a couple of simple adjustments to your tests that will increase
3939
your confidence in the interactive behavior of your components. For other
4040
interactions you may want to either consider using
41-
[`user-event`](ecosystem-user-event.mdx) or testing your components in a real
41+
[`user-event`](user-event/intro.mdx) or testing your components in a real
4242
environment (e.g. manually, automatic with cypress, etc.).
4343

4444
### Keydown

‎docs/queries/about.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ make use of semantic queries to test your page in the most accessible way.
1818

1919
After selecting an element, you can use the
2020
[Events API](dom-testing-library/api-events.mdx) or
21-
[user-event](ecosystem-user-event.mdx) to fire events and simulate user
22-
interactions with the page, or use Jest and [jest-dom](ecosystem-jest-dom.mdx)
23-
to make assertions about the element.
21+
[user-event](user-event/intro.mdx) to fire events and simulate user interactions
22+
with the page, or use Jest and [jest-dom](ecosystem-jest-dom.mdx) to make
23+
assertions about the element.
2424

2525
There are Testing Library helper methods that work with queries. As elements
2626
appear and disappear in response to actions,

‎docs/react-testing-library/migrate-from-enzyme.mdx

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@ some of the project's other libraries that can help you along the way:
2020

2121
- **[@testing-library/jest-dom](https://github.com/testing-library/jest-dom)**:
2222
`jest-dom` provides a set of custom Jest matchers that you can use to extend
23-
Jest. These make your tests more declarative, clearer to read, and easier
24-
to maintain.
23+
Jest. These make your tests more declarative, clearer to read, and easier to
24+
maintain.
2525

2626
- **[@testing-library/user-event](https://github.com/testing-library/user-event):**
2727
`user-event` tries to simulate the real events that happen in the browser as
@@ -120,8 +120,8 @@ test this component:
120120

121121
The following component gets a `name` from `props` and shows a welcome message
122122
in an `h1` element. It also has a text input which users can change to a
123-
different name, and the template updates accordingly. Check the live version
124-
on [CodeSandbox](https://codesandbox.io/s/ecstatic-hellman-fh7in).
123+
different name, and the template updates accordingly. Check the live version on
124+
[CodeSandbox](https://codesandbox.io/s/ecstatic-hellman-fh7in).
125125

126126
```jsx
127127
const Welcome = props => {
@@ -247,15 +247,15 @@ of the query documentation might help you understand the concepts better.
247247
> A `<form>` element must have a `name` attribute in order to have an implicit
248248
> `role` of `'form'` (as required by the specification).
249249
250-
React Testing Library aims to test the components how users use them. Users
251-
see buttons, headings, forms and other elements by their role, not by their
252-
`id`, `class`, or element tag name. Therefore, when you use React Testing
253-
Library you should avoid accessing the DOM with the `document.querySelector`
254-
API. (You _can_ use it in your tests, but it's not recommended for the reasons
255-
stated in this paragraph.)
250+
React Testing Library aims to test the components how users use them. Users see
251+
buttons, headings, forms and other elements by their role, not by their `id`,
252+
`class`, or element tag name. Therefore, when you use React Testing Library you
253+
should avoid accessing the DOM with the `document.querySelector` API. (You _can_
254+
use it in your tests, but it's not recommended for the reasons stated in this
255+
paragraph.)
256256

257-
React Testing Library exposes some handy query APIs which help you access
258-
the component elements efficiently. You can see the
257+
React Testing Library exposes some handy query APIs which help you access the
258+
component elements efficiently. You can see the
259259
[list of available queries here](queries/about.mdx#types-of-queries). If you're
260260
not sure which query you should use in a given situation, we have a great page
261261
which explains [which query to use](queries/about.mdx#priority), so check it
@@ -330,10 +330,14 @@ input's "checked" property is properly set. Let's see how we might write a test
330330
for that case:
331331

332332
```jsx
333-
test('handles click correctly', () => {
333+
test('handles click correctly', async () => {
334334
render(<Checkbox />)
335+
const user = userEvent.setup()
336+
337+
// You can also call this method directly on userEvent,
338+
// but using the methods from `.setup()` is recommended.
339+
await user.click(screen.getByText('Check'))
335340

336-
userEvent.click(screen.getByText('Check'))
337341
expect(screen.getByLabelText('Check')).toBeChecked()
338342
})
339343
```

‎docs/user-event/api-keyboard.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ keyboard('{Shift>}A{/Shift}') // translates to: Shift(down), A, Shift(up)
6969
```
7070

7171
The mapping of `key` to `code` is performed by a
72-
[default key map](https://github.com/testing-library/user-event/blob/beta/src/keyboard/keyMap.ts)
72+
[default key map](https://github.com/testing-library/user-event/blob/main/src/keyboard/keyMap.ts)
7373
portraying a "default" US-keyboard. You can provide your own local keyboard
7474
mapping per [`keyboardMap`](options.mdx#keyboardmap) option.
7575

@@ -79,5 +79,5 @@ keys.
7979
> Future versions might try to interpolate the modifiers needed to reach a
8080
> printable key on the keyboard. E.g. Automatically pressing `{Shift}` when
8181
> CapsLock is not active and `A` is referenced. If you don't wish this behavior,
82-
> you can deactivate the [`autoModify`](options.mdx#automodify) option to opt out
83-
> of this non-breaking change.
82+
> you can deactivate the [`autoModify`](options.mdx#automodify) option to opt
83+
> out of this non-breaking change.

‎docs/user-event/install.mdx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,14 @@ import TabItem from '@theme/TabItem'
1313
<TabItem value="npm">
1414

1515
```sh
16-
npm install --save-dev @testing-library/user-event@^14.0.0-beta
16+
npm install --save-dev @testing-library/user-event
1717
```
1818

1919
</TabItem>
2020
<TabItem value="yarn">
2121

2222
```sh
23-
yarn add --dev @testing-library/user-event@^14.0.0-beta
23+
yarn add --dev @testing-library/user-event
2424
```
2525

2626
</TabItem>
@@ -29,8 +29,8 @@ yarn add --dev @testing-library/user-event@^14.0.0-beta
2929
Note that `@testing-library/user-event` requires `@testing-library/dom`.
3030

3131
If you use one of the
32-
[framework wrappers](../dom-testing-library/install.mdx#wrappers), it is important
33-
that `@testing-library/dom` is resolved to the same installation required by the
34-
framework wrapper of your choice.
32+
[framework wrappers](../dom-testing-library/install.mdx#wrappers), it is
33+
important that `@testing-library/dom` is resolved to the same installation
34+
required by the framework wrapper of your choice.
3535
Usually this means that if you use one of the framework wrappers, you should not
3636
add `@testing-library/dom` to your project dependencies.

‎docs/user-event/intro.mdx

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,14 @@ id: intro
33
title: Introduction
44
---
55

6-
[`user-event`](https://github.com/testing-library/user-event)
7-
is a companion library for Testing Library that simulates user interactions by
8-
dispatching the events that would happen if the interaction took place in a browser.
6+
[`user-event`](https://github.com/testing-library/user-event) is a companion
7+
library for Testing Library that simulates user interactions by dispatching the
8+
events that would happen if the interaction took place in a browser.
99

10-
> These docs describe `user-event@14.0.0-beta`.
11-
This is still a pre-release and might be subject to breaking changes
12-
if they should be deemed necessary in the light of feedback we receive for this version.
13-
All planned breaking changes are already implemented though.
14-
If you are starting or actively working on a project,
15-
we recommend to use this pre-release, as it includes important bug fixes and new features.
16-
You can find the docs for `user-event@13.5.0` [here](../ecosystem-user-event.mdx).
10+
> These docs describe `user-event@14`.
11+
> We recommend updating your projects to this version, as it includes important
12+
> bug fixes and new features. You can find the docs for `user-event@13.5.0`
13+
> [here](../user-event/intro.mdx).
1714
1815
While most examples with `user-event` are for `React`, the library can be used
1916
with any framework as long as there is a DOM.
@@ -36,8 +33,9 @@ to test interaction with your components.
3633

3734
## Writing tests with `userEvent`
3835

39-
We recommend to use [`userEvent.setup()`](setup.mdx) when rendering your component
40-
and inline that rendering and setup in your test or use a setup function.
36+
We recommend to use [`userEvent.setup()`](setup.mdx) when rendering your
37+
component and inline that rendering and setup in your test or use a setup
38+
function.
4139
We discourage rendering or using any `userEvent` functions outside of the test
4240
itself - e.g. in a `before`/`after` hook - for reasons described in
4341
["Avoid Nesting When You're Testing"](https://kentcdodds.com/blog/avoid-nesting-when-youre-testing).
@@ -55,14 +53,14 @@ test('trigger some awesome feature when clicking the button', async () => {
5553

5654
```js
5755
function setup(jsx) {
58-
return {
59-
user: userEvent.setup(),
60-
...render(jsx),
61-
}
56+
return {
57+
user: userEvent.setup(),
58+
...render(jsx),
59+
}
6260
}
6361

6462
test('render with a setup function', async () => {
65-
const { user } = setup(<MyComponent/>)
66-
// ...
63+
const {user} = setup(<MyComponent />)
64+
// ...
6765
})
6866
```

0 commit comments

Comments
 (0)