0
# @vitest/ui
1

2
@vitest/ui provides a web-based user interface for the Vitest testing framework, offering developers a visual and interactive way to run, monitor, and analyze their test suites. The package includes both a Vite plugin for development mode and an HTML reporter for generating standalone test reports.
3

4
## Package Information
5

6
- **Package Name**: @vitest/ui
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vitest/ui`
10

11
## Core Imports
12

13
```typescript
14
import vitestUI from "@vitest/ui";
15
```
16

17
For the HTML reporter:
18

19
```typescript
20
import HTMLReporter from "@vitest/ui/reporter";
21
```
22

23
## Basic Usage
24

25
### Vite Plugin (Development Mode)
26

27
```typescript
28
import { defineConfig } from 'vite';
29
import vitestUI from '@vitest/ui';
30

31
export default defineConfig({
32
  plugins: [
33
    vitestUI(vitestContext), // vitestContext is a Vitest instance
34
  ],
35
});
36
```
37

38
### HTML Reporter (Build Mode)
39

40
```typescript
41
import { defineConfig } from 'vitest/config';
42
import HTMLReporter from '@vitest/ui/reporter';
43

44
export default defineConfig({
45
  test: {
46
    reporters: [
47
      new HTMLReporter({ outputFile: 'test-results/index.html' })
48
    ],
49
  },
50
});
51
```
52

53
## Architecture
54

55
@vitest/ui is built around several key components:
56

57
- **Vite Plugin**: Serves the UI interface during development with real-time WebSocket communication
58
- **HTML Reporter**: Generates static HTML reports for CI/CD and offline viewing
59
- **Client Application**: Vue.js-based SPA that provides the actual UI interface
60
- **WebSocket Client**: Real-time communication layer for live test updates
61
- **Explorer Tree**: Hierarchical test result management and visualization
62

63
## Capabilities
64

65
### Vite Plugin Integration
66

67
Provides a Vite plugin that serves the Vitest UI during development, enabling real-time test monitoring and interaction through a web interface.
68

69
```typescript { .api }
70
declare function vitestUI(ctx: Vitest): Plugin;
71
```
72

73
[Vite Plugin](./vite-plugin.md)
74

75
### HTML Report Generation
76

77
Generates comprehensive HTML reports containing test results, coverage information, and interactive visualizations for offline viewing and CI/CD integration.
78

79
```typescript { .api }
80
declare class HTMLReporter implements Reporter {
81
  constructor(options: HTMLOptions);
82
  onInit(ctx: Vitest): Promise<void>;
83
  onFinished(): Promise<void>;
84
}
85
```
86

87
[HTML Reporter](./html-reporter.md)
88

89
### Client-Side WebSocket API
90

91
Browser-based API for connecting to and controlling Vitest through WebSocket communication, including test execution, file management, and result viewing.
92

93
```typescript { .api }
94
interface BrowserUI {
95
  setCurrentFileId(fileId: string): void;
96
  setIframeViewport(width: number, height: number): Promise<void>;
97
}
98
```
99

100
[Client API](./client-api.md)
101

102
## Types
103

104
```typescript { .api }
105
interface WSMessage {
106
  type: string;
107
  data: any;
108
}
109

110
type RunState = 'idle' | 'running';
111

112
interface BrowserRunnerState {
113
  files: string[];
114
  config: SerializedConfig;
115
  type: 'orchestrator';
116
  provider: string;
117
  wrapModule: <T>(module: () => T) => T;
118
}
119

120
interface HTMLOptions {
121
  outputFile?: string | Partial<Record<string, string>>;
122
}
123

124
// External types from dependencies:
125
// - Vitest: from 'vitest/node'
126
// - Plugin: from 'vite'  
127
// - Reporter: from 'vitest/reporters'
128
// - SerializedConfig: from 'vitest'
129
```