Vitest "Failed to load setup file" (setupFiles) in CI

By Kaveh Alemi·Latchkey

Vitest runs each setupFiles entry before your tests. If the path does not resolve on the runner, or the setup throws (a missing import like @testing-library/jest-dom), every test in that project fails at startup.

What this error means

The run fails with "Failed to load ./src/setup.ts" or an error thrown from inside the setup file, and no tests execute.

Error: Failed to load setup file: /home/runner/work/app/app/src/test/setup.ts
Cannot find package '@testing-library/jest-dom' imported from setup.ts

Common causes

The setup path does not resolve in CI

A relative path that worked from one directory does not resolve when the root or working directory differs on the runner.

The setup imports a missing dependency

The setup imports a testing helper (jest-dom, a polyfill) that is not in the CI dependency tree, so loading it throws.

How to fix it

Use a resolvable path and install setup deps

1. Point setupFiles at a path relative to the config root that exists in the checkout.
2. Install every package the setup imports as a devDependency.
3. Re-run so the setup loads cleanly.

export default defineConfig({
  test: { setupFiles: ['./src/test/setup.ts'] },
})

Install the setup dependencies

Add packages the setup imports so a clean CI install includes them.

npm install -D @testing-library/jest-dom

How to prevent it

• Reference setup files relative to the config root.
• Declare every setup import in devDependencies.
• Run from a clean npm ci so setup gaps appear in CI, not later.

Frequently asked questions

Related guides

References

• GitHub Actions documentation