0
# Jest Preset Angular
1

2
Jest Preset Angular is a comprehensive Jest preset configuration specifically designed for Angular projects, enabling developers to efficiently set up and run unit tests in Angular applications. It provides seamless integration with TypeScript, Angular-specific transformations, and optimized test configurations that handle Angular's unique compilation and module loading requirements.
3

4
## Package Information
5

6
- **Package Name**: jest-preset-angular
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev jest-preset-angular`
10

11
## Core Imports
12

13
```typescript
14
import { createCjsPreset, createEsmPreset } from 'jest-preset-angular/presets';
15
```
16

17
For the transformer:
18

19
```typescript
20
import jestPresetAngular from 'jest-preset-angular';
21
const transformer = jestPresetAngular.createTransformer();
22
```
23

24
For CommonJS (jest.config.js):
25

26
```javascript
27
const { createCjsPreset } = require('jest-preset-angular/presets');
28
```
29

30
## Basic Usage
31

32
### Simple CJS Configuration
33

34
```javascript
35
// jest.config.js
36
const { createCjsPreset } = require('jest-preset-angular/presets');
37

38
module.exports = createCjsPreset({
39
  tsconfig: '<rootDir>/tsconfig.spec.json'
40
});
41
```
42

43
### Simple ESM Configuration
44

45
```javascript
46
// jest.config.mjs
47
import { createEsmPreset } from 'jest-preset-angular/presets';
48

49
export default createEsmPreset({
50
  tsconfig: '<rootDir>/tsconfig.spec.json'
51
});
52
```
53

54
### Traditional Preset Usage
55

56
```javascript
57
// jest.config.js
58
module.exports = {
59
  preset: 'jest-preset-angular',
60
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
61
};
62
```
63

64
## Architecture
65

66
Jest Preset Angular is built around several key components:
67

68
- **Preset Factories**: Functions (`createCjsPreset`, `createEsmPreset`) that generate complete Jest configurations for different module systems
69
- **Custom Transformer**: `NgJestTransformer` class that extends ts-jest to handle Angular-specific compilation needs
70
- **Angular Compiler Integration**: `NgJestCompiler` that processes Angular decorators, templates, and styles
71
- **Configuration Management**: `NgJestConfig` that handles Angular-specific TypeScript and Jest settings
72
- **Snapshot Serializers**: Built-in serializers for clean Angular component snapshots
73
- **Custom Environment**: JSDOM environment optimized for Angular testing
74

75
## Capabilities
76

77
### Jest Preset Configuration
78

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

81
```typescript { .api }
82
function createCjsPreset(options?: CjsPresetOptionsType): CjsPresetType;
83
function createEsmPreset(options?: EsmPresetOptionsType): EsmPresetType;
84

85
interface CjsPresetOptionsType {
86
  tsconfig?: TsJestTransformerOptions['tsconfig'];
87
  astTransformers?: TsJestTransformerOptions['astTransformers'];
88
  babelConfig?: TsJestTransformerOptions['babelConfig'];
89
  diagnostics?: TsJestTransformerOptions['diagnostics'];
90
  testEnvironment?: JSDOMEnvironment;
91
}
92

93
interface EsmPresetOptionsType {
94
  tsconfig?: TsJestTransformerOptions['tsconfig'];
95
  astTransformers?: TsJestTransformerOptions['astTransformers'];
96
  babelConfig?: TsJestTransformerOptions['babelConfig'];
97
  diagnostics?: TsJestTransformerOptions['diagnostics'];
98
  testEnvironment?: JSDOMEnvironment;
99
}
100

101
type JSDOMEnvironment = 'jsdom' | 'jest-preset-angular/environments/jest-jsdom-env';
102
```
103

104
[Preset Configuration](./preset-configuration.md)
105

106
### Angular Transformer
107

108
Custom Jest transformer that handles Angular-specific compilation including component templates, styles, decorators, and TypeScript compilation with Angular compiler integration.
109

110
```typescript { .api }
111
class NgJestTransformer extends TsJestTransformer {
112
  constructor(tsJestConfig?: TsJestTransformerOptions);
113
  process(
114
    fileContent: string,
115
    filePath: string,
116
    transformOptions: TsJestTransformOptions
117
  ): TransformedSource;
118
}
119

120
function createTransformer(tsJestConfig?: TsJestTransformerOptions): NgJestTransformer;
121
```
122

123
[Angular Transformer](./angular-transformer.md)
124

125
### Test Environment
126

127
Custom JSDOM environment optimized for Angular testing with proper global setup and Angular-specific configurations.
128

129
```typescript { .api }
130
class JestJSDOMEnvironment extends BaseEnv {
131
  constructor(config: JestEnvironmentConfig, context: EnvironmentContext);
132
}
133
```
134

135
[Test Environment](./test-environment.md)
136

137
### Test Environment Setup
138

139
Functions for setting up Angular testing environments with proper TestBed configuration and zone handling.
140

141
```typescript { .api }
142
function setupZoneTestEnv(options?: TestEnvironmentOptions): void;
143
function setupZonelessTestEnv(options?: TestEnvironmentOptions): void;
144
```
145

146
[Setup Environment](./setup-environment.md)
147

148
### Snapshot Serializers
149

150
Built-in snapshot serializers for clean, readable Angular component test snapshots with Angular-specific attribute handling.
151

152
```typescript { .api }
153
interface NgSnapshotOptions {
154
  omitAllCompAttrs?: boolean;
155
}
156
```
157

158
[Snapshot Serializers](./snapshot-serializers.md)
159

160
## Types
161

162
```typescript { .api }
163
interface TsJestTransformOptions {
164
  config?: {
165
    [key: string]: any;
166
    globals?: {
167
      ngJest?: NgJestGlobalConfig;
168
    };
169
  };
170
  supportsStaticESM?: boolean;
171
}
172

173
interface NgJestGlobalConfig {
174
  skipNgcc?: boolean;
175
  tsconfig?: string;
176
  testEnvironmentOptions?: TestEnvironmentOptions;
177
  processWithEsbuild?: string[];
178
}
179

180
interface TestEnvironmentOptions {
181
  [key: string]: any;
182
}
183

184
interface TransformedSource {
185
  code: string;
186
  map?: string | object;
187
}
188

189
interface SnapshotSerializer {
190
  serialize(val: any, config: any, indentation: string, depth: number, refs: any, printer: any): string;
191
  test(val: any): boolean;
192
}
193

194
type TsJestTransformerOptions = {
195
  tsconfig?: string | object;
196
  astTransformers?: object;
197
  babelConfig?: object;
198
  diagnostics?: object;
199
  isolatedModules?: boolean;
200
  stringifyContentPathRegex?: string;
201
  useESM?: boolean;
202
};
203

204
type CjsPresetType = Config & {
205
  transformIgnorePatterns: string[];
206
  transform: Record<string, any>;
207
};
208

209
type EsmPresetType = Config & {
210
  extensionsToTreatAsEsm: string[];
211
  moduleNameMapper: Record<string, string>;
212
  transformIgnorePatterns: string[];
213
  transform: Record<string, any>;
214
};
215

216
interface Config {
217
  testEnvironment?: string;
218
  moduleFileExtensions?: string[];
219
  snapshotSerializers?: string[];
220
  preset?: string;
221
  setupFilesAfterEnv?: string[];
222
}
223

224
interface BaseEnv {
225
  constructor(config: JestEnvironmentConfig, context: EnvironmentContext, jsdom: any);
226
  global: any;
227
  moduleMocker: any;
228
  fakeTimers: any;
229
  setup(): Promise<void>;
230
  teardown(): Promise<void>;
231
  runScript(script: any): any;
232
}
233

234
interface JestEnvironmentConfig {
235
  projectConfig: any;
236
  globalConfig: any;
237
}
238

239
interface EnvironmentContext {
240
  console: Console;
241
  docblockPragmas: Record<string, string | string[]>;
242
  testPath: string;
243
}
244

245
interface TsJestTransformer {
246
  constructor(tsJestConfig?: TsJestTransformerOptions);
247
  process(fileContent: string, filePath: string, transformOptions: TsJestTransformOptions): TransformedSource;
248
  getCacheKey(fileContent: string, filePath: string, transformOptions: TsJestTransformOptions): string;
249
}
250
```