0
# Jest Preset Configuration
1

2
Core preset creation functions that generate complete Jest configurations optimized for Angular projects with different module systems and environments.
3

4
## Capabilities
5

6
### createCjsPreset Function
7

8
Creates a Jest preset configuration optimized for CommonJS module system with Angular-specific transformations and settings.
9

10
```typescript { .api }
11
/**
12
 * Creates a Jest preset configuration for CommonJS modules
13
 * @param options - Optional configuration options for the preset
14
 * @returns Complete Jest configuration object for CommonJS projects
15
 */
16
function createCjsPreset(options?: CjsPresetOptionsType): CjsPresetType;
17

18
interface CjsPresetOptionsType {
19
  /** TypeScript configuration file path or options */
20
  tsconfig?: TsJestTransformerOptions['tsconfig'];
21
  /** AST transformers for custom TypeScript transformations */
22
  astTransformers?: TsJestTransformerOptions['astTransformers'];
23
  /** Babel configuration for additional transformations */
24
  babelConfig?: TsJestTransformerOptions['babelConfig'];
25
  /** TypeScript diagnostic options */
26
  diagnostics?: TsJestTransformerOptions['diagnostics'];
27
  /** Test environment configuration */
28
  testEnvironment?: JSDOMEnvironment;
29
}
30

31
type CjsPresetType = BasePresetConfig & Required<Pick<Config, 'transformIgnorePatterns' | 'transform'>>;
32
```
33

34
**Usage Examples:**
35

36
```javascript
37
const { createCjsPreset } = require('jest-preset-angular/presets');
38

39
// Basic configuration
40
module.exports = createCjsPreset();
41

42
// With custom tsconfig
43
module.exports = createCjsPreset({
44
  tsconfig: '<rootDir>/tsconfig.spec.json'
45
});
46

47
// With custom environment
48
module.exports = createCjsPreset({
49
  testEnvironment: 'jest-preset-angular/environments/jest-jsdom-env'
50
});
51

52
// Full configuration
53
module.exports = createCjsPreset({
54
  tsconfig: {
55
    tsconfig: '<rootDir>/tsconfig.spec.json',
56
    isolatedModules: true
57
  },
58
  diagnostics: {
59
    warnOnly: true
60
  },
61
  testEnvironment: 'jsdom'
62
});
63
```
64

65
### createEsmPreset Function
66

67
Creates a Jest preset configuration optimized for ECMAScript modules with Angular-specific transformations and ESM support.
68

69
```typescript { .api }
70
/**
71
 * Creates a Jest preset configuration for ECMAScript modules
72
 * @param options - Optional configuration options for the preset
73
 * @returns Complete Jest configuration object for ESM projects
74
 */
75
function createEsmPreset(options?: EsmPresetOptionsType): EsmPresetType;
76

77
interface EsmPresetOptionsType {
78
  /** TypeScript configuration file path or options */
79
  tsconfig?: TsJestTransformerOptions['tsconfig'];
80
  /** AST transformers for custom TypeScript transformations */
81
  astTransformers?: TsJestTransformerOptions['astTransformers'];
82
  /** Babel configuration for additional transformations */
83
  babelConfig?: TsJestTransformerOptions['babelConfig'];
84
  /** TypeScript diagnostic options */
85
  diagnostics?: TsJestTransformerOptions['diagnostics'];
86
  /** Test environment configuration */
87
  testEnvironment?: JSDOMEnvironment;
88
}
89

90
type EsmPresetType = BasePresetConfig & 
91
  Required<Pick<Config, 'extensionsToTreatAsEsm' | 'moduleNameMapper' | 'transformIgnorePatterns' | 'transform'>>;
92
```
93

94
**Usage Examples:**
95

96
```javascript
97
// jest.config.mjs
98
import { createEsmPreset } from 'jest-preset-angular/presets';
99

100
// Basic ESM configuration
101
export default createEsmPreset();
102

103
// With custom options
104
export default createEsmPreset({
105
  tsconfig: '<rootDir>/tsconfig.spec.json',
106
  testEnvironment: 'jest-preset-angular/environments/jest-jsdom-env'
107
});
108
```
109

110
### Base Preset Configuration
111

112
Shared configuration object used by both CJS and ESM presets.
113

114
```typescript { .api }
115
interface BasePresetConfig {
116
  testEnvironment: JSDOMEnvironment;
117
  moduleFileExtensions: Config['moduleFileExtensions'];
118
  snapshotSerializers: Config['snapshotSerializers'];
119
}
120

121
const basePresetConfig: BasePresetConfig = {
122
  testEnvironment: 'jsdom',
123
  moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'],
124
  snapshotSerializers: [
125
    'jest-preset-angular/build/serializers/html-comment',
126
    'jest-preset-angular/build/serializers/ng-snapshot',
127
    'jest-preset-angular/build/serializers/no-ng-attributes'
128
  ]
129
};
130

131
interface Config {
132
  testEnvironment?: string;
133
  moduleFileExtensions?: string[];
134
  snapshotSerializers?: string[];
135
  transformIgnorePatterns?: string[];
136
  transform?: Record<string, any>;
137
  extensionsToTreatAsEsm?: string[];
138
  moduleNameMapper?: Record<string, string>;
139
}
140
```
141

142
### Environment Types
143

144
Available test environment options for Angular testing.
145

146
```typescript { .api }
147
type JSDOMEnvironment = 'jsdom' | 'jest-preset-angular/environments/jest-jsdom-env';
148
```
149

150
The preset supports two JSDOM environments:
151
- `'jsdom'`: Standard Jest JSDOM environment
152
- `'jest-preset-angular/environments/jest-jsdom-env'`: Custom Angular-optimized JSDOM environment
153

154
### Configuration Differences
155

156
**CommonJS Preset Features:**
157
- Transform ignore patterns: `['node_modules/(?!(.*\\.mjs$|@angular/common/locales/.*\\.js$))']`
158
- Standard transform configuration for TypeScript, JavaScript, HTML, and SVG files
159

160
**ESM Preset Features:**
161
- Extensions treated as ESM: `['.ts']`
162
- Module name mapper for tslib: `{ tslib: 'tslib/tslib.es6.js' }`
163
- Transform ignore patterns: `['node_modules/(?!tslib)']`
164
- ESM-specific transform configuration with `useESM: true`
165

166
### Traditional Preset Usage
167

168
Alternative configuration method using Jest's built-in preset system for simpler setup.
169

170
```typescript { .api }
171
/**
172
 * Traditional Jest preset configuration
173
 * Uses the default CJS preset with standard Jest configuration
174
 */
175
interface TraditionalPresetConfig {
176
  preset: 'jest-preset-angular';
177
  setupFilesAfterEnv?: string[];
178
  testEnvironment?: string;
179
}
180
```
181

182
**Usage Examples:**
183

184
```javascript
185
// jest.config.js - Traditional preset approach
186
module.exports = {
187
  preset: 'jest-preset-angular',
188
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
189
};
190

191
// With custom test environment
192
module.exports = {
193
  preset: 'jest-preset-angular',
194
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
195
  testEnvironment: 'jest-preset-angular/environments/jest-jsdom-env'
196
};
197

198
// With additional Jest options
199
module.exports = {
200
  preset: 'jest-preset-angular',
201
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
202
  collectCoverageFrom: [
203
    'src/**/*.{ts,js}',
204
    '!src/**/*.spec.ts',
205
    '!src/main.ts',
206
    '!src/polyfills.ts'
207
  ],
208
  coverageDirectory: 'coverage',
209
  coverageReporters: ['html', 'text-summary', 'cobertura']
210
};
211
```
212

213
**Traditional vs Factory Function Approach:**
214

215
```javascript
216
// Traditional preset (uses default CJS configuration)
217
module.exports = {
218
  preset: 'jest-preset-angular',
219
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
220
};
221

222
// Factory function approach (more control)
223
const { createCjsPreset } = require('jest-preset-angular/presets');
224

225
module.exports = createCjsPreset({
226
  tsconfig: '<rootDir>/tsconfig.spec.json',
227
  diagnostics: {
228
    warnOnly: true
229
  }
230
});
231
```
232

233
**Benefits of Traditional Preset:**
234
- Simpler configuration for basic use cases
235
- Familiar Jest preset syntax
236
- Automatically applies default Angular testing configuration
237
- Compatible with standard Jest tooling and IDE integrations
238

239
**Benefits of Factory Functions:**
240
- More granular control over configuration
241
- Explicit ESM vs CJS module system selection
242
- Customizable TypeScript and diagnostic options
243
- Better for complex or non-standard setups
244

245
### Setup File Integration
246

247
Both traditional and factory function approaches require setup files for Angular TestBed initialization:
248

249
```typescript
250
// setup-jest.ts (for zone-based apps)
251
import 'jest-preset-angular/setup-env/zone';
252

253
// setup-jest.ts (for zoneless apps)
254
import 'jest-preset-angular/setup-env/zoneless';
255
```
256

257
**Configuration:**
258

259
```javascript
260
// Both approaches use setupFilesAfterEnv
261
module.exports = {
262
  preset: 'jest-preset-angular',
263
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
264
};
265

266
// Or with factory function
267
const config = createCjsPreset();
268
config.setupFilesAfterEnv = ['<rootDir>/setup-jest.ts'];
269
module.exports = config;
270
```