Skip to content

Commit 21c0238

Browse files
ahnpnlahnpnl
committedNov 15, 2024
feat: add new setup test env functions
Closes #354 Closes #2755
·
v15.0.0-next.0v14.3.0
1 parent 8a8820e commit 21c0238

30 files changed

+437
-58
lines changed
 

‎.eslintignore

+1
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ src/config/setup-jest.ts
66
coverage
77
src/transformers/jit_transform.js
88
index.html
9+
*.mjs

‎.eslintrc.js

+2-1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ const baseJsTsConfig = {
99
parser: '@typescript-eslint/parser',
1010
parserOptions: {
1111
project: 'tsconfig.eslint.json',
12+
sourceType: 'module',
1213
},
1314
rules: {
1415
'@typescript-eslint/no-empty-function': 'error',
@@ -71,7 +72,7 @@ module.exports = {
7172
overrides: [
7273
{
7374
...baseJsTsConfig,
74-
files: ['*.ts', '*.js'],
75+
files: ['*.ts', '*.js', '*.mts'],
7576
extends: [
7677
'plugin:@angular-eslint/recommended',
7778
'plugin:@angular-eslint/template/process-inline-templates',

‎examples/example-app-monorepo/apps/app1/setup-jest-esm.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest.mjs';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-monorepo/apps/app1/setup-jest.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-monorepo/libs/user/setup-jest-esm.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest.mjs';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-monorepo/libs/user/setup-jest.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-v16/setup-jest-esm.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest.mjs';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-v16/setup-jest.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-v17/setup-jest-esm.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest.mjs';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-v17/setup-jest.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-v18/setup-jest-esm.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest.mjs';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-v18/setup-jest.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-yarn-workspace/packages/angular-app/setup-jest-esm.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest.mjs';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-yarn-workspace/packages/angular-app/setup-jest.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-yarn-workspace/packages/user/setup-jest-esm.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest.mjs';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎examples/example-app-yarn-workspace/packages/user/setup-jest.ts

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1-
import 'jest-preset-angular/setup-jest';
1+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
22
import './jest-global-mocks';
3+
4+
setupZoneTestEnv();

‎scripts/test-examples.js

+1
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ const executeTest = (projectPath) => {
4343
'package.json',
4444
'setup-jest.js',
4545
'setup-jest.mjs',
46+
'setup-env',
4647
].forEach((asset) => {
4748
const assetToReplace = join(projectPath, 'node_modules', 'jest-preset-angular', asset);
4849
const assetToCopy = join(rootDir, asset);

‎setup-env/utils.mjs

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
import { TextDecoder, TextEncoder } from 'util';
2+
3+
export const polyfillEncoder = () => {
4+
if (typeof globalThis.TextEncoder === 'undefined') {
5+
globalThis.TextEncoder = TextEncoder;
6+
globalThis.TextDecoder = TextDecoder;
7+
}
8+
};
9+
10+
export const resolveTestEnvOptions = (options) => {
11+
const globalTestEnvOptions = globalThis.ngJest?.testEnvironmentOptions;
12+
if (globalTestEnvOptions) {
13+
console.warn(
14+
'Setting testEnvironmentOptions via globalThis.ngJest is deprecated. Please provide testEnvironmentOptions via function argument',
15+
);
16+
}
17+
18+
return globalTestEnvOptions ?? options;
19+
};

‎setup-env/zone/index.d.mts

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
import type { TestEnvironmentOptions } from '@angular/core/testing';
2+
3+
export declare const setupZoneTestEnv: (options?: TestEnvironmentOptions) => void;

‎setup-env/zone/index.d.ts

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
import type { TestEnvironmentOptions } from '@angular/core/testing';
2+
3+
declare const _default: {
4+
setupZoneTestEnv: (options?: TestEnvironmentOptions) => void;
5+
};
6+
export = _default;

‎setup-env/zone/index.js

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
require('zone.js');
2+
require('zone.js/testing');
3+
4+
const { TextEncoder, TextDecoder } = require('util');
5+
6+
const { getTestBed } = require('@angular/core/testing');
7+
const {
8+
BrowserDynamicTestingModule,
9+
platformBrowserDynamicTesting,
10+
} = require('@angular/platform-browser-dynamic/testing');
11+
12+
const polyfillEncoder = () => {
13+
if (typeof globalThis.TextEncoder === 'undefined') {
14+
globalThis.TextEncoder = TextEncoder;
15+
globalThis.TextDecoder = TextDecoder;
16+
}
17+
};
18+
19+
const resolveTestEnvOptions = (options) => {
20+
const globalTestEnvOptions = globalThis.ngJest?.testEnvironmentOptions;
21+
if (globalTestEnvOptions) {
22+
console.warn(
23+
'Setting testEnvironmentOptions via globalThis.ngJest is deprecated. Please provide testEnvironmentOptions via function argument',
24+
);
25+
}
26+
27+
return globalTestEnvOptions ?? options;
28+
};
29+
30+
const setupZoneTestEnv = (options) => {
31+
polyfillEncoder();
32+
const testEnvironmentOptions = resolveTestEnvOptions(options);
33+
34+
getTestBed().initTestEnvironment(
35+
BrowserDynamicTestingModule,
36+
platformBrowserDynamicTesting(),
37+
testEnvironmentOptions,
38+
);
39+
};
40+
41+
module.exports = {
42+
setupZoneTestEnv,
43+
};

‎setup-env/zone/index.mjs

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import 'zone.js';
2+
import 'zone.js/testing';
3+
4+
import { getTestBed } from '@angular/core/testing';
5+
import { BrowserDynamicTestingModule, platformBrowserDynamicTesting } from '@angular/platform-browser-dynamic/testing';
6+
7+
import { polyfillEncoder, resolveTestEnvOptions } from '../utils.mjs';
8+
9+
export const setupZoneTestEnv = (options) => {
10+
polyfillEncoder();
11+
const testEnvironmentOptions = resolveTestEnvOptions(options);
12+
13+
getTestBed().initTestEnvironment(
14+
BrowserDynamicTestingModule,
15+
platformBrowserDynamicTesting(),
16+
testEnvironmentOptions,
17+
);
18+
};

‎setup-env/zoneless/index.d.mts

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
import type { TestEnvironmentOptions } from '@angular/core/testing';
2+
3+
export declare const setupZonelessTestEnv: (options?: TestEnvironmentOptions) => void;

‎setup-env/zoneless/index.d.ts

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
import type { TestEnvironmentOptions } from '@angular/core/testing';
2+
3+
declare const _default: {
4+
setupZonelessTestEnv: (options?: TestEnvironmentOptions) => void;
5+
};
6+
export = _default;

‎setup-env/zoneless/index.js

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// eslint-disable-next-line @typescript-eslint/no-unused-vars
2+
const setupZonelessTestEnv = (_options) => {
3+
throw Error(
4+
'Zoneless testing environment only works when running Jest in ESM mode with Jest 29. ' +
5+
'Jest 30+ will support to work with CommonJS mode.',
6+
);
7+
};
8+
9+
module.exports = {
10+
setupZonelessTestEnv,
11+
};

‎setup-env/zoneless/index.mjs

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import { ErrorHandler, NgModule, provideExperimentalZonelessChangeDetection } from '@angular/core';
2+
import { getTestBed } from '@angular/core/testing';
3+
import { BrowserDynamicTestingModule, platformBrowserDynamicTesting } from '@angular/platform-browser-dynamic/testing';
4+
5+
import { polyfillEncoder, resolveTestEnvOptions } from '../utils.mjs';
6+
7+
export const setupZonelessTestEnv = (options) => {
8+
if (typeof provideExperimentalZonelessChangeDetection !== 'undefined') {
9+
polyfillEncoder();
10+
const testEnvironmentOptions = resolveTestEnvOptions(options);
11+
@NgModule({
12+
providers: [
13+
provideExperimentalZonelessChangeDetection(),
14+
{
15+
provide: ErrorHandler,
16+
useValue: {
17+
handleError: (e) => {
18+
throw e;
19+
},
20+
},
21+
},
22+
],
23+
})
24+
export class TestModule {}
25+
26+
getTestBed().initTestEnvironment(
27+
[BrowserDynamicTestingModule, TestModule],
28+
platformBrowserDynamicTesting(),
29+
testEnvironmentOptions,
30+
);
31+
32+
return;
33+
}
34+
35+
throw Error(
36+
'Cannot find provideExperimentalZonelessChangeDetection() to setup zoneless testing environment. ' +
37+
'Please use setupZoneTestEnv() from jest-preset-angular/setup-env/setup-zone-env.mjs instead.',
38+
);
39+
};

‎src/config/setup-jest.spec.ts

+66
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,39 @@ describe('setup-jest', () => {
8585

8686
expect(globalThis.TextEncoder).toBeDefined();
8787
});
88+
89+
it('should call getTestBed() and initTestEnvironment() with the testEnvironmentOptions passed as argument with setupZoneTestEnv()', async () => {
90+
const { setupZoneTestEnv } = await import('../../setup-env/zone/index.js');
91+
92+
setupZoneTestEnv({
93+
teardown: {
94+
destroyAfterEach: false,
95+
rethrowErrors: true,
96+
},
97+
errorOnUnknownElements: true,
98+
errorOnUnknownProperties: true,
99+
});
100+
101+
expect(mockZoneJs).toHaveBeenCalled();
102+
expect(mockZoneJsTesting).toHaveBeenCalled();
103+
assertOnInitTestEnv();
104+
expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
105+
teardown: {
106+
destroyAfterEach: false,
107+
rethrowErrors: true,
108+
},
109+
errorOnUnknownElements: true,
110+
errorOnUnknownProperties: true,
111+
});
112+
});
113+
114+
it('should always have TextEncoder in globalThis with setupZoneTestEnv()', async () => {
115+
const { setupZoneTestEnv } = await import('../../setup-env/zone/index.js');
116+
117+
setupZoneTestEnv();
118+
119+
expect(globalThis.TextEncoder).toBeDefined();
120+
});
88121
});
89122

90123
describe('for ESM setup-jest, test environment initialization', () => {
@@ -120,5 +153,38 @@ describe('setup-jest', () => {
120153

121154
expect(globalThis.TextEncoder).toBeDefined();
122155
});
156+
157+
it('should call getTestBed() and initTestEnvironment() with the testEnvironmentOptions passed as argument with setupZoneTestEnv()', async () => {
158+
const { setupZoneTestEnv } = await import('../../setup-env/zone/index.mjs');
159+
160+
setupZoneTestEnv({
161+
teardown: {
162+
destroyAfterEach: false,
163+
rethrowErrors: true,
164+
},
165+
errorOnUnknownElements: true,
166+
errorOnUnknownProperties: true,
167+
});
168+
169+
expect(mockZoneJs).toHaveBeenCalled();
170+
expect(mockZoneJsTesting).toHaveBeenCalled();
171+
assertOnInitTestEnv();
172+
expect(mockInitTestEnvironment.mock.calls[0][2]).toEqual({
173+
teardown: {
174+
destroyAfterEach: false,
175+
rethrowErrors: true,
176+
},
177+
errorOnUnknownElements: true,
178+
errorOnUnknownProperties: true,
179+
});
180+
});
181+
182+
it('should always have TextEncoder in globalThis with setupZoneTestEnv()', async () => {
183+
const { setupZoneTestEnv } = await import('../../setup-env/zone/index.mjs');
184+
185+
setupZoneTestEnv();
186+
187+
expect(globalThis.TextEncoder).toBeDefined();
188+
});
123189
});
124190
});

‎website/docs/getting-started/installation.md

+63-17
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ id: installation
33
title: Installation
44
---
55

6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
69
### Dependencies
710

811
You can install `jest-preset-angular` and dependencies all at once with one of the following commands.
@@ -19,27 +22,38 @@ Angular doesn't support native `async/await` in testing with `target` higher tha
1922

2023
:::
2124

22-
In your project root, create `setup-jest.ts` file with following contents:
25+
In your project root, create a setup file with following contents:
2326

24-
```ts
27+
```ts tab={"label":"TypeScript CJS"}
2528
// setup-jest.ts
26-
import 'jest-preset-angular/setup-jest';
29+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
30+
31+
setupZoneTestEnv();
2732
```
2833

29-
Add the following section:
34+
```ts tab={"label":"TypeScript ESM"}
35+
// setup-jest.ts
36+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone.mjs';
37+
38+
setupZoneTestEnv();
39+
```
3040

31-
- to your root Jest config
41+
Add the following section to your root Jest config
3242

33-
```js tab
34-
// jest.config.js
35-
module.exports = {
43+
```ts tab={"label":"TypeScript CJS"}
44+
// jest.config.ts
45+
import type { Config } from 'jest';
46+
47+
const jestConfig: Config = {
3648
preset: 'jest-preset-angular',
3749
setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
3850
};
51+
52+
export default jestConfig;
3953
```
4054

41-
```ts tab
42-
// jest.config.ts
55+
```ts tab={"label":"TypeScript ESM"}
56+
// jest.config.mts
4357
import type { Config } from 'jest';
4458

4559
const jestConfig: Config = {
@@ -52,26 +66,47 @@ export default jestConfig;
5266

5367
Adjust your `tsconfig.spec.json` to be:
5468

55-
```json
69+
```json5 tab={"label": "Tsconfig CJS"}
70+
// tsconfig.spec.json
5671
{
72+
//...
73+
extends: './tsconfig.json',
74+
compilerOptions: {
75+
//...
76+
module: 'CommonJS',
77+
types: ['jest'],
78+
},
79+
include: ['src/**/*.spec.ts', 'src/**/*.d.ts'],
80+
//...
81+
}
82+
```
83+
84+
```json tab={"label": "Tsconfig ESM"}
85+
// tsconfig.spec.json
86+
{
87+
//...
5788
"extends": "./tsconfig.json",
5889
"compilerOptions": {
59-
"outDir": "./out-tsc/spec",
60-
"module": "CommonJs",
90+
//...
91+
"module": "ES2022",
6192
"types": ["jest"]
6293
},
6394
"include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
95+
//...
6496
}
6597
```
6698

6799
Adjust `scripts` part your `package.json` to use `jest` instead of `ng`, e.g.
68100

69101
```json
102+
// package.json
70103
{
104+
//...
71105
"scripts": {
72106
"test": "jest",
73107
"test:watch": "jest --watch"
74108
}
109+
//...
75110
}
76111
```
77112

@@ -85,17 +120,28 @@ simulate the behaviors of real browsers in `JSDOM`. To add global mocks, you can
85120
- Create a file `jest-global-mocks.ts` to your root project.
86121
- Import it in your global setup file:
87122

88-
```ts
89-
// Assuming that your global setup file is setup-jest.ts
90-
import 'jest-preset-angular/setup-jest';
123+
```ts tab={"label":"TypeScript CJS"}
124+
// setup-jest.ts
125+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
126+
import './jest-global-mocks';
127+
128+
setupZoneTestEnv();
129+
```
130+
131+
```ts tab={"label":"TypeScript ESM"}
132+
// setup-jest.ts
133+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone.mjs';
91134
import './jest-global-mocks';
135+
136+
setupZoneTestEnv();
92137
```
93138

94139
:::tip
95140

96141
An example for `jest-global-mocks.ts`
97142

98-
```
143+
```ts
144+
// jest-global-mocks.ts
99145
Object.defineProperty(document, 'doctype', {
100146
value: '<!DOCTYPE html>',
101147
});

‎website/docs/getting-started/test-environment.md

+113-25
Original file line numberDiff line numberDiff line change
@@ -3,32 +3,120 @@ id: test-environment
33
title: Test environment
44
---
55

6-
If you look at [`setup-jest.js`](https://github.com/thymikee/jest-preset-angular/blob/main/setup-jest.js),
7-
what we're doing here is we're adding globals required by Angular. With the included [Angular zone patch](https://github.com/angular/angular/tree/main/packages/zone.js)
8-
we also make sure Jest test methods run in Zone context. Then we initialize the Angular testing environment like normal.
9-
10-
While `setup-jest.js` above is for running Jest with **CommonJS** mode, we also provide [`setup-jest.mjs`](https://github.com/thymikee/jest-preset-angular/blob/main/setup-jest.mjs)
11-
to run with **ESM** mode.
12-
13-
### Configure test environment
14-
15-
When creating Angular test environment with `TestBed`, it is possible to specify the `testEnvironmentOptions` via `globalThis` in the Jest setup file.
16-
For example:
17-
18-
```ts
19-
// setup-test.ts
20-
globalThis.ngJest = {
21-
testEnvironmentOptions: {
22-
teardown: {
23-
destroyAfterEach: false,
24-
rethrowErrors: true,
25-
},
26-
errorOnUnknownElements: true,
27-
errorOnUnknownProperties: true,
28-
},
6+
In Jest, a test environment defines the sandbox context in which your tests run.
7+
For Angular projects, setting up the correct test environment is essential to ensure compatibility with the
8+
framework-specific features, such as dependency injection and change detection.
9+
10+
`jest-preset-angular` provides utility functions to simplify setting up a Jest test environment tailored for Angular projects.
11+
These functions support both **zone-based** and **zoneless** environments, catering to different testing needs.
12+
13+
## Methods
14+
15+
import TOCInline from '@theme/TOCInline';
16+
17+
<TOCInline toc={toc.slice(1)} />
18+
19+
---
20+
21+
### `setupZoneTestEnv(options)`
22+
23+
Configures a test environment that uses `zone.js`, which is the mechanism for tracking asynchronous operations.
24+
It is suitable for most Angular applications that rely on `zone.js` for change detection and other framework features.
25+
26+
You can customize the environment by providing options as function arguments.
27+
28+
#### Parameters
29+
30+
- `options`**(optional)**: An object follows [TestEnvironmentOptions interface](https://github.com/angular/angular/blob/a55341b1ab8d2bc4285a4cce59df7fc0b23c0125/packages/core/testing/src/test_bed_common.ts#L95), which allows fine-tuning the environment.
31+
32+
#### Example:
33+
34+
- Create a Jest setup file:
35+
36+
```ts tab={"label": "TypeScript CJS"}
37+
// setup-jest.ts
38+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
39+
40+
setupZoneTestEnv({
41+
//...options
42+
});
43+
```
44+
45+
```ts tab={"label": "TypeScript ESM"}
46+
// setup-jest.ts
47+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone.mjs';
48+
49+
setupZoneTestEnv({
50+
//...options
51+
});
52+
```
53+
54+
- Update your Jest configuration:
55+
56+
```ts tab={"label": "TypeScript CJS"}
57+
// jest.config.ts
58+
import type { Config } from 'jest';
59+
60+
const jestConfig: Config = {
61+
preset: 'jest-preset-angular',
62+
setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
2963
};
3064

31-
import 'jest-preset-angular/setup-jest';
65+
export default jestConfig;
3266
```
3367

34-
`jest-preset-angular` will look at `globalThis.ngJest` and pass the correct [`TestEnvironmentOptions`](https://angular.io/api/core/testing/TestEnvironmentOptions) object to `TestBed`.
68+
```ts tab={"label": "TypeScript ESM"}
69+
// jest.config.mts
70+
import type { Config } from 'jest';
71+
72+
const jestConfig: Config = {
73+
preset: 'jest-preset-angular',
74+
setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
75+
};
76+
77+
export default jestConfig;
78+
```
79+
80+
### `setupZonelessTestEnv(options)`
81+
82+
Configures a test environment that **DOESN'T** use `zone.js`, as described in [Angular experimental zoneless guide](https://angular.dev/guide/experimental/zoneless).
83+
It is designed for projects that have disabled `zone.js`, which can lead to improved performance and simplified testing.
84+
85+
:::important
86+
87+
This function is only supported in Jest `ESM` mode in [Jest 29](https://github.com/jestjs/jest/issues/10962). Jest 30+ will support to use for `CommonJS` mode.
88+
89+
:::
90+
91+
You can customize the environment by providing options as function arguments.
92+
93+
#### Parameters
94+
95+
- `options`**(optional)**: An object follows [TestEnvironmentOptions interface](https://github.com/angular/angular/blob/a55341b1ab8d2bc4285a4cce59df7fc0b23c0125/packages/core/testing/src/test_bed_common.ts#L95), which allows fine-tuning the environment.
96+
97+
#### Example:
98+
99+
- Create a Jest setup file:
100+
101+
```ts tab={"label": "TypeScript ESM"}
102+
// setup-jest.ts
103+
import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zone.mjs';
104+
105+
setupZonelessTestEnv({
106+
//...options
107+
});
108+
```
109+
110+
- Update your Jest configuration:
111+
112+
```ts tab={"label": "TypeScript ESM"}
113+
// jest.config.mts
114+
import type { Config } from 'jest';
115+
116+
const jestConfig: Config = {
117+
preset: 'jest-preset-angular',
118+
setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
119+
};
120+
121+
export default jestConfig;
122+
```

‎website/docs/guides/troubleshooting.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ With Angular 8 and higher, a [change to the way the Angular CLI works](https://g
1818
"emitDecoratorMetadata": true
1919
```
2020

21-
In general, this is related to Angular's reflection and also depends on a reflection library, as e. g. included in `core-js`. We use our own minimal reflection that satisfy Angular's current requirements, but in case these change, you can install `core-js` and import the reflection library in your `setup-jest.ts`:
21+
In general, this is related to `Angular`'s reflection and also depends on a reflection library, as e. g. included in `core-js`. We use our own minimal reflection that satisfy `Angular`'s current requirements, but in case these change, you can install `core-js` and import the reflection library in your `setup-jest.ts`:
2222

2323
```ts
2424
// setup-jest.ts

0 commit comments

Comments
 (0)
Please sign in to comment.