SolidJS Vitest "document is not defined" (missing jsdom) in CI

By Kaveh Alemi·Latchkey

Vitest defaults to a Node environment with no DOM. Solid tests that render components need jsdom (or happy-dom); without it, calls into document throw "document is not defined" in CI.

What this error means

Locally passing tests fail in CI with "ReferenceError: document is not defined" during render(...), because the CI Vitest config did not set a DOM environment.

FAIL  src/App.test.tsx
ReferenceError: document is not defined
  at render (@solidjs/testing-library)

Common causes

No DOM test environment configured

Vitest runs in node by default; rendering Solid components needs a simulated DOM.

A missing jsdom/happy-dom dependency

The environment is set but the DOM package is not installed on the runner.

How to fix it

Set the jsdom environment

1. Install jsdom and @solidjs/testing-library as dev dependencies.
2. Set test.environment to jsdom in the Vitest config.
3. Keep the Solid conditions so the browser build is tested.

import { defineConfig } from 'vitest/config';
import solid from 'vite-plugin-solid';

export default defineConfig({
  plugins: [solid()],
  test: { environment: 'jsdom' },
});

Install the DOM package in CI

Ensure jsdom is in devDependencies so npm ci provides it on the runner.

npm install -D jsdom @solidjs/testing-library

How to prevent it

• Set test.environment: jsdom for component tests.
• Keep jsdom/happy-dom in devDependencies.
• Load vite-plugin-solid in the Vitest config too.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation