0
# @umijs/test
1

2
@umijs/test provides Jest testing utilities and configurations specifically designed for Umi applications. It offers pre-configured Jest setups with support for multiple JavaScript transformers (esbuild, swc, ts-jest), TypeScript/JSX transformation, CSS module mocking, and both Node.js and browser testing environments.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript { .api }
14
import { createConfig, JSTransformer } from "@umijs/test";
15
import type { Config } from "@umijs/test";
16
```
17

18
For CommonJS:
19

20
```javascript { .api }
21
const { createConfig } = require("@umijs/test");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { createConfig } from "@umijs/test";
28

29
// Basic Jest configuration with default esbuild transformer
30
const jestConfig = createConfig();
31

32
// Configuration with specific transformer
33
const jestConfigWithSwc = createConfig({
34
  jsTransformer: 'swc',
35
  target: 'node'
36
});
37

38
// Browser environment configuration
39
const browserConfig = createConfig({
40
  jsTransformer: 'esbuild',
41
  target: 'browser',
42
  jsTransformerOpts: {
43
    target: 'es2020'
44
  }
45
});
46

47
export default jestConfig;
48
```
49

50
## Architecture
51

52
@umijs/test is built around several key components:
53

54
- **Configuration Factory**: The `createConfig` function generates complete Jest configurations with Umi-specific defaults
55
- **Transformer System**: Pluggable JavaScript/TypeScript transformation supporting esbuild, swc, and ts-jest
56
- **Module Resolution**: Custom resolver that prioritizes main field over module field in package.json
57
- **Environment Setup**: Automatic polyfill injection for test environments (fetch via isomorphic-unfetch)
58
- **CSS Module Handling**: Built-in CSS/LESS/SASS/SCSS/Stylus module mocking via identity-obj-proxy
59

60
## Capabilities
61

62
### Jest Configuration Creation
63

64
Creates a pre-configured Jest configuration optimized for Umi applications with sensible defaults and transformer support.
65

66
```typescript { .api }
67
/**
68
 * Creates a Jest configuration with Umi-specific defaults
69
 * @param opts - Configuration options
70
 * @returns Complete Jest configuration object
71
 */
72
function createConfig(opts?: {
73
  /** JavaScript transformer to use - defaults to 'esbuild' */
74
  jsTransformer?: JSTransformer;
75
  /** Runtime environment - defaults to 'node' */
76
  target?: 'node' | 'browser';
77
  /** Additional options passed to the JS transformer */
78
  jsTransformerOpts?: any;
79
}): Config.InitialOptions;
80
```
81

82
**Configuration Defaults:**
83

84
The `createConfig` function provides these pre-configured settings:
85

86
- **Test Match Patterns**: `**/*.test.(t|j)s(x)?` - Matches test files with .test extension
87
- **Transform Patterns**: Handles TypeScript, JavaScript, JSX, and .mjs files
88
- **Module Name Mapping**: CSS/LESS/SASS/SCSS/Stylus files mapped to `identity-obj-proxy`
89
- **Test Timeout**: 30 seconds (30000ms)
90
- **Transform Ignore Patterns**: Transforms all node_modules (empty ignore pattern)
91
- **Path Ignore Patterns**: Ignores compiled and fixtures directories
92
- **Setup Files**: Automatically includes isomorphic-unfetch polyfill
93
- **Custom Resolver**: Uses package.json main field prioritization
94
- **Test Environment**: Node.js by default, jsdom when `target: 'browser'`
95

96
**Usage Examples:**
97

98
```typescript
99
// Default configuration with esbuild
100
const defaultConfig = createConfig();
101

102
// Swc transformer for faster builds
103
const swcConfig = createConfig({
104
  jsTransformer: 'swc'
105
});
106

107
// Browser environment with jsdom
108
const browserConfig = createConfig({
109
  target: 'browser',
110
  jsTransformer: 'esbuild',
111
  jsTransformerOpts: {
112
    target: 'es2020',
113
    sourcemap: true
114
  }
115
});
116

117
// ts-jest for maximum TypeScript compatibility
118
const tsJestConfig = createConfig({
119
  jsTransformer: 'ts-jest'
120
});
121
```
122

123
## Types
124

125
```typescript { .api }
126
/** Supported JavaScript/TypeScript transformers */
127
type JSTransformer = 'esbuild' | 'swc' | 'ts-jest';
128

129
/** Jest configuration interface (re-exported from @jest/types) */
130
interface Config {
131
  // Complete Jest configuration type from @jest/types
132
  InitialOptions: {
133
    testMatch?: string[];
134
    transform?: Record<string, any>;
135
    moduleNameMapper?: Record<string, string>;
136
    testTimeout?: number;
137
    transformIgnorePatterns?: string[];
138
    setupFiles?: string[];
139
    resolver?: string;
140
    testEnvironment?: string;
141
    // ... and all other Jest configuration options
142
  };
143
}
144
```
145

146
## Internal Components
147

148
The package includes several internal utilities that power the main API:
149

150
### EsBuild Transformer
151

152
Custom Jest transformer using esbuild for fast TypeScript/JavaScript compilation:
153

154
- **File Support**: `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs` files
155
- **Jest Mock Support**: Special handling for `jest.mock()` calls via Babel transformation
156
- **Source Maps**: Full source map support for debugging
157
- **Caching**: MD5-based caching for improved performance
158
- **ESBuild Options**: Configurable via `jsTransformerOpts` parameter
159

160
### Custom Resolver
161

162
Jest resolver that modifies package.json resolution:
163

164
- **Main Field Priority**: Prioritizes `main` field over `module` field
165
- **Compatibility**: Ensures better compatibility with CommonJS-first packages
166
- **Fallback**: Uses Jest's default resolver as fallback
167

168
### Setup Files
169

170
Automatic environment setup:
171

172
- **Fetch Polyfill**: Includes `isomorphic-unfetch` for fetch API support in Node.js test environments
173
- **Auto-injection**: Automatically included in all Jest configurations
174

175
## Error Handling
176

177
The package handles several common testing scenarios:
178

179
- **Unknown Transformer**: Throws descriptive error for unsupported `jsTransformer` values
180
- **Transform Warnings**: Logs esbuild warnings to console during transformation
181
- **Module Resolution**: Falls back to default Jest resolver if custom resolution fails
182

183
## Advanced Configuration
184

185
For advanced use cases, you can extend the returned configuration:
186

187
```typescript { .api }
188
import { createConfig } from "@umijs/test";
189

190
const baseConfig = createConfig({
191
  jsTransformer: 'esbuild',
192
  target: 'node'
193
});
194

195
// Extend with custom settings
196
const customConfig = {
197
  ...baseConfig,
198
  collectCoverage: true,
199
  coverageDirectory: 'coverage',
200
  coverageReporters: ['text', 'lcov'],
201
  setupFilesAfterEnv: ['<rootDir>/test-setup.ts']
202
};
203

204
export default customConfig;
205
```