diff --git a/docs/ecosystem-user-event.mdx b/docs/ecosystem-user-event.mdx
index 724dc97ad..9972c7f55 100644
--- a/docs/ecosystem-user-event.mdx
+++ b/docs/ecosystem-user-event.mdx
@@ -3,28 +3,40 @@ id: ecosystem-user-event
title: user-event
---
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
[`user-event`][gh] is a companion library for Testing Library that provides more
advanced simulation of browser interactions than the built-in
[`fireEvent`](dom-testing-library/api-events.mdx#fireevent) method.
-[`user-event` on GitHub][gh]
+## Installation
-## Install
+
+
-```
+```sh
npm install --save-dev @testing-library/user-event @testing-library/dom
```
-```jsx
-import { screen } from '@testing-library/dom'
+
+
+
+```sh
+yarn add --dev @testing-library/user-event @testing-library/dom
+```
+
+
+
+
+Now simply import it in your tests:
+
+```js
import userEvent from '@testing-library/user-event'
-test('types inside textarea', () => {
- document.body.innerHTML = ``
+// or
- userEvent.type(screen.getByRole('textbox'), 'Hello, World!')
- expect(screen.getByRole('textbox')).toHaveValue('Hello, World!')
-})
+const { default: userEvent } = require('@testing-library/user-event')
```
## API
@@ -69,7 +81,9 @@ See the
constructor documentation for more options.
Note that `click` will trigger hover events before clicking. To disable this,
-set the `skipHover` option to `true`.
+set the `skipHover` option to `true`. Also note that trying to click an element
+with `pointer-events` being set to `"none"` (i.e. unclickable) will throw an
+error.
### `dblClick(element, eventInit, options)`
@@ -113,10 +127,6 @@ are typed. By default it's 0. You can use this option if your component has a
different behavior for fast or slow users. If you do this, you need to make sure
to `await`!
-> To be clear, `userEvent.type` _always_ returns a promise, but you _only_ need
-> to `await` the promise it returns if you're using the `delay` option.
-> Otherwise everything runs synchronously and you can ignore the promise.
-
`type` will click the element before typing. To disable this, set the
`skipClick` option to `true`.
@@ -136,6 +146,8 @@ The following special character strings are supported:
| `{arrowright}` | ArrowRight | N/A | |
| `{arrowup}` | ArrowUp | N/A | |
| `{arrowdown}` | ArrowDown | N/A | |
+| `{home}` | Home | N/A | |
+| `{end}` | End | N/A | |
| `{shift}` | Shift | `shiftKey` | Does **not** capitalize following characters. |
| `{ctrl}` | Control | `ctrlKey` | |
| `{alt}` | Alt | `altKey` | |
@@ -184,18 +196,15 @@ The following is an example of usage of this library with
``
```jsx
-import React from 'react
-import {render, screen} from '@testing-library/react'
+import React from 'react'
+import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
test('types into the input', () => {
render(
<>
-
+
>
)
const input = screen.getByLabelText(/enter a time/i)
@@ -261,7 +270,7 @@ userEvent.keyboard('a', { keyboardState }) // press [KeyA] with active ctrlKey m
```
The mapping of `key` to `code` is performed by a
-[default key map](https://github.com/testing-library/user-event/blob/master/src/keyboard/keyMap.ts)
+[default key map](https://github.com/testing-library/user-event/blob/main/src/keyboard/keyMap.ts)
portraying a "default" US-keyboard. You can provide your own local keyboard
mapping per option.
@@ -274,12 +283,15 @@ userEvent.keyboard('?', { keyboardMap: myOwnLocaleKeyboardMap })
> CapsLock is not active and `A` is referenced. If you don't wish this behavior,
> you can pass `autoModify: false` when using `userEvent.keyboard` in your code.
-### `upload(element, file, [{ clickInit, changeInit }])`
+### `upload(element, file, [{ clickInit, changeInit }], [options])`
Uploads file to an ``. For uploading multiple files use `` with
the `multiple` attribute and the second `upload` argument as an array. It's also
possible to initialize a click or change event using a third argument.
+If `options.applyAccept` is set to `true` and there is an `accept` attribute on
+the element, files that don't match will be discarded.
+
```jsx
import React from 'react'
import { render, screen } from '@testing-library/react'
@@ -527,15 +539,17 @@ method.
| Key | Character |
| ---------- | -------------- |
-| arrowLeft | `{arrowLeft}` |
-| arrowRight | `{arrowRight}` |
-| arrowDown | `{arrowDown}` |
-| arrowUp | `{arrowUp}` |
+| arrowLeft | `{arrowleft}` |
+| arrowRight | `{arrowright}` |
+| arrowDown | `{arrowdown}` |
+| arrowUp | `{arrowup}` |
+| home | `{home}` |
+| end | `{end}` |
| enter | `{enter}` |
| escape | `{esc}` |
| delete | `{del}` |
| backspace | `{backspace}` |
-| selectAll | `{selectAll}` |
+| selectAll | `{selectall}` |
| space | `{space}` |
| whitespace | `' '` |
@@ -561,9 +575,4 @@ test('delete characters within the selectedRange', () => {
})
```
-## Known limitations
-
-- No `` support.
- [#423](https://github.com/testing-library/user-event/issues/423#issuecomment-669368863)
-
[gh]: https://github.com/testing-library/user-event