Is there some guidance on when to use setup() vs userEvent.whatever?

[camjackson]

I've been using testing-library and user-event for a few years. I've always done userEvent.click(), and never had any problems with it.

I recently started on a new team and have found that they do

const user = userEvent.setup();
user.click();

I had never seen this before, went and did a bunch of reading, including this page of the docs, and some of the issues + PRs discussing the implementation. It seems that setup() is important if you want proper simulation of multi-step inputs like shift+click, but that is surely a rare case? >99% of my tests never have to worry about that, and work just fine with userEvent.click(), as far as I can tell.

I find setup() to be a bit boilerplatey. I don't want to have to add const user = userEvent.setup() to the start of every single test (or worse, use let and beforeEach). It just feels messy. But I will do it if there is a good reason. The docs have this to say:

You can also call the APIs directly on the default export. This will call setup internally and then use the method on the instance.

This exists to ease the transition to version 14 and writing simple tests. Using the methods on the instances returned by userEvent.setup() is recommended.

What I really want to know is: if I'm not doing tricky multi-step interactions or trying to configure userEvent to do anything special, is there any reason to use setup()? Or can I continue on without the extra step as I always have? Will there be a performance penalty from setup being invoked on every interaction rather than once at the start of my test? Or is the difference negligible?

[ph-fritsche]

This exists to ease the transition to version 14 and writing simple tests. Using the methods on the instances returned by userEvent.setup() is recommended.

This pretty much sums it up.
You should use userEvent.setup() after creating the document and before you render() your component.
You can keep on using the direct APIs if rewriting tests is to much work on a project or if you only write a simple (throw-away) test.

In almost all cases it will not make a difference, but if you hit one of the rare edge cases, it might be hard to debug - especially since most environments don't create a new document for each test. So the first test will apply .setup() after rendering and every subsequent test will have our workarounds applied from the test before and only create a new input device state after rendering.

Yes, boilerplate in every test can be messy. A setup function that you can share across many tests is the way to go.
https://testing-library.com/docs/user-event/intro#writing-tests-with-userevent

You can write a test helper that allows you to create single-line arrange steps in your tests.
See for example the test helpers on this repo: https://github.com/testing-library/user-event/blob/main/tests/_helpers/setup.ts

[camjackson]

Thanks, that's helpful. I'm still a bit unconvinced on the value of setup if it will almost never make a difference. But knowing that I can avoid the boilerplate by wrapping setup and render into a single step makes me a lot happier. Cheers.