Vite Plugin

The @vitest/ui Vite plugin provides a development-time web interface for Vitest, serving the UI application and handling WebSocket connections for real-time test monitoring.

Core Import

import vitestUI from "@vitest/ui";

API

Plugin Factory Function

Creates a Vite plugin that integrates the Vitest UI into your development server.

declare function vitestUI(ctx: Vitest): Plugin;

Parameters:

• ctx: Vitest - The Vitest instance context containing configuration and state

Returns:

• Plugin - A Vite plugin object with server middleware configuration

Usage Examples

Basic Setup

import { defineConfig } from 'vite';
import vitestUI from '@vitest/ui';

export default defineConfig({
  plugins: [
    vitestUI(vitestContext), // Pass your Vitest instance
  ],
});

With Vitest Configuration

import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [
    // Vitest will automatically configure the UI plugin when ui: true
  ],
  test: {
    ui: true,
    uiBase: '/vitest-ui', // Custom base path
  },
});

Plugin Behavior

The plugin performs several key functions:

1. Version Validation: Ensures @vitest/ui version matches the Vitest core version
2. Static File Serving: Serves the Vue.js client application from the built dist directory
3. Coverage Integration: Provides access to HTML coverage reports if enabled
4. File Attachment Handling: Manages test attachments and makes them accessible via HTTP
5. API Token Injection: Injects WebSocket API tokens into the HTML for secure connections

Middleware Configuration

The plugin configures several middleware handlers:

• Attachment Middleware: Serves test attachments via /__vitest_attachment__ endpoint
• HTML Middleware: Serves the main UI HTML with injected configuration
• Static File Middleware: Serves client assets (CSS, JS, images)
• Coverage Middleware: Serves HTML coverage reports when available

Error Handling

The plugin includes validation to prevent configuration conflicts:

// Example error case
if (coveragePath && base === coveragePath) {
  throw new Error(
    `The ui base path and the coverage path cannot be the same: ${base}, change coverage.reportsDirectory`
  );
}

Types

interface Plugin {
  name: string;
  apply: string;
  configureServer: {
    order: string;
    handler: (server: ViteDevServer) => void;
  };
}