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
```