0
# HTML Reporter
1
2
The HTML Reporter generates comprehensive standalone HTML reports from Vitest test results, providing an interactive interface for viewing test outcomes, coverage data, and detailed error information.
3
4
## Core Import
5
6
```typescript
7
import HTMLReporter from "@vitest/ui/reporter";
8
```
9
10
## API
11
12
### HTMLReporter Class
13
14
Main class for generating HTML test reports.
15
16
```typescript { .api }
17
declare class HTMLReporter implements Reporter {
18
constructor(options: HTMLOptions);
19
onInit(ctx: Vitest): Promise<void>;
20
onFinished(): Promise<void>;
21
processAttachment(attachment: TestAttachment): Promise<void>;
22
writeReport(report: string): Promise<void>;
23
}
24
```
25
26
**Constructor Parameters:**
27
- `options: HTMLOptions` - Configuration options for the HTML reporter
28
29
**Methods:**
30
- `onInit(ctx: Vitest): Promise<void>` - Initialize the reporter with Vitest context
31
- `onFinished(): Promise<void>` - Generate the final HTML report after tests complete
32
- `processAttachment(attachment: TestAttachment): Promise<void>` - Process and store test attachments
33
- `writeReport(report: string): Promise<void>` - Write the HTML report to the file system
34
35
## Usage Examples
36
37
### Basic Configuration
38
39
```typescript
40
import { defineConfig } from 'vitest/config';
41
import HTMLReporter from '@vitest/ui/reporter';
42
43
export default defineConfig({
44
test: {
45
reporters: [
46
new HTMLReporter({ outputFile: 'test-results/index.html' })
47
],
48
},
49
});
50
```
51
52
### Multiple Output Formats
53
54
```typescript
55
import { defineConfig } from 'vitest/config';
56
import HTMLReporter from '@vitest/ui/reporter';
57
58
export default defineConfig({
59
test: {
60
reporters: [
61
'default', // Console reporter
62
new HTMLReporter({ outputFile: 'reports/test-results.html' }),
63
],
64
},
65
});
66
```
67
68
### Custom Output Directory
69
70
```typescript
71
export default defineConfig({
72
test: {
73
reporters: [
74
new HTMLReporter({
75
outputFile: 'dist/reports/vitest-report.html'
76
})
77
],
78
},
79
});
80
```
81
82
## Report Generation Process
83
84
The HTML reporter follows this workflow:
85
86
1. **Initialization**: Sets up output directories and file paths
87
2. **Data Collection**: Gathers test results, module graphs, and source code
88
3. **Attachment Processing**: Handles test attachments (images, files, etc.)
89
4. **Report Serialization**: Converts test data to compressed JSON format
90
5. **Asset Copying**: Copies UI client files to the report directory
91
6. **HTML Generation**: Creates the final HTML file with embedded metadata
92
93
## Report Structure
94
95
Generated reports include:
96
97
- **Interactive Test Tree**: Hierarchical view of test files and suites
98
- **Test Results**: Pass/fail status, timing information, and error details
99
- **Source Code**: Syntax-highlighted source code for failed tests
100
- **Module Graphs**: Dependency relationships between test files
101
- **Attachments**: Images, screenshots, and other test artifacts
102
- **Coverage Integration**: Links to HTML coverage reports when available
103
104
## Attachment Handling
105
106
The reporter automatically processes test attachments:
107
108
```typescript
109
// External URLs are preserved as-is
110
if (attachment.path.startsWith('http://') || attachment.path.startsWith('https://')) {
111
attachment.body = undefined;
112
return;
113
}
114
115
// Local files are copied to the report directory
116
const buffer = await readFile(attachment.path);
117
const hash = crypto.createHash('sha1').update(buffer).digest('hex');
118
const filename = hash + extname(attachment.path);
119
await writeFile(resolve(this.reporterDir, 'data', filename), buffer);
120
```
121
122
## Types
123
124
```typescript { .api }
125
// HTMLOptions is imported from 'vitest/node'
126
interface HTMLOptions {
127
outputFile?: string | Partial<Record<string, string>>;
128
}
129
130
interface HTMLReportData {
131
paths: string[];
132
files: RunnerTestFile[];
133
config: SerializedConfig;
134
projects: string[];
135
moduleGraph: Record<string, Record<string, ModuleGraphData>>;
136
unhandledErrors: unknown[];
137
sources: Record<string, string>;
138
}
139
140
interface TestAttachment {
141
path?: string;
142
body?: string | Buffer;
143
contentType?: string;
144
}
145
```