0
# umi-test
1

2
umi-test is a Jest-based testing utility library specifically designed for Umi.js applications. It provides pre-configured Jest settings with custom transformers for JavaScript and TypeScript, automatic test file discovery, CSS/LESS module mocking, and integrated setup files for React component testing with Enzyme.
3

4
## Package Information
5

6
- **Package Name**: umi-test
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install umi-test`
10

11
## Core Imports
12

13
```javascript
14
const test = require("umi-test").default;
15
```
16

17
For ES modules:
18

19
```javascript
20
import test from "umi-test";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const test = require("umi-test").default;
27

28
// Run tests with default configuration
29
test().then(() => {
30
  console.log('Tests passed');
31
}).catch(e => {
32
  console.error('Tests failed:', e);
33
});
34

35
// Run tests with custom options
36
test({
37
  watch: true,
38
  coverage: true,
39
  cwd: '/path/to/project',
40
  moduleNameMapper: {
41
    '^@/(.*)$': '<rootDir>/src/$1'
42
  }
43
});
44
```
45

46
CLI usage:
47

48
```bash
49
# Run tests once
50
umi-test
51

52
# Run in watch mode
53
umi-test --watch
54

55
# Run with coverage
56
umi-test --coverage
57
```
58

59
## Architecture
60

61
umi-test is built around several key components:
62

63
- **Main Test Function**: Core test runner that configures and executes Jest with Umi-specific settings
64
- **CLI Binary**: Command-line interface for easy test execution
65
- **Custom Transformers**: Babel and TypeScript transformers optimized for Umi.js projects
66
- **Setup Files**: Pre-configured environment setup for JSDOM, Enzyme, and polyfills
67
- **Module Mocking**: Automatic CSS/LESS module mocking to prevent import errors
68

69
## Capabilities
70

71
### Main Test Function
72

73
Core test runner function that configures and runs Jest with Umi-specific settings including transformers, setup files, and module resolution.
74

75
```javascript { .api }
76
/**
77
 * Main test runner function for Umi.js applications
78
 * @param {Object} [opts={}] - Configuration options for Jest and test execution
79
 * @param {string} [opts.cwd] - Current working directory (defaults to process.cwd())
80
 * @param {Object} [opts.moduleNameMapper] - Additional module name mappings for Jest
81
 * @param {boolean} [opts.watch] - Enable watch mode
82
 * @param {boolean} [opts.coverage] - Enable coverage reporting
83
 * @returns {Promise<void>} Promise that resolves on successful test completion or rejects on failure
84
 */
85
function test(opts = {});
86
```
87

88
**Usage Examples:**
89

90
```javascript
91
const test = require("umi-test").default;
92

93
// Basic usage
94
await test();
95

96
// With custom configuration
97
await test({
98
  cwd: '/path/to/project',
99
  watch: true,
100
  coverage: true,
101
  moduleNameMapper: {
102
    '^@components/(.*)$': '<rootDir>/src/components/$1',
103
    '^@utils/(.*)$': '<rootDir>/src/utils/$1'
104
  }
105
});
106
```
107

108
### CLI Binary
109

110
Command-line interface for running tests with common options.
111

112
```bash { .api }
113
# Usage: umi-test [options]
114
# Options:
115
#   -w, --watch     Enable watch mode
116
#   --coverage      Enable coverage reporting
117
#   Additional Jest CLI options are passed through to Jest
118
```
119

120
**Usage Examples:**
121

122
```bash
123
# Run tests once
124
umi-test
125

126
# Run in watch mode
127
umi-test --watch
128

129
# Run with coverage
130
umi-test --coverage
131

132
# Combine options
133
umi-test --watch --coverage
134
```
135

136
### Transformers
137

138
Custom transformers for processing JavaScript, TypeScript, and JSX files.
139

140
```javascript { .api }
141
// JavaScript/JSX Transformer (babel-jest with babel-preset-umi)
142
const jsTransformer;
143

144
// TypeScript/TSX Transformer (ts-jest)  
145
const tsTransformer;
146

147
// JS Transformer Configuration:
148
// - Uses babel-preset-umi with transformRuntime: false
149
// - Includes babel-plugin-module-resolver with aliases:
150
//   - ts-jest, react, react-dom, enzyme
151
```
152

153
## Built-in Configuration
154

155
The test function provides comprehensive Jest configuration:
156

157
### Transform Configuration
158
- **JavaScript/JSX files**: Uses babel-jest with babel-preset-umi (transformRuntime: false) and babel-plugin-module-resolver for aliases
159
- **TypeScript/TSX files**: Uses ts-jest with useBabelrc: true
160
- **CSS/LESS/SASS/SCSS files**: Mocked with identity-obj-proxy
161

162
### Test Discovery
163
- **Pattern**: `**/?(*.)(spec|test|e2e).(j|t)s?(x)`
164
- **Extensions**: js, jsx, ts, tsx, json
165

166
### Module Resolution
167
- Provides aliases for common testing libraries (react, react-dom, enzyme, ts-jest)
168
- CSS modules are automatically mocked to prevent import errors
169
- Supports custom moduleNameMapper via options
170

171
### Environment Setup
172
- Sets NODE_ENV to 'test'
173
- Configures JSDOM with basic HTML structure including root div
174
- Sets up Enzyme with React 16 adapter
175
- Provides babel polyfill and requestAnimationFrame shim
176
- Sets jasmine timeout to 20 seconds (20000ms)
177

178
### Setup Files
179

180
```javascript { .api }
181
// Setup files loaded before tests:
182
// 1. require.resolve('./shim.js') - Babel polyfill and requestAnimationFrame shim
183
// 2. require.resolve('./setupTests.js') - JSDOM and Enzyme configuration
184

185
// Test framework setup:
186
// setupTestFrameworkScriptFile: require.resolve('./jasmine.js') - Sets jasmine timeout to 20000ms
187

188
// Module name mapping:
189
// CSS/LESS/SASS/SCSS files are mocked with identity-obj-proxy
190
```
191

192
## Custom Configuration
193

194
Users can provide additional Jest configuration by creating a `jest.config.js` file in their project root:
195

196
```javascript
197
// jest.config.js
198
module.exports = {
199
  // Custom configuration that will be merged with default umi-test config
200
  testTimeout: 30000,
201
  collectCoverageFrom: [
202
    'src/**/*.{js,jsx,ts,tsx}',
203
    '!src/**/*.d.ts',
204
  ],
205
  // Additional Jest options...
206
};
207
```
208

209
## Error Handling
210

211
The test function returns a Promise that:
212
- **Resolves** when all tests pass successfully
213
- **Rejects** with an Error('Jest failed') when tests fail
214
- **Logs errors** to console for debugging
215

216
## Configuration Details
217

218
```javascript { .api }
219
// Jest Configuration Generated:
220
{
221
  rootDir: process.cwd(),
222
  setupFiles: [
223
    require.resolve('./shim.js'),
224
    require.resolve('./setupTests.js')
225
  ],
226
  transform: {
227
    '\\.jsx?$': require.resolve('./transformers/jsTransformer'),
228
    '\\.tsx?$': require.resolve('./transformers/tsTransformer')
229
  },
230
  testMatch: ['**/?(*.)(spec|test|e2e).(j|t)s?(x)'],
231
  moduleFileExtensions: ['js', 'jsx', 'ts', 'tsx', 'json'],
232
  setupTestFrameworkScriptFile: require.resolve('./jasmine'),
233
  moduleNameMapper: {
234
    '\\.(css|less|sass|scss)$': require.resolve('identity-obj-proxy'),
235
    // Additional mappings from opts.moduleNameMapper
236
  },
237
  globals: {
238
    'ts-jest': {
239
      useBabelrc: true
240
    }
241
  }
242
  // User jest.config.js is merged if present
243
}
244
```