Skip to content

Commit cf0e2f4

Browse files
ahnpnlahnpnl
committed
docs: add documentation for v14.3
1 parent a304036 commit cf0e2f4

20 files changed

+1709
-10
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ setupZoneTestEnv();
3333

3434
```ts tab={"label":"TypeScript ESM"}
3535
// setup-jest.ts
36-
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone.mjs';
36+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
3737

3838
setupZoneTestEnv();
3939
```

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ setupZoneTestEnv({
4444

4545
```ts tab={"label": "TypeScript ESM"}
4646
// setup-jest.ts
47-
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone.mjs';
47+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
4848

4949
setupZoneTestEnv({
5050
//...options
@@ -100,7 +100,7 @@ You can customize the environment by providing options as function arguments.
100100

101101
```ts tab={"label": "TypeScript ESM"}
102102
// setup-jest.ts
103-
import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zone.mjs';
103+
import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless/index.mjs';
104104

105105
setupZonelessTestEnv({
106106
//...options

‎website/docs/guides/angular-13+.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -111,16 +111,18 @@ export default jestConfig;
111111

112112
Before upgrading to ng13 and switching to ES Modules, your `setup-jest.ts` file most likely uses the preset `setup-jest`, like the following:
113113

114-
```ts
114+
```ts tab={"label":"TypeScript CJS"}
115115
// setup-jest.ts
116-
import 'jest-preset-angular/setup-jest';
117-
```
116+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
118117

119-
or for ESM mode
118+
setupZoneTestEnv();
119+
```
120120

121-
```ts
121+
```ts tab={"label":"TypeScript ESM"}
122122
// setup-jest.ts
123-
import 'jest-preset-angular/setup-jest.mjs';
123+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
124+
125+
setupZoneTestEnv();
124126
```
125127

126128
## Potential issues with Angular 13 ESM package format and workaround

‎website/docs/guides/esm-support.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ Besides, there is `setup-jest.mjs` to add to Jest setup file to ensure that Jest
1919

2020
```ts
2121
// setup-jest.ts
22-
import 'jest-preset-angular/setup-jest.mjs';
22+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
23+
24+
setupZoneTestEnv();
2325
```
2426

2527
### Examples

‎website/versioned_docs/version-14.3/getting-started/installation.md

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
id: installation
3+
title: Installation
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
### Dependencies
10+
11+
You can install `jest-preset-angular` and dependencies all at once with one of the following commands.
12+
13+
```bash npm2yarn
14+
npm install -D jest jest-preset-angular @types/jest
15+
```
16+
17+
### Configuration
18+
19+
:::important
20+
21+
Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
22+
23+
:::
24+
25+
In your project root, create a setup file with following contents:
26+
27+
```ts tab={"label":"TypeScript CJS"}
28+
// setup-jest.ts
29+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
30+
31+
setupZoneTestEnv();
32+
```
33+
34+
```ts tab={"label":"TypeScript ESM"}
35+
// setup-jest.ts
36+
import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
37+
38+
setupZoneTestEnv();
39+
```
40+
41+
Add the following section to your root Jest config
42+
43+
```ts tab={"label":"TypeScript CJS"}
44+
// jest.config.ts
45+
import type { Config } from 'jest';
46+
47+
const jestConfig: Config = {
48+
preset: 'jest-preset-angular',
49+
setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
50+
};
51+
52+
export default jestConfig;
53+
```
54+
55+
```ts tab={"label":"TypeScript ESM"}
56+
// jest.config.mts
57+
import type { Config } from 'jest';
58+
59+
const jestConfig: Config = {
60+
preset: 'jest-preset-angular',
61+
setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
62+
};
63+
64+
export default jestConfig;
65+
```
66+
67+
Adjust your `tsconfig.spec.json` to be:
68+
69+
```json5 tab={"label": "Tsconfig CJS"}
70+
// tsconfig.spec.json
71+
{
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+
//...
88+
"extends": "./tsconfig.json",
89+
"compilerOptions": {
90+
//...
91+
"module": "ES2022",
92+
"types": ["jest"]
93+
},
94+
"include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
95+
//...
96+
}
97+
```
98+
99+
Adjust `scripts` part your `package.json` to use `jest` instead of `ng`, e.g.
100+
101+
```json
102+
// package.json
103+
{
104+
//...
105+
"scripts": {
106+
"test": "jest",
107+
"test:watch": "jest --watch"
108+
}
109+
//...
110+
}
111+
```
112+
113+
### Customizing
114+
115+
#### Global mocks
116+
117+
`jest-preset-angular` uses `JSDOM` which is different from normal browsers. You might need some global browser mocks to
118+
simulate the behaviors of real browsers in `JSDOM`. To add global mocks, you can do the following:
119+
120+
- Create a file `jest-global-mocks.ts` to your root project.
121+
- Import it in your global setup file:
122+
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';
134+
import './jest-global-mocks';
135+
136+
setupZoneTestEnv();
137+
```
138+
139+
:::tip
140+
141+
An example for `jest-global-mocks.ts`
142+
143+
```ts
144+
// jest-global-mocks.ts
145+
Object.defineProperty(document, 'doctype', {
146+
value: '<!DOCTYPE html>',
147+
});
148+
Object.defineProperty(window, 'getComputedStyle', {
149+
value: () => {
150+
return {
151+
display: 'none',
152+
appearance: ['-webkit-appearance'],
153+
};
154+
},
155+
});
156+
/**
157+
* ISSUE: https://github.com/angular/material2/issues/7101
158+
* Workaround for JSDOM missing transform property
159+
*/
160+
Object.defineProperty(document.body.style, 'transform', {
161+
value: () => {
162+
return {
163+
enumerable: true,
164+
configurable: true,
165+
};
166+
},
167+
});
168+
```
169+
170+
:::
171+
172+
#### Avoid karma conflicts
173+
174+
By Angular CLI defaults you'll have a `src/test.ts` file which will be picked up by jest. To circumvent this you can either rename it to `src/karmaTest.ts` or hide it from jest by adding `<rootDir>/src/test.ts` to jest `testPathIgnorePatterns` option.

‎website/versioned_docs/version-14.3/getting-started/options.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
id: options
3+
title: Options
4+
---
5+
6+
`jest-preset-angular` uses `ts-jest` options under the hood, which are located under the `transform` of Jest config object
7+
in the `package.json` file of your project, or through a `jest.config.js`, or `jest.config.ts` file.
8+
9+
More information about `ts-jest` options, see [doc](https://kulshekhar.github.io/ts-jest/docs/getting-started/options)
10+
11+
:::important
12+
13+
Since **v9.0.0**, `jest-preset-angular` default Jest configuration no longer provides `moduleNameMapper`. If you wish to reuse
14+
the old `moduleNameMapper` configuration, you can put this into your Jest config.
15+
16+
```js tab
17+
// jest.config.js
18+
module.exports = {
19+
//...
20+
moduleNameMapper: {
21+
'^src/(.*)$': '<rootDir>/src/$1',
22+
'^app/(.*)$': '<rootDir>/src/app/$1',
23+
'^assets/(.*)$': '<rootDir>/src/assets/$1',
24+
'^environments/(.*)$': '<rootDir>/src/environments/$1',
25+
},
26+
};
27+
```
28+
29+
```ts tab
30+
// jest.config.ts
31+
import type { Config } from 'jest';
32+
33+
const jestConfig: Config = {
34+
//...
35+
moduleNameMapper: {
36+
'^src/(.*)$': '<rootDir>/src/$1',
37+
'^app/(.*)$': '<rootDir>/src/app/$1',
38+
'^assets/(.*)$': '<rootDir>/src/assets/$1',
39+
'^environments/(.*)$': '<rootDir>/src/environments/$1',
40+
},
41+
};
42+
43+
export default jestConfig;
44+
```
45+
46+
### Processing with esbuild
47+
48+
Since **v11.0.0**, `jest-preset-angular` introduced the usage of `esbuild` to process files besides TypeScript API. By default, all `.mjs` files
49+
will be processed by `esbuild` in `jest-preset-angular`. To configure extra files to process with `esbuild`, one can do the following:
50+
51+
```js tab
52+
// jest.config.js
53+
module.exports = {
54+
//...
55+
globals: {
56+
ngJest: {
57+
processWithEsbuild: [<glob_to_files>],
58+
},
59+
},
60+
}
61+
```
62+
63+
```ts tab
64+
// jest.config.ts
65+
import type { Config } from 'jest';
66+
67+
const jestConfig: Config = {
68+
//...
69+
globals: {
70+
ngJest: {
71+
processWithEsbuild: [<glob_to_files>],
72+
},
73+
},
74+
}
75+
76+
export default jestConfig;
77+
```
78+
79+
:::
80+
81+
### Exposed configuration
82+
83+
```js tab
84+
// jest.config.js
85+
const snapshotSerializers = require('jest-preset-angular/build/serializers');
86+
87+
module.exports = {
88+
moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'],
89+
resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js',
90+
snapshotSerializers,
91+
testEnvironment: 'jsdom',
92+
transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
93+
transform: {
94+
'^.+\\.(ts|js|mjs|html|svg)$': [
95+
'jest-preset-angular',
96+
{
97+
tsconfig: '<rootDir>/tsconfig.spec.json',
98+
stringifyContentPathRegex: '\\.(html|svg)$',
99+
},
100+
],
101+
},
102+
};
103+
```
104+
105+
```ts tab
106+
// jest.config.ts
107+
import type { Config } from 'jest';
108+
import snapshotSerializers from 'jest-preset-angular/build/serializers';
109+
110+
const jestConfig: Config = {
111+
moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'],
112+
resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js',
113+
snapshotSerializers,
114+
testEnvironment: 'jsdom',
115+
transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
116+
transform: {
117+
'^.+\\.(ts|js|mjs|html|svg)$': [
118+
'jest-preset-angular',
119+
{
120+
tsconfig: '<rootDir>/tsconfig.spec.json',
121+
stringifyContentPathRegex: '\\.(html|svg)$',
122+
},
123+
],
124+
},
125+
};
126+
127+
export default jestConfig;
128+
```
129+
130+
:::important
131+
132+
Jest runs with `jest-preset-angular` neither in browser nor through dev server. It uses `JSDOM` to abstract browser environment hence we depend on
133+
`JSDOM` implementation for real browser features.
134+
135+
:::
136+
137+
### Brief explanation of config
138+
139+
- We're using `"transform"` to pass information about configuration to use for code compilation with `ts-jest`.
140+
- `"moduleFileExtensions"` – our modules are TypeScript (`ts`), HTML (`html`), JavaScript (`js`), JSON (`json`) and ESM JavaScript (`mjs`) files.
141+
- `"moduleNameMapper"` – if you're using absolute imports here's how to tell Jest where to look for them; uses `RegExp`.
142+
- `"resolver"` - instruct Jest how to resolve entry file based on `package.json` definitions.
143+
- `"snapshotSerializers"` - array of serializers which will be applied to snapshot the code. See more in [Snapshot testing](../guides/snapshot-testing.md)
144+
- `"testEnvironment"` – the test environment to run on.
145+
- `"transformIgnorePatterns"`: instruct Jest to transform any `.mjs` files which come from `node_modules`.
146+
- `"transform"` – run every `TS`, `JS`, `MJS`, `HTML`, or `SVG` file through so called _Jest transformer_; this lets Jest understand non-JS syntax.

0 commit comments

Comments
 (0)