0
# Setup Environment
1

2
Functions for setting up Angular testing environments with proper TestBed configuration and zone handling for different Angular testing scenarios.
3

4
## Capabilities
5

6
### setupZoneTestEnv Function
7

8
Sets up Angular testing environment with Zone.js support for traditional Angular applications.
9

10
```typescript { .api }
11
/**
12
 * Sets up Angular testing environment with Zone.js support
13
 * @param options - Optional TestBed environment configuration options
14
 */
15
function setupZoneTestEnv(options?: TestEnvironmentOptions): void;
16

17
interface TestEnvironmentOptions {
18
  [key: string]: any;
19
}
20
```
21

22
**Path**: `'jest-preset-angular/setup-env/zone'`
23

24
**Usage Examples:**
25

26
```typescript
27
// setup-jest.ts
28
import 'jest-preset-angular/setup-env/zone';
29

30
// Or with custom options
31
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
32

33
// Basic setup (called automatically when importing)
34
// No manual call needed when using import statement
35

36
// Manual setup with options
37
setupZoneTestEnv({
38
  // Custom TestBed configuration options
39
});
40
```
41

42
**Configuration:**
43

44
```javascript
45
// jest.config.js
46
module.exports = {
47
  preset: 'jest-preset-angular',
48
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
49
};
50
```
51

52
**Features:**
53
- Automatically imports and configures Zone.js and Zone.js testing utilities
54
- Initializes Angular TestBed with BrowserDynamicTestingModule
55
- Sets up platformBrowserDynamicTesting platform
56
- Applies text encoding polyfills for Node.js environment
57
- Configures proper test environment options
58

59
### setupZonelessTestEnv Function
60

61
Sets up Angular testing environment for zoneless Angular applications (Angular 18+ experimental feature).
62

63
```typescript { .api }
64
/**
65
 * Sets up Angular testing environment without Zone.js for zoneless applications
66
 * @param options - Optional TestBed environment configuration options
67
 */
68
function setupZonelessTestEnv(options?: TestEnvironmentOptions): void;
69
```
70

71
**Path**: `'jest-preset-angular/setup-env/zoneless'`
72

73
**Usage Examples:**
74

75
```typescript
76
// setup-jest.ts for zoneless Angular app
77
import 'jest-preset-angular/setup-env/zoneless';
78

79
// Or with custom options
80
import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless';
81

82
// Manual setup with options
83
setupZonelessTestEnv({
84
  // Custom TestBed configuration options for zoneless environment
85
});
86
```
87

88
**Configuration:**
89

90
```javascript
91
// jest.config.js for zoneless Angular app
92
module.exports = {
93
  preset: 'jest-preset-angular',
94
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
95
};
96
```
97

98
**Features:**
99
- Skips Zone.js import and configuration 
100
- Initializes Angular TestBed for zoneless operation
101
- Sets up platformBrowserDynamicTesting without zone patches
102
- Applies text encoding polyfills for Node.js environment
103
- Optimized for Angular applications using zoneless change detection
104

105
### Environment Setup Utilities
106

107
Shared utilities used by both zone and zoneless setup functions.
108

109
```typescript { .api }
110
/**
111
 * Applies text encoding polyfills for Node.js environment compatibility
112
 */
113
function polyfillEncoder(): void;
114

115
/**
116
 * Resolves and validates test environment options
117
 * @param options - Raw test environment options
118
 * @returns Processed test environment options
119
 */
120
function resolveTestEnvOptions(options?: TestEnvironmentOptions): TestEnvironmentOptions;
121
```
122

123
**Internal Usage:**
124
These utilities are automatically called by the setup functions and typically don't need direct usage:
125

126
```typescript
127
// Used internally by setup functions
128
polyfillEncoder(); // Ensures TextEncoder/TextDecoder are available
129
const processedOptions = resolveTestEnvOptions(userOptions);
130
```
131

132
### Global Configuration
133

134
The setup environment functions support global configuration through the `ngJest` global variable.
135

136
```typescript { .api }
137
declare global {
138
  var ngJest: {
139
    skipNgcc?: boolean;
140
    tsconfig?: string;
141
    testEnvironmentOptions?: TestEnvironmentOptions;
142
  } | undefined;
143
}
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
// In test setup or jest configuration
150
globalThis.ngJest = {
151
  skipNgcc: true, // Skip Angular Ivy compilation cache
152
  tsconfig: '<rootDir>/tsconfig.spec.json',
153
  testEnvironmentOptions: {
154
    // Custom Angular TestBed options
155
  }
156
};
157
```
158

159
### Setup File Configuration
160

161
**Zone-based Applications (Default):**
162

163
```typescript
164
// setup-jest.ts
165
import 'jest-preset-angular/setup-env/zone';
166

167
// Jest will automatically call setupZoneTestEnv()
168
```
169

170
**Zoneless Applications:**
171

172
```typescript
173
// setup-jest.ts
174
import 'jest-preset-angular/setup-env/zoneless';
175

176
// Jest will automatically call setupZonelessTestEnv()
177
```
178

179
**Manual Setup with Options:**
180

181
```typescript
182
// setup-jest.ts
183
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
184

185
setupZoneTestEnv({
186
  // Custom TestBed configuration
187
});
188
```
189

190
### TestBed Integration
191

192
Both setup functions configure Angular's TestBed with appropriate modules and platforms:
193

194
**Zone Setup:**
195
- Imports `zone.js` and `zone.js/testing`
196
- Uses `BrowserDynamicTestingModule`
197
- Configures `platformBrowserDynamicTesting()` with zone support
198

199
**Zoneless Setup:**
200
- Skips zone.js imports
201
- Uses `BrowserDynamicTestingModule` without zone patches
202
- Configures `platformBrowserDynamicTesting()` for zoneless operation
203

204
### Environment Detection
205

206
The setup functions automatically handle Node.js environment compatibility:
207

208
```typescript
209
// Automatic polyfills applied:
210
// - TextEncoder/TextDecoder for Angular's text processing
211
// - Proper module resolution for Angular testing utilities
212
// - Browser API simulation through JSDOM integration
213
```
214

215
### Compatibility
216

217
**Supported Angular Versions:**
218
- Zone-based: Angular 18+, 19+, 20+
219
- Zoneless: Angular 18+ (experimental feature)
220

221
**Supported Node.js Versions:**
222
- Node.js 18.19.1+
223
- Node.js 20.11.1+
224
- Node.js 22.0.0+
225

226
### Common Setup Patterns
227

228
**Basic Zone-based Setup:**
229

230
```javascript
231
// jest.config.js
232
module.exports = {
233
  preset: 'jest-preset-angular',
234
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts']
235
};
236
```
237

238
```typescript
239
// setup-jest.ts
240
import 'jest-preset-angular/setup-env/zone';
241
```
242

243
**Advanced Configuration:**
244

245
```typescript
246
// setup-jest.ts
247
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
248

249
// Configure global settings
250
globalThis.ngJest = {
251
  testEnvironmentOptions: {
252
    // Custom TestBed options
253
  }
254
};
255

256
// Setup with custom options
257
setupZoneTestEnv({
258
  // Environment-specific options
259
});
260
```
261

262
### Error Handling
263

264
The setup functions include proper error handling and logging:
265

266
```typescript
267
// Setup functions will log warnings for:
268
// - Missing Angular dependencies
269
// - Incompatible zone configurations
270
// - Invalid test environment options
271
```
272

273
All setup is handled automatically when importing the respective modules, making it easy to configure Angular testing environments with minimal boilerplate code.