{"id":14246,"library":"vite-test-utils","title":"Vite Test Utilities","description":"Vite Test Utilities (`vite-test-utils`) is a library designed to streamline integration and end-to-end testing for Vite applications. It provides an approachable set of APIs, including a web-standard `$fetch` and methods for manual server and browser control, which can be used out-of-the-box. The library focuses on instant server and browser startup by leveraging Vite's dev or preview server and Playwright, significantly reducing boilerplate for test environments. It supports fixture-based testing with overridable Vite configurations and is highly optimized for use with Vitest, aiming for lightning-fast test execution. The current stable version is `0.6.0`, which includes support for Vite v4 and Vitest 0.26. The project demonstrates an active development cadence, frequently releasing updates to align with its core dependencies, ensuring compatibility with the evolving Vite ecosystem.","status":"active","version":"0.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/kazupon/vite-test-utils","tags":["javascript","vite","vite.js","test","vitest","e2e","playwright","typescript"],"install":[{"cmd":"npm install vite-test-utils","lang":"bash","label":"npm"},{"cmd":"yarn add vite-test-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-test-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for managing the development and preview server, and for integrating with Vite's build process.","package":"vite","optional":false},{"reason":"Primary integrated test runner; the library is optimized to work seamlessly within a Vitest environment.","package":"vitest","optional":false},{"reason":"Used for browser automation to facilitate end-to-end testing scenarios.","package":"playwright","optional":false}],"imports":[{"note":"The primary function to initialize the Vite testing environment, returning server, browser, and fetch utilities. This package is ESM-first.","wrong":"const { setup } = require('vite-test-utils')","symbol":"setup","correct":"import { setup } from 'vite-test-utils'"},{"note":"Provides a web-standard `fetch` API for making HTTP requests against the test server, typically accessed from the object returned by `setup`.","symbol":"$fetch","correct":"const { fetch: $fetch } = await setup(...); // Access from setup context"},{"note":"The `server` object, returned from `setup`, provides access to the Vite test server URL and control methods like `server.close()`.","symbol":"server","correct":"const { server } = await setup(...); // Access from setup context"},{"note":"The `browser` object, returned from `setup` when `browser: true` option is used, provides a Playwright page instance for browser interaction.","symbol":"browser","correct":"const { browser } = await setup(...); // Access from setup context"}],"quickstart":{"code":"import { describe, test, expect, beforeAll } from 'vitest';\nimport { setup } from 'vite-test-utils';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n// A small fixture directory with a simple Vite app is assumed:\n// project-root/test/fixture/index.html\n// project-root/test/fixture/main.ts (Vue/React app with an H1 and button)\n\n// ESM-friendly way to get __dirname\nconst __dirname = fileURLToPath(new URL('.', import.meta.url));\n\ndescribe('Vite Application Integration Test', () => {\n  let server: Awaited<ReturnType<typeof setup>>['server'];\n  let browser: Awaited<ReturnType<typeof setup>>['browser'];\n  let $fetch: Awaited<ReturnType<typeof setup>>['fetch'];\n\n  // Setup the Vite development server and Playwright browser before all tests\n  beforeAll(async () => {\n    // `setup` handles starting/stopping the server and browser\n    ({ server, browser, fetch: $fetch } = await setup({\n      rootDir: path.resolve(__dirname, './fixture'), // Path to your mock Vite project\n      browser: true, // Enable browser testing with Playwright\n      viteConfig: {\n        // Example: Add a mock API route for $fetch demonstration\n        configureServer(viteServer) {\n          viteServer.middlewares.use('/api/data', (req, res) => {\n            res.setHeader('Content-Type', 'application/json');\n            res.end(JSON.stringify({ message: 'Data from mock API' }));\n          });\n        },\n      },\n    }));\n  }, 30000); // Increase timeout for setup if needed\n\n  test('should render the app title', async () => {\n    await browser.goto(server.url); // Navigate to the running Vite app\n    const h1Text = await browser.textContent('h1');\n    expect(h1Text).toBe('Hello Vite App'); // Assumes fixture's index.html/main.ts renders 'Hello Vite App'\n  });\n\n  test('should increment count on button click', async () => {\n    await browser.goto(server.url);\n    const button = browser.locator('button'); // Assumes fixture has a button\n    await button.click();\n    expect(await button.textContent()).toBe('1');\n  });\n\n  test('should make API calls with $fetch', async () => {\n    const response = await $fetch('/api/data'); // Use the fetch utility from the setup context\n    expect(response).toEqual({ message: 'Data from mock API' });\n  });\n});","lang":"typescript","description":"Demonstrates setting up a Vite application with Vitest and Playwright, performing browser interaction tests, and making API calls against the test server using `$fetch`."},"warnings":[{"fix":"Review and update your `setup` configuration options related to browser features to align with the new defaults, consulting the official documentation for `v0.4.0` or later.","message":"The default behavior for browser features was changed, potentially affecting existing browser testing configurations.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Adjust your test files to destructure the utility functions (like `server`, `browser`, `fetch`) from the `setup` function's return object or from the updated Vitest context if applicable.","message":"The method for APIs exporting via the Vitest context was modified, changing how test utilities are accessed within your tests.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Ensure your project and its dependencies are configured consistently for ESM where possible. If encountering resolution errors, consider Vitest's `test.deps.inline` or `resolve.mainFields` configuration options, or explicitly define `exports` in your `package.json` with `import` and `require` conditions.","message":"Mixing CommonJS (CJS) and ESM modules, especially with `exports` maps in `package.json`, can lead to module resolution issues with Vitest and Vite, resulting in packages being incorrectly loaded or not found. Vite itself is deprecating its CJS Node API.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.26':121 '0.6.0':112 'activ':126 'aim':100 'align':133 'api':33 'applic':26 'approach':30 'base':86 'boilerpl':78 'box':56 'browser':46,64 'cadenc':128 'compat':139 'configur':91 'control':47 'core':136 'current':108 'demonstr':124 'depend':137 'design':14 'dev':70 'develop':127 'e2e':150 'ecosystem':144 'end':20,22 'end-to-end':19 'ensur':138 'environ':81 'evolv':142 'execut':106 'fast':104 'fetch':39 'fixtur':85 'fixture-bas':84 'focus':59 'frequent':129 'high':94 'includ':34,114 'instant':61 'integr':17 'javascript':145 'leverag':67 'librari':13,58 'lightn':103 'lightning-fast':102 'manual':43 'method':41 'optim':95 'out-of-the-box':52 'overrid':89 'playwright':75,151 'preview':72 'project':123 'provid':28 'reduc':77 'releas':130 'server':44,62,73 'set':31 'signific':76 'stabl':109 'standard':38 'startup':65 'streamlin':16 'support':83,115 'test':2,5,9,23,80,87,105,148 'typescript':152 'updat':131 'use':51,97 'util':3,6,10 'v4':118 'version':110 'vite':1,4,8,25,68,90,117,143,146 'vite-test-util':7 'vite.js':147 'vitest':99,120,149 'web':37 'web-standard':36","created_at":"2026-04-20T01:58:41.706327+00:00","updated_at":"2026-04-20T01:58:41.706327+00:00","problems":[{"fix":"For 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.","cause":"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`.","error":"Error: Failed to resolve entry for package \"@myorg/mypackage\". The package may have incorrect main/module/exports specified in its package.json."},{"fix":"If 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.","cause":"Node.js-specific global `process` is being accessed in a browser-like environment (e.g., `jsdom` or Playwright tests) without proper polyfill or mocking.","error":"ReferenceError: process is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/kazupon/vite-test-utils","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vite-test-utils","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}