vitest-dev/vitest · error · Error

Failed to resolve user-event package from

Error message

Failed to resolve user-event package from ${previewDistRoot}

What it means

getUserEventImport runs only for the 'preview' provider and resolves @testing-library/user-event relative to the preview provider's distRoot. The preview provider integrates user-event for simulating interactions, so the package must be resolvable from that location. The error fires when Vite's resolver returns null, meaning the package is not installed or not reachable.

Solutions

1. Install the package: `pnpm add -D @testing-library/user-event` in the same package that runs the browser tests.
2. If in a monorepo, ensure hoisting makes the package visible from the preview provider's distRoot, or add it to every workspace package that uses provider: 'preview'.
3. Rebuild @vitest/browser (`pnpm build`) if you are in the Vitest monorepo itself, so distRoot is populated.
4. As a workaround, switch to provider: 'playwright' or 'webdriverio' which do not require user-event.

Example fix

// before - missing dependency
browser: { provider: 'preview' }
// after
pnpm add -D @testing-library/user-event
browser: { provider: 'preview' }

import { createRequire } from 'node:module'
const req = createRequire(import.meta.url)
function userEventResolvable(from: string): boolean {
  try { req.resolve('@testing-library/user-event', { paths: [from] }); return true } catch { return false }
}

When it happens

Trigger: Selecting provider: 'preview' in browser config without having @testing-library/user-event installed; installing it in a different workspace package than the one the preview provider resolves from; a pnpm hoisting setting that hides the package from the preview dist root.

Common situations: Following a tutorial that uses the preview provider without listing the optional peer dependency; monorepo where user-event is a devDependency of one package but the browser tests run from another; corrupted/incomplete node_modules.

Related errors

• The "preview" provider doesn't support…
• Browser is not initialized
• Browser provider is not defined for the project
• Browser provider is not defined for the project
• Cannot upload files outside of a test

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/6e8aa26c5092d991. Report an issue: GitHub.

Appendix: source

Thrown at packages/browser/src/node/plugins/pluginContext.ts:95

  commands: {
    ${commandsCode}
  },
  config: __vitest_browser_runner__.config,
}
export const commands = server.commands
export const userEvent = createUserEvent(_userEventSetup)
export { page, cdp, locators, utils }
`
}

async function getUserEventImport(provider: BrowserProvider | undefined, resolve: (id: string, importer: string) => Promise<null | { id: string }>) {
  if (!provider || provider.name !== 'preview') {
    return 'const _userEventSetup = undefined'
  }
  const previewDistRoot = (provider as any).distRoot
  const resolved = await resolve('@testing-library/user-event', previewDistRoot)
  if (!resolved) {
    throw new Error(`Failed to resolve user-event package from ${previewDistRoot}`)
  }
  return `\
import { userEvent as _userEventSetup } from '${slash(`/@fs/${resolved.id}`)}'
`
}

View on GitHub (pinned to 1fa9837ec2)