userEvent.setup() exists but I'm unable to call it

[nene]

Reproduction example

import { describe, expect, it } from "vitest";
import userEvent from "@testing-library/user-event";

describe("my test", () => {
  it("should pass", () => {
    console.log(userEvent.setup);
    userEvent.setup();     // <-- fails here
    expect(true).toBe(true);
  });
});

https://github.com/nene/test-userevent

Prerequisites

Sorry, I don't know how to work with tests in codesandbox. Instead I provide a repository:

1. Check out the repo git clone git@github.com:nene/test-userevent.git
2. Install dependencies with npm install
3. Run tests npm test

Expected behavior

Tests execute successfully.

Actual behavior

An error occurs:

 FAIL  src/my.test.ts > my test > should pass
TypeError: Cannot read properties of undefined (reading 'Symbol(Node prepared with document state workarounds)')
 ❯ prepareDocument node_modules/@testing-library/user-event/dist/esm/document/prepareDocument.js:10:17
 ❯ Object.setupMain [as setup] node_modules/@testing-library/user-event/dist/esm/setup/setup.js:52:5
 ❯ src/my.test.ts:7:15
      5|   it("should pass", () => {
      6|     console.log(userEvent.setup);
      7|     userEvent.setup();
       |               ^
      8|     expect(true).toBe(true);
      9|   });

User-event version

14.6.1

Environment

Testing Library framework: @testing-library/dom 10.4.0

JS framework: react 18.3.1 (though not used in test)

Test environment: vitest 3.0.8

DOM implementation: Not sure, Vitest docs say that the default environment is node. I haven't installed any of the optional environments like js-dom or happy-dom.

Additional context

This problem looks similar to #839, but that issue has been fixed, and the workarounds suggested there didn't seem to do anything.

Most strangely, when I console.log(userEvent.setup) it prints:

[Function: setupMain]

Similarly typeof userEvent.setup also tells me that it's a function.

But when I call the function userEvent.setup() I get the error.

I managed to locate this strange Symbol(Node prepared with document state workarounds) inside user-event library. But I have no clue what's going on with that.

[nene]

I figured out the cause. I had not installed any of the vitest dom environments. After installing happy-dom the test started to work.

So feel free to close this issue. Though it would be nicer if the error message one gets when no DOM environment is present would not be quite as mysterious as this.

[beanscg]

Bean Labs took a source/docs pass. The useful public surfaces for this look like src/setup, README/docs, package exports.

The highest-signal next step would be to show the supported import shape for userEvent.setup and add a short note for default import versus named API confusion. That keeps the issue scoped to observable source/docs behavior before opening a PR.

No PR opened from this pass.