0
# Testing Utilities
1

2
Testing integration utilities for Jest configuration, alias resolution, and umi-specific testing setup.
3

4
## Capabilities
5

6
### Alias Configuration
7

8
Configure Jest with umi's alias system for proper module resolution in tests.
9

10
```typescript { .api }
11
/**
12
 * Configure Jest with umi alias mappings for proper module resolution
13
 * @param config - Jest configuration object to modify
14
 * @returns Promise resolving to the modified Jest configuration
15
 */
16
function configUmiAlias(config: Config.InitialOptions): Promise<Config.InitialOptions>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { configUmiAlias } from "umi/test";
23

24
// Basic Jest configuration with umi aliases
25
const jestConfig = await configUmiAlias({
26
  testEnvironment: "jsdom",
27
  setupFilesAfterEnv: ["<rootDir>/src/setupTests.ts"],
28
});
29

30
// Advanced configuration
31
const jestConfig = await configUmiAlias({
32
  testEnvironment: "jsdom",
33
  moduleNameMapper: {
34
    // These will be merged with umi's alias mappings
35
    "\\.(css|less|scss)$": "identity-obj-proxy",
36
  },
37
  transform: {
38
    "^.+\\.(ts|tsx)$": "ts-jest",
39
  },
40
  setupFilesAfterEnv: ["<rootDir>/src/setupTests.ts"],
41
  testMatch: [
42
    "<rootDir>/src/**/__tests__/**/*.(ts|js|tsx|jsx)",
43
    "<rootDir>/src/**/?(*.)(spec|test).(ts|js|tsx|jsx)",
44
  ],
45
});
46

47
export default jestConfig;
48
```
49

50
### Alias Resolution
51

52
Get and resolve umi's alias configuration for manual module resolution.
53

54
```typescript { .api }
55
/**
56
 * Get the current umi alias configuration
57
 * @returns Promise resolving to alias mapping object
58
 */
59
function getUmiAlias(): Promise<Record<string, string>>;
60

61
/**
62
 * Resolve alias path with recursive resolution support
63
 * @param alias - Alias mapping object
64
 * @param key - Key to resolve
65
 * @returns Resolved absolute path
66
 */
67
function getAliasPathWithKey(
68
  alias: Record<string, string>, 
69
  key: string
70
): string;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import { getUmiAlias, getAliasPathWithKey } from "umi/test";
77

78
// Get current alias configuration
79
const aliases = await getUmiAlias();
80
console.log(aliases);
81
// Output: { "@": "/project/src", "@@": "/project/.umi", ... }
82

83
// Resolve specific alias
84
const srcPath = getAliasPathWithKey(aliases, "@/components/Button");
85
console.log(srcPath); // "/project/src/components/Button"
86

87
// Handle nested aliases
88
const aliases = {
89
  "@": "/project/src",
90
  "components": "@/components",
91
};
92
const resolved = getAliasPathWithKey(aliases, "components/Button");
93
console.log(resolved); // "/project/src/components/Button"
94
```
95

96
### Testing Setup
97

98
Access to all utilities from @umijs/test package for comprehensive testing support.
99

100
```typescript { .api }
101
// All exports from @umijs/test are available
102
// Including Jest configuration, test utilities, and matchers
103
```
104

105
**Common Testing Patterns:**
106

107
```typescript
108
import { configUmiAlias } from "umi/test";
109
import type { Config } from "@jest/types";
110

111
// Jest configuration file (jest.config.ts)
112
const config: Config.InitialOptions = {
113
  testEnvironment: "jsdom",
114
  setupFilesAfterEnv: ["<rootDir>/src/setupTests.ts"],
115
  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json"],
116
  transform: {
117
    "^.+\\.(ts|tsx)$": ["ts-jest", {
118
      tsconfig: "tsconfig.json",
119
    }],
120
  },
121
  moduleNameMapper: {
122
    "\\.(css|less|scss|sass)$": "identity-obj-proxy",
123
    "\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$": "jest-transform-stub",
124
  },
125
  collectCoverageFrom: [
126
    "src/**/*.{ts,tsx}",
127
    "!src/**/*.d.ts",
128
    "!src/setupTests.ts",
129
  ],
130
  testMatch: [
131
    "<rootDir>/src/**/__tests__/**/*.(ts|js|tsx|jsx)",
132
    "<rootDir>/src/**/?(*.)(spec|test).(ts|js|tsx|jsx)",
133
  ],
134
};
135

136
export default configUmiAlias(config);
137
```
138

139
## Alias Resolution Algorithm
140

141
The alias resolution follows a recursive pattern:
142

143
1. **Direct Match**: If the key exists directly in the alias mapping, use its value
144
2. **Recursive Resolution**: If the alias value is itself an alias, resolve recursively
145
3. **Prefix Match**: For keys like `@/components/Button`, find aliases that match the prefix
146
4. **Path Substitution**: Replace the matched prefix with its resolved path
147

148
```typescript
149
// Example resolution process
150
const aliases = {
151
  "@": "/project/src",
152
  "components": "@/components", // Points to another alias
153
  "utils": "/project/src/utils",
154
};
155

156
// Resolving "components/Button"
157
// 1. Find prefix match: "components" -> "@/components"
158
// 2. Recursive resolve: "@/components" -> "/project/src/components"  
159
// 3. Substitute: "components/Button" -> "/project/src/components/Button"
160
```
161

162
## Testing Utilities Integration
163

164
The testing utilities integrate with:
165

166
- **Jest Configuration**: Automatic moduleNameMapper generation
167
- **TypeScript**: Full type support for test files
168
- **Path Resolution**: Seamless import resolution in tests
169
- **Umi Service**: Access to umi's internal configuration
170

171
```typescript
172
// Test file example using umi aliases
173
import { render, screen } from "@testing-library/react";
174
import Button from "@/components/Button"; // Resolved via umi alias
175
import { formatDate } from "@/utils/date"; // Also resolved via alias
176
import { mockUser } from "@@/test-fixtures"; // Umi internal alias
177

178
describe("Button Component", () => {
179
  test("renders correctly", () => {
180
    render(<Button>Click me</Button>);
181
    expect(screen.getByRole("button")).toBeInTheDocument();
182
  });
183

184
  test("formats date correctly", () => {
185
    const date = new Date("2023-01-01");
186
    expect(formatDate(date)).toBe("2023-01-01");
187
  });
188
});
189
```
190

191
## Type Definitions
192

193
```typescript { .api }
194
// Jest configuration type (from @jest/types)
195
interface Config.InitialOptions {
196
  testEnvironment?: string;
197
  moduleNameMapper?: Record<string, string>;
198
  transform?: Record<string, string | [string, any]>;
199
  setupFilesAfterEnv?: string[];
200
  testMatch?: string[];
201
  collectCoverageFrom?: string[];
202
  [key: string]: any;
203
}
204

205
// Alias mapping type
206
type AliasMapping = Record<string, string>;
207
```