Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
setup
✓ import { setup } from 'vite-test-utils'
✗ const { setup } = require('vite-test-utils')
The primary function to initialize the Vite testing environment, returning server, browser, and fetch utilities. This package is ESM-first.
$fetch
✓ const { fetch: $fetch } = await setup(...); // Access from setup context
Provides a web-standard `fetch` API for making HTTP requests against the test server, typically accessed from the object returned by `setup`.
server
✓ const { server } = await setup(...); // Access from setup context
The `server` object, returned from `setup`, provides access to the Vite test server URL and control methods like `server.close()`.
browser
✓ const { browser } = await setup(...); // Access from setup context
The `browser` object, returned from `setup` when `browser: true` option is used, provides a Playwright page instance for browser interaction.
Demonstrates setting up a Vite application with Vitest and Playwright, performing browser interaction tests, and making API calls against the test server using `$fetch`.
import { describe, test, expect, beforeAll } from 'vitest';
import { setup } from 'vite-test-utils';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
// A small fixture directory with a simple Vite app is assumed:
// project-root/test/fixture/index.html
// project-root/test/fixture/main.ts (Vue/React app with an H1 and button)
// ESM-friendly way to get __dirname
const __dirname = fileURLToPath(new URL('.', import.meta.url));
describe('Vite Application Integration Test', () => {
let server: Awaited<ReturnType<typeof setup>>['server'];
let browser: Awaited<ReturnType<typeof setup>>['browser'];
let $fetch: Awaited<ReturnType<typeof setup>>['fetch'];
// Setup the Vite development server and Playwright browser before all tests
beforeAll(async () => {
// `setup` handles starting/stopping the server and browser
({ server, browser, fetch: $fetch } = await setup({
rootDir: path.resolve(__dirname, './fixture'), // Path to your mock Vite project
browser: true, // Enable browser testing with Playwright
viteConfig: {
// Example: Add a mock API route for $fetch demonstration
configureServer(viteServer) {
viteServer.middlewares.use('/api/data', (req, res) => {
res.setHeader('Content-Type', 'application/json');
res.end(JSON.stringify({ message: 'Data from mock API' }));
});
},
},
}));
}, 30000); // Increase timeout for setup if needed
test('should render the app title', async () => {
await browser.goto(server.url); // Navigate to the running Vite app
const h1Text = await browser.textContent('h1');
expect(h1Text).toBe('Hello Vite App'); // Assumes fixture's index.html/main.ts renders 'Hello Vite App'
});
test('should increment count on button click', async () => {
await browser.goto(server.url);
const button = browser.locator('button'); // Assumes fixture has a button
await button.click();
expect(await button.textContent()).toBe('1');
});
test('should make API calls with $fetch', async () => {
const response = await $fetch('/api/data'); // Use the fetch utility from the setup context
expect(response).toEqual({ message: 'Data from mock API' });
});
});
Errors
Common errors & fixes
Error: Failed to resolve entry for package "@myorg/mypackage". The package may have incorrect main/module/exports specified in its package.json.
Vitest or Vite failed to correctly resolve a package, often due to mismatched ESM/CJS configurations or an incorrectly defined `exports` field in the dependency's `package.json`.
fixFor third-party dependencies, try adding the package to `test.deps.inline` in your `vite.config.ts` or `vitest.config.ts`. For your own packages, ensure `package.json` explicitly defines `exports` with `import` and `require` conditions if supporting both module types, and that `type: 'module'` is correctly set if using ESM.
ReferenceError: process is not defined
Node.js-specific global `process` is being accessed in a browser-like environment (e.g., `jsdom` or Playwright tests) without proper polyfill or mocking.
fixIf the code is intended for the browser, remove or conditionally guard `process` usage. For test environments, you can configure Vitest's `test.globals` or mock `process` global if specific properties are needed for browser tests. Alternatively, ensure the `test.environment` is set to `'node'` if the tests are exclusively server-side.
Audit
Dependencies
viterequiredCore dependency for managing the development and preview server, and for integrating with Vite's build process.
vitestrequiredPrimary integrated test runner; the library is optimized to work seamlessly within a Vitest environment.
playwrightrequiredUsed for browser automation to facilitate end-to-end testing scenarios.