|
| 1 | +# Use [userEvent](https://github.com/testing-library/user-event) over using `fireEvent` for user interactions (prefer-user-event) |
| 2 | + |
| 3 | +From |
| 4 | +[testing-library/dom-testing-library#107](https://github.com/testing-library/dom-testing-library/issues/107): |
| 5 | + |
| 6 | +> [...] it is becoming apparent the need to express user actions on a web page |
| 7 | +> using a higher-level abstraction than `fireEvent` |
| 8 | +
|
| 9 | +`userEvent` adds related event calls from browsers to make tests more realistic than its counterpart `fireEvent`, which is a low-level api. |
| 10 | +See the appendix at the end to check how are the events from `fireEvent` mapped to `userEvent` |
| 11 | + |
| 12 | +## Rule Details |
| 13 | + |
| 14 | +This rules enforces the usage of [userEvent](https://github.com/testing-library/user-event) methods over `fireEvent`. By default, the methods from `userEvent` takes precedence, but you add exceptions by configuring the rule in `.eslintrc` |
| 15 | + |
| 16 | +See below for examples of valid usages of `fireEvent` methods with the configuration. |
| 17 | + |
| 18 | +Examples of **incorrect** code for this rule: |
| 19 | + |
| 20 | +```ts |
| 21 | +// a method in fireEvent that has a userEvent equivalent |
| 22 | +import { fireEvent } from '@testing-library/dom'; |
| 23 | +fireEvent.click(node); |
| 24 | + |
| 25 | +// using fireEvent with an alias |
| 26 | +import { fireEvent as fireEventAliased } from '@testing-library/dom'; |
| 27 | +fireEventAliased.click(node); |
| 28 | + |
| 29 | +// using fireEvent after importing the entire library |
| 30 | +import * as dom from '@testing-library/dom'; |
| 31 | +dom.fireEvent.click(node); |
| 32 | +``` |
| 33 | + |
| 34 | +Examples of **correct** code for this rule: |
| 35 | + |
| 36 | +```ts |
| 37 | +// any userEvent method |
| 38 | +userEvent.click(); |
| 39 | +// fireEvent method that does not have an alternative in userEvent |
| 40 | +fireEvent.cut(node); |
| 41 | +import * as dom from '@testing-library/dom'; |
| 42 | +dom.fireEvent.cut(node); |
| 43 | + |
| 44 | +// a function called fireEvent that's not imported from testing-library |
| 45 | +function fireEvent() { |
| 46 | + // do stuff |
| 47 | +} |
| 48 | +fireEvent(); |
| 49 | +``` |
| 50 | + |
| 51 | +#### Options |
| 52 | + |
| 53 | +This rule allows to exclude specific functions with an equivalent in `userEvent` through configuration. This is useful if you need to allow an event from `fireEvent` to be used in the solution. For specific scenarios, you might want to consider disabling the rule inline. |
| 54 | + |
| 55 | +The configuration consists of an array of strings with the names of fireEvents methods to be excluded. |
| 56 | +An example looks like this |
| 57 | + |
| 58 | +```json |
| 59 | +{ |
| 60 | + "rules": { |
| 61 | + "prefer-user-event": [ |
| 62 | + "error", |
| 63 | + { |
| 64 | + "allowedMethods": ["click", "change"] |
| 65 | + } |
| 66 | + ] |
| 67 | + } |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +With this configuration example, the following use cases are considered valid |
| 72 | + |
| 73 | +```ts |
| 74 | +// using a named import |
| 75 | +import { fireEvent } from '@testing-library/dom'; |
| 76 | +fireEvent.click(node); |
| 77 | +fireEvent.change(node, { target: { value: 'foo' } }); |
| 78 | + |
| 79 | +// using fireEvent with an alias |
| 80 | +import { fireEvent as fireEventAliased } from '@testing-library/dom'; |
| 81 | +fireEventAliased.click(node); |
| 82 | +fireEventAliased.change(node, { target: { value: 'foo' } }); |
| 83 | + |
| 84 | +// using fireEvent after importing the entire library |
| 85 | +import * as dom from '@testing-library/dom'; |
| 86 | +dom.fireEvent.click(node); |
| 87 | +dom.fireEvent.change(node, { target: { value: 'foo' } }); |
| 88 | +``` |
| 89 | + |
| 90 | +## When Not To Use It |
| 91 | + |
| 92 | +When you don't want to use `userEvent`, such as if a legacy codebase is still using `fireEvent` or you need to have more low-level control over firing events (rather than the recommended approach of testing from a user's perspective) |
| 93 | + |
| 94 | +## Further Reading |
| 95 | + |
| 96 | +- [userEvent repository](https://github.com/testing-library/user-event) |
| 97 | +- [userEvent in the react-testing-library docs](https://testing-library.com/docs/ecosystem-user-event) |
| 98 | + |
| 99 | +## Appendix |
| 100 | + |
| 101 | +The following table lists all the possible equivalents from the low-level API `fireEvent` to the higher abstraction API `userEvent`. All the events not listed here do not have an equivalent (yet) |
| 102 | + |
| 103 | +| fireEvent method | Possible options in userEvent | |
| 104 | +| ---------------- | ----------------------------------------------------------------------------------------------------------- | |
| 105 | +| `click` | <ul><li>`click`</li><li>`type`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 106 | +| `change` | <ul><li>`upload`</li><li>`type`</li><li>`clear`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 107 | +| `dblClick` | <ul><li>`dblClick`</li></ul> | |
| 108 | +| `input` | <ul><li>`type`</li><li>`upload`</li><li>`selectOptions`</li><li>`deselectOptions`</li><li>`paste`</li></ul> | |
| 109 | +| `keyDown` | <ul><li>`type`</li><li>`tab`</li></ul> | |
| 110 | +| `keyPress` | <ul><li>`type`</li></ul> | |
| 111 | +| `keyUp` | <ul><li>`type`</li><li>`tab`</li></ul> | |
| 112 | +| `mouseDown` | <ul><li>`click`</li><li>`dblClick`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 113 | +| `mouseEnter` | <ul><li>`hover`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 114 | +| `mouseLeave` | <ul><li>`unhover`</li></ul> | |
| 115 | +| `mouseMove` | <ul><li>`hover`</li><li>`unhover`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 116 | +| `mouseOut` | <ul><li>`unhover`</li></ul> | |
| 117 | +| `mouseOver` | <ul><li>`hover`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 118 | +| `mouseUp` | <ul><li>`click`</li><li>`dblClick`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 119 | +| `paste` | <ul><li>`paste`</li></ul> | |
| 120 | +| `pointerDown` | <ul><li>`click`</li><li>`dblClick`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 121 | +| `pointerEnter` | <ul><li>`hover`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 122 | +| `pointerLeave` | <ul><li>`unhover`</li></ul> | |
| 123 | +| `pointerMove` | <ul><li>`hover`</li><li>`unhover`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 124 | +| `pointerOut` | <ul><li>`unhover`</li></ul> | |
| 125 | +| `pointerOver` | <ul><li>`hover`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
| 126 | +| `pointerUp` | <ul><li>`click`</li><li>`dblClick`</li><li>`selectOptions`</li><li>`deselectOptions`</li></ul> | |
0 commit comments