feat: document user-event v14 #980
Conversation
|
Hi @ph-fritsche! Thanks for tagging me to review this one :) |
|
You won't see me arguing against a more prominent advertisement for I think the change between |
| > Our primary target audience tests per `jest` in a `jsdom` environment and there | ||
| is no layout in `jsdom`. This means that different from your browser the | ||
| elements don't exist in a specific position, layer and size. | ||
| We don't try to determine if the pointer action you describe is possible at that | ||
| position in your layout. |
There was a problem hiding this comment.
Do you mean this?
| > Our primary target audience tests per `jest` in a `jsdom` environment and there | |
| is no layout in `jsdom`. This means that different from your browser the | |
| elements don't exist in a specific position, layer and size. | |
| We don't try to determine if the pointer action you describe is possible at that | |
| position in your layout. | |
| > Our primary target audience tests per `jest` in a `jsdom` environment and there | |
| is no layout in `jsdom`. This means that the elements specific position, layer, and size could be different from your browser. | |
| We don't try to determine if the pointer action you describe is possible at that | |
| position in your layout. |
There was a problem hiding this comment.
No this literally means that there is no specific position, layer, or size. Elements can have IDL properties and/or CSS styles that usually correspond to elements being at a specific position, having specific dimensions, or being above/under each other. But jsdom has no layout. The properties and styles exist, but they have no effect.
document.body.innerHTML=`<img style="position: relative; left: 50px;"/>`
$("img").style.left // '50px'
$("img").offsetLeft // 0There was a problem hiding this comment.
👍 Got it, the comment made it click to me - would it be worth it to also mention it in the docs?
every character has effective width zero and is at effective offset 0,0. (While there might be properties applied that suggest otherwise but have no effect.)
There was a problem hiding this comment.
I don't know. I feel like it might be better to write a blog post about this topic explaining the concept and then adding a link. Really explaining this, and what difference it makes to testing might be worth it, but is out of scope for these docs.
| title: Convenience APIs | ||
| --- | ||
|
|
||
| The following APIs are shortcuts for equivalent calls to the underlying |
There was a problem hiding this comment.
I'm not sure these API's should be "hidden" in the convenience section because most of the users will probably be using them.
Either we should think of a way to rename them, change the order of the docs so they'll be first or mention them in the pointer and keyboard pages.
There was a problem hiding this comment.
Yeah, I don't know. On one hand they exist because they are easy to use and so - yes - they are probably used often, but on the other hand they are self-explanatory and merely documented for sake of completeness. The auto-completion in IDE would probably be enough.
Maybe this could be solved by another blog post walking through some examples with heavy use of these convenience methods and mentioning the post with a short excerpt in the introduction.
A mention in pointer and keyboard might also be fine.
There was a problem hiding this comment.
Not sure we should rely on the IDE auto-completion for this one and IMO the package's functionality should be easily found in the docs and not in a personal blog post (but we should also think of writing a blog post about user-event 14 in the testing-library blog).
I strongly prefer a mention in pointer and keyboard pages :)
|
|
||
| ```js | ||
| test('trigger some awesome feature when clicking the button', async () => { | ||
| const user = userEvent.setup() |
There was a problem hiding this comment.
This is only my opinion, but is there a way to setup userEvent in the setupFilesAfterEnv in jest for example?
I think causing our users to write this line in every test might cause some pain.
There was a problem hiding this comment.
Yes, this could be done in a beforeEach. But we especially mention Avoid nesting when you're testing in the docs...
The solution for now would be:
function setup(jsx) {
render(jsx)
const user = userEvent.setup()
return { user }
}
test('something', () => {
const { user } = setup(<MyComponent/>)
// ...
})This pattern might even become that common that we should consider returning the user-event instance from render in the framework packages.
There was a problem hiding this comment.
Added an example for a test setup function below.
There was a problem hiding this comment.
I'm in favor of returning the user-event instance from render.
But this means people will need to install user-event too and the frameworks will instantiate that for them?
That sounds too "voodoo" to me.
There was a problem hiding this comment.
Yes, something like that.
The framework wrapper could try..require user-event. So that if user-event is installed the wrapper will automatically return an instance from render.
Or we could take a similar approach like how @testing-library/react configures /dom when it's imported.
user-event could register itself on the framework wrapper when being imported.
It might be a bit "voodoo", but it might also result in a good developer experience.
Co-authored-by: Matan Borenkraout <Matanbobi@gmail.com>
Add documentation for
user-event@14alongsidev13for rest ofbeta.New projects / projects that someone is actively working on should probably already switch to
v14-0.0-beta, but I want to wait for more feedback before declaring thisstable.I hope the new documentation helps with this.