Ensuring Node.js API Availability in Vitest with Explicit Environment Configuration

Need Node.js APIs (like `fs` or `path`) during Vitest testing? Explicitly set `environment: 'node'` in your configuration.

Vitest defaults to environments optimized for browser-like execution (e.g., JSDOM). If your tests rely on standard Node.js modules—such as the built-in `fs` (file system) or `path` module—you must configure Vitest to use the Node runtime environment.

Configuring the Node Environment

This is managed within your Vitest configuration file, typically vitest.config.ts (or vitest.config.js).

Example Configuration

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node', // This ensures Node.js APIs are available
    globals: true,
  },
});

Note: globals: true makes testing utilities like describe and it available globally without explicit imports.

Mocking Dependencies in Node Context

Even when using the Node environment, dependency mocking remains crucial for isolation. Use vi.mock() at the top level of the test file to intercept module imports.

Mocking Example

import { vi, describe, it, expect } from 'vitest';
// Mocking the built-in 'fs' module for testing file operations without disk I/O
vi.mock('fs', () => ({
  readFileSync: vi.fn(() => 'mocked file content'),
}));

describe('File Reader Test', () => {
  it('should read content correctly using the mock', () => {
    // Test logic that imports and uses 'fs'
    const fs = require('fs');
    expect(fs.readFileSync('test.txt')).toBe('mocked file content');
  });
});

Permissions: Configuration changes require write access to the project root where vitest.config.ts resides. No elevated permissions are needed for running tests.

Limitations and Common Pitfalls

• Node Version Compatibility: Ensure your Node.js version meets the requirements of your specific Vitest release. Older versions may lack necessary APIs.
• Environment Mismatch: If your application runs in a browser (e.g., via Vite dev server) but your tests use environment: 'node', tests relying on browser globals (like window) will fail.

Verification: Run the command npx vitest --environment node from your terminal. If the test suite executes without errors related to missing Node APIs (e.g., fs is not defined), the configuration is likely correct.

Practical Check: In a test file, attempt to use require('path'). If it succeeds without runtime errors, the environment: 'node' setting is active.