0
# @umijs/test-utils
1
2
@umijs/test-utils provides testing utilities for Umi applications, enabling developers to create controlled testing environments with temporary file generation, HTML output, React component rendering, and content retrieval. It integrates seamlessly with Umi's service architecture and React Testing Library.
3
4
## Package Information
5
6
- **Package Name**: @umijs/test-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @umijs/test-utils`
10
- **Peer Dependencies**: `@testing-library/react ^9.4.0`, `umi ^3.0.0`
11
12
## Core Imports
13
14
```typescript
15
import { generateTmp, generateHTML, render, getHTML } from "@umijs/test-utils";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const { generateTmp, generateHTML, render, getHTML } = require("@umijs/test-utils");
22
```
23
24
## Basic Usage
25
26
```typescript
27
import { generateTmp, render, getHTML } from "@umijs/test-utils";
28
import { Service } from "@umijs/core";
29
30
// Generate temporary test environment
31
await generateTmp({
32
cwd: "/path/to/project",
33
Service,
34
});
35
36
// Render the generated app with React Testing Library
37
const { getByText } = render({ cwd: "/path/to/project" });
38
39
// Get HTML output for assertions
40
const htmlContent = getHTML({ cwd: "/path/to/project" });
41
```
42
43
## Architecture
44
45
@umijs/test-utils is built around the following key components:
46
47
- **Service Integration**: Leverages Umi's Service class to create isolated test environments
48
- **Memory History**: Uses memory-based routing through an internal plugin for predictable testing
49
- **Temporary Generation**: Creates `.umi-test` directories with all necessary Umi configuration and files
50
- **React Testing Library Integration**: Provides seamless component rendering for unit tests
51
- **HTML Output**: Generates and retrieves HTML files for integration testing
52
53
## Capabilities
54
55
### Temporary Environment Generation
56
57
Creates temporary Umi test environments with all necessary configuration files and dependencies.
58
59
```typescript { .api }
60
/**
61
* Generates temporary Umi test environment in .umi-test directory
62
* @param opts - Configuration options for test environment generation
63
* @returns Promise that resolves when generation is complete
64
*/
65
function generateTmp(opts: {
66
cwd: string;
67
Service?: typeof UmiService;
68
}): Promise<void>;
69
```
70
71
### HTML Generation
72
73
Generates HTML output files for testing and integration scenarios.
74
75
```typescript { .api }
76
/**
77
* Generates HTML output for testing in dist directory
78
* @param opts - Configuration options for HTML generation
79
* @returns Promise that resolves when HTML generation is complete
80
*/
81
function generateHTML(opts: {
82
cwd: string;
83
Service?: typeof UmiService;
84
}): Promise<void>;
85
```
86
87
### Component Rendering
88
89
Renders Umi applications using React Testing Library for component testing.
90
91
```typescript { .api }
92
/**
93
* Renders the generated Umi app using React Testing Library
94
* @param opts - Configuration options for rendering
95
* @returns RenderResult from React Testing Library for querying and interaction
96
*/
97
function render(opts: { cwd: string }): RenderResult;
98
```
99
100
### HTML Content Retrieval
101
102
Retrieves generated HTML content as a string for assertions and validation.
103
104
```typescript { .api }
105
/**
106
* Retrieves generated HTML content from dist/index.html
107
* @param opts - Configuration options for HTML retrieval
108
* @returns HTML content as a string
109
*/
110
function getHTML(opts: { cwd: string }): string;
111
```
112
113
## Types
114
115
```typescript { .api }
116
import { Service as UmiService } from 'umi';
117
import { RenderResult } from '@testing-library/react';
118
119
interface GenerationOptions {
120
/** Current working directory path for the test project */
121
cwd: string;
122
/** Optional Umi Service class override for custom service instances */
123
Service?: typeof UmiService;
124
}
125
126
interface RenderOptions {
127
/** Current working directory path containing the generated .umi-test files */
128
cwd: string;
129
}
130
131
interface HTMLOptions {
132
/** Current working directory path containing the generated dist files */
133
cwd: string;
134
}
135
```
136
137
## Usage Examples
138
139
### Complete Testing Workflow
140
141
```typescript
142
import { generateTmp, generateHTML, render, getHTML } from "@umijs/test-utils";
143
import { Service } from "@umijs/core";
144
145
// Setup test environment
146
const testCwd = "/tmp/test-project";
147
148
// Generate temporary test files
149
await generateTmp({
150
cwd: testCwd,
151
Service,
152
});
153
154
// Render app for component testing
155
const { getByText, container } = render({ cwd: testCwd });
156
157
// Assert component rendering
158
expect(getByText("Welcome")).toBeInTheDocument();
159
160
// Generate HTML for integration testing
161
await generateHTML({
162
cwd: testCwd,
163
Service,
164
});
165
166
// Get HTML content for validation
167
const htmlContent = getHTML({ cwd: testCwd });
168
expect(htmlContent).toContain("<title>My App</title>");
169
```
170
171
### Custom Service Configuration
172
173
```typescript
174
import { generateTmp } from "@umijs/test-utils";
175
import { Service } from "umi";
176
177
// Create custom service configuration
178
class CustomTestService extends Service {
179
constructor(opts) {
180
super({
181
...opts,
182
// Custom test-specific configuration
183
});
184
}
185
}
186
187
// Use custom service for test generation
188
await generateTmp({
189
cwd: "/path/to/project",
190
Service: CustomTestService,
191
});
192
```
193
194
## Error Handling
195
196
Functions may throw errors in the following scenarios:
197
198
- **File System Errors**: When `cwd` path doesn't exist or lacks proper permissions
199
- **Service Errors**: When Umi Service fails to initialize or execute commands
200
- **Generation Errors**: When temporary file generation fails due to configuration issues
201
- **Render Errors**: When React component rendering fails due to missing files or configuration
202
- **HTML Errors**: When `dist/index.html` file doesn't exist or can't be read
203
204
## File Structure
205
206
The package generates the following directory structure during testing:
207
208
```
209
project-root/
210
├── .umi-test/ # Temporary test environment
211
│ ├── umi.ts # Main Umi app entry point
212
│ ├── core/ # Core Umi files
213
│ └── ... # Other generated test files
214
└── dist/ # HTML output directory
215
└── index.html # Generated HTML file
216
```