docs: document userEvent.setup

docs/guide/browser/interactivity-api.md

@@ -29,6 +29,29 @@ Almost every `userEvent` method inherits its provider options. To see all availa
 ```
 :::
 
+## userEvent.setup
+
+- **Type:** `() => UserEvent`
+
+Creates a new user event instance. This is useful if you need to keep the state of keyboard to press and release buttons correctly.
+
+::: warning
+Unlike `@testing-library/user-event`, the default `userEvent` instance from `@vitest/browser/context` is created once, not every time its methods are called! You can see the difference in how it works in this snippet:
+
+```ts
+import { userEvent as vitestUserEvent } from '@vitest/browser/context'
+import { userEvent as originalUserEvent } from '@testing-library/user-event'
+
+await vitestUserEvent.keyboard('{Shift}') // press shift without releasing
+await vitestUserEvent.keyboard('{/Shift}') // releases shift
+
+await originalUserEvent.keyboard('{Shift}') // press shift without releasing
+await originalUserEvent.keyboard('{/Shift}') // DID NOT release shift because the state is different
+```
+
+This behaviour is more useful because we do not emulate the keyboard, we actually press the Shift, so keeping the original behaviour would cause unexpected issues when typing in the field.
+:::
+
 ## userEvent.click
 
 - **Type:** `(element: Element, options?: UserEventClickOptions) => Promise<void>`

packages/browser/context.d.ts

@@ -49,6 +49,14 @@ export interface BrowserCommands {
 }
 
 export interface UserEvent {
+  /**
+   * Creates a new user event instance. This is useful if you need to keep the
+   * state of keyboard to press and release buttons correctly.
+   *
+   * **Note:** Unlike `@testing-library/user-event`, the default `userEvent` instance
+   * from `@vitest/browser/context` is created once, not every time its methods are called!
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api.html#userevent-setup}
+   */
   setup: () => UserEvent
   /**
    * Click on an element. Uses provider's API under the hood and supports all its options.