fix: improve runner error when importing outside of test context (#9335)

sheremet-va · web-flow · commit 2dd3dd8396e7 · 2025-12-27T15:39:36.000+01:00
diff --git a/packages/runner/src/suite.ts b/packages/runner/src/suite.ts
@@ -187,7 +187,13 @@ let currentTestFilepath: string
 
 function assert(condition: any, message: string) {
   if (!condition) {
-    throw new Error(`Vitest failed to find ${message}. This is a bug in Vitest. Please, open an issue with reproduction.`)
+    throw new Error(
+      `Vitest failed to find ${message}. One of the following is possible:`
+      + '\n- "vitest" is imported directly without running "vitest" command'
+      + '\n- "vitest" is imported inside "globalSetup" (to fix this, use "setupFiles" instead, because "globalSetup" runs in a different context)'
+      + '\n- "vitest" is imported inside Vite / Vitest config file'
+      + '\n- Otherwise, it might be a Vitest bug. Please report it to https://github.com/vitest-dev/vitest/issues\n',
+    )
   }
 }
 
diff --git a/test/global-setup/globalSetup/failing.ts b/test/global-setup/globalSetup/failing.ts
@@ -0,0 +1,10 @@
+import assert from 'node:assert'
+// node can import from vitest at any point
+import { beforeAll } from 'vitest'
+
+assert.throws(() => {
+  // some vitest API cannot be used outside of a test context
+  beforeAll(() => {})
+}, /Vitest failed to find the runner. One of the following is possible/)
+
+export default () => {}
diff --git a/test/global-setup/vitest.config.ts b/test/global-setup/vitest.config.ts
@@ -21,6 +21,7 @@ export default defineConfig({
       './globalSetup/ts-with-imports.ts',
       './globalSetup/another-vite-instance.ts',
       './globalSetup/update-env.ts',
+      './globalSetup/failing.ts',
     ],
   },
 })

Original file line number	Diff line number	Diff line change
`@@ -187,7 +187,13 @@ let currentTestFilepath: string`
`187`	`187`
`188`	`188`	`function assert(condition: any, message: string) {`
`189`	`189`	`if (!condition) {`
`190`		- throw new Error(`Vitest failed to find ${message}. This is a bug in Vitest. Please, open an issue with reproduction.`)
	`190`	`+ throw new Error(`
	`191`	+ `Vitest failed to find ${message}. One of the following is possible:`
	`192`	`+ + '\n- "vitest" is imported directly without running "vitest" command'`
	`193`	`+ + '\n- "vitest" is imported inside "globalSetup" (to fix this, use "setupFiles" instead, because "globalSetup" runs in a different context)'`
	`194`	`+ + '\n- "vitest" is imported inside Vite / Vitest config file'`
	`195`	`+ + '\n- Otherwise, it might be a Vitest bug. Please report it to https://github.com/vitest-dev/vitest/issues\n',`
	`196`	`+ )`
`191`	`197`	`}`
`192`	`198`	`}`
`193`	`199`