diff --git a/CHANGELOG.md b/CHANGELOG.md index 54f8a76327..63cf87b7f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,42 @@ +# [11.0.0](https://github.com/thymikee/jest-preset-angular/compare/v11.0.0-rc.4...v11.0.0) (2021-11-18) + + +### Bug Fixes + +* **presets:** use `ts-jest` types for preset types ([#1172](https://github.com/thymikee/jest-preset-angular/issues/1172)) ([81854f6](https://github.com/thymikee/jest-preset-angular/commit/81854f680088f23f4f2f5801ef660711812b90e3)) +* **presets:** add `mjs` to the list of `moduleFileExtensions` ([#1155](https://github.com/thymikee/jest-preset-angular/issues/1155)) ([3c992a1](https://github.com/thymikee/jest-preset-angular/commit/3c992a18b209f9d6500e34255b8f74c7fc5f3560)), closes [#1147](https://github.com/thymikee/jest-preset-angular/issues/1147) + + +### Features + +* support Angular 13 in CJS mode ([#1122](https://github.com/thymikee/jest-preset-angular/issues/1122)) ([12d3c6d](https://github.com/thymikee/jest-preset-angular/commit/12d3c6d27fadc3c423ab42d10615526e26826ed6)) + + +## Code Refactoring + +* **presets**: improve `transformIgnorePatterns` value ([#1162](https://github.com/thymikee/jest-preset-angular/issues/1162)) ([99a4b1b1](https://github.com/thymikee/jest-preset-angular/commit/99a4b1b1549a13b27bd8d03df181ea6fa69aa073)) + + +### Performance Improvements + +* process `js` files in `node_modules` with `esbuild` ([#1169](https://github.com/thymikee/jest-preset-angular/issues/1169)) ([1de3bf0](https://github.com/thymikee/jest-preset-angular/commit/1de3bf04886fbc91ab821e965ec94a2d8dc741be)) +* use `esbuild` to process `.mjs` files ([#1142](https://github.com/thymikee/jest-preset-angular/issues/1142)) ([5d3fe10](https://github.com/thymikee/jest-preset-angular/commit/5d3fe1010592b7a3973cdbc22c238e0e46d47b45)), closes [#1141](https://github.com/thymikee/jest-preset-angular/issues/1141) + + +## BREAKING CHANGES + +* `js` files from `node_modules` are now compiled with `esbuild` to improve performance. +* **NodeJs** range version support now is `^12.20.0 || ^14.15.0 || >=16.10.0` +* Due to the introduction of **ESM package format** for Angular packages, several things are added to the **default preset** + to handle `.mjs` files from **Angular ESM packages**. Please check our migration documentation at https://thymikee.github.io/jest-preset-angular/docs/next/guides/angular-13+ + + +### Special Thanks + +Alan Agius, Pete Bacon Darwin from Angular team + + + # [11.0.0-rc.4](https://github.com/thymikee/jest-preset-angular/compare/v11.0.0-rc.3...v11.0.0-rc.4) (2021-11-15) diff --git a/package.json b/package.json index 7dd445f32e..4ebf89ce4f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "jest-preset-angular", - "version": "11.0.0-rc.4", + "version": "11.0.0", "description": "Jest preset configuration for Angular projects", "license": "MIT", "engines": { diff --git a/website/docs/getting-started/options.md b/website/docs/getting-started/options.md index c287ac3243..0754497911 100644 --- a/website/docs/getting-started/options.md +++ b/website/docs/getting-started/options.md @@ -6,7 +6,7 @@ title: Options `jest-preset-angular` uses `ts-jest` options under the hood, which are located under the `globals` of Jest config object in the `package.json` file of your project, or through a `jest.config.js`, or `jest.config.ts` file. -More information about `ts-jest` options, see https://kulshekhar.github.io/ts-jest/docs/next/getting-started/options +More information about `ts-jest` options, see https://kulshekhar.github.io/ts-jest/docs/getting-started/options :::important diff --git a/website/docs/guides/angular-13+.md b/website/docs/guides/angular-13+.md index 5d1375c299..eecfa0c399 100644 --- a/website/docs/guides/angular-13+.md +++ b/website/docs/guides/angular-13+.md @@ -4,7 +4,7 @@ title: Angular >=13 --- **Angular 13** introduces ESM package format for Angular packages. `jest-preset-angular` -currently supports testing with Jest in `CommonJS` mode with **Angular 13** using [default preset](https://thymikee.github.io/jest-preset-angular/docs/next/getting-started/presets). +currently supports testing with Jest in `CommonJS` mode with **Angular 13** using [default preset](../getting-started/presets.md). Jest ESM support with **Angular 13** is being worked on and will come in the future releases. Starting from **11.0.0**, `jest-preset-angular` introduces a few extra changes to be able to run Jest with **Angular 13**: diff --git a/website/docs/guides/esm-support.md b/website/docs/guides/esm-support.md index 8cf46020ba..c0be22e9e5 100644 --- a/website/docs/guides/esm-support.md +++ b/website/docs/guides/esm-support.md @@ -5,7 +5,7 @@ title: ESM Support To use `jest-preset-angular` with ESM support, you'll first need to check [ESM Jest documentation](https://jestjs.io/docs/en/ecmascript-modules). -`jest-preset-angular` supports ESM via a `ts-jest` config option [useESM](https://kulshekhar.github.io/ts-jest/docs/next/getting-started/options/useESM) in combination with jest config option [extensionsToTreatAsEsm](https://jestjs.io/docs/en/next/configuration#extensionstotreatasesm-arraystring). +`jest-preset-angular` supports ESM via a `ts-jest` config option [useESM](https://kulshekhar.github.io/ts-jest/docs/getting-started/options/useESM) in combination with jest config option [extensionsToTreatAsEsm](https://jestjs.io/docs/en/configuration#extensionstotreatasesm-arraystring). There is also a [preset](../getting-started/presets.md) to work with ESM. diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 6970efb4a2..e7a9341be3 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -79,7 +79,7 @@ function Home() { Angular Ivy? Check out our Angular Ivy guidance.
- Migrate to Angular >=13? Check out our Angular >=13 guidance + Migrate to Angular >=13? Check out our Angular >=13 guidance .
diff --git a/website/versioned_docs/version-11.x/getting-started/installation.md b/website/versioned_docs/version-11.x/getting-started/installation.md new file mode 100644 index 0000000000..77f0b66998 --- /dev/null +++ b/website/versioned_docs/version-11.x/getting-started/installation.md @@ -0,0 +1,117 @@ +--- +id: installation +title: Installation +--- + +### Dependencies + +You can install `jest-preset-angular` and dependencies all at once with one of the following commands. + +#### NPM + +```sh +npm install -D jest jest-preset-angular @types/jest +``` + +#### Yarn + +```sh +yarn add -D jest jest-preset-angular @types/jest +``` + +### Configuration + +In your project root, create `setup-jest.ts` file with following contents: + +```ts +import 'jest-preset-angular/setup-jest'; +``` + +Add the following section: + +- to your root `jest.config.js` + +```js +// jest.config.js +module.exports = { + preset: 'jest-preset-angular', + setupFilesAfterEnv: ['/setup-jest.ts'], +}; +``` + +- or to your root `package.json` + +```json +{ + "jest": { + "preset": "jest-preset-angular", + "setupFilesAfterEnv": ["/setup-jest.ts"] + } +} +``` + +Adjust your `tsconfig.spec.json` to be: + +```json +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "./out-tsc/spec", + "types": ["jest"] + }, + "include": ["src/**/*.spec.ts", "src/**/*.d.ts"] +} +``` + +### Customizing + +#### Global mocks + +`jest-preset-angular` uses `JSDOM` which is different from normal browsers. You might need some global browser mocks to +stimulate the behaviors of real browsers in `JSDOM`. To add global mocks, you can do the following: + +- Create a file `jest-global-mocks.ts` to your root project. +- Import it in your global setup file: + +```ts +// Assuming that your global setup file is setup-jest.ts +import 'jest-preset-angular/setup-jest'; +import './jest-global-mocks'; +``` + +:::tip + +An example for `jest-global-mocks.ts` + +``` +Object.defineProperty(window, 'CSS', { value: null }); +Object.defineProperty(document, 'doctype', { + value: '', +}); +Object.defineProperty(window, 'getComputedStyle', { + value: () => { + return { + display: 'none', + appearance: ['-webkit-appearance'], + }; + }, +}); +/** + * ISSUE: https://github.com/angular/material2/issues/7101 + * Workaround for JSDOM missing transform property + */ +Object.defineProperty(document.body.style, 'transform', { + value: () => { + return { + enumerable: true, + configurable: true, + }; + }, +}); +``` + +::: + +#### Avoid karma conflicts + +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 `/src/test.ts` to jest `testPathIgnorePatterns` option. diff --git a/website/versioned_docs/version-11.x/getting-started/options.md b/website/versioned_docs/version-11.x/getting-started/options.md new file mode 100644 index 0000000000..0754497911 --- /dev/null +++ b/website/versioned_docs/version-11.x/getting-started/options.md @@ -0,0 +1,69 @@ +--- +id: options +title: Options +--- + +`jest-preset-angular` uses `ts-jest` options under the hood, which are located under the `globals` of Jest config object +in the `package.json` file of your project, or through a `jest.config.js`, or `jest.config.ts` file. + +More information about `ts-jest` options, see https://kulshekhar.github.io/ts-jest/docs/getting-started/options + +:::important + +Since **9.0.0**, `jest-preset-angular` default Jest configuration no longer provides `moduleNameMapper`. If you wish to reuse +the old `moduleNameMapper` configuration, you can put this into your Jest config + +``` +moduleNameMapper: { + '^src/(.*)$': '/src/$1', + '^app/(.*)$': '/src/app/$1', + '^assets/(.*)$': '/src/assets/$1', + '^environments/(.*)$': '/src/environments/$1', +} +``` + +::: + +### Exposed configuration + +```js +const snapshotSerializers = require('../build/serializers'); + +module.exports = { + globals: { + 'ts-jest': { + tsconfig: '/tsconfig.spec.json', + stringifyContentPathRegex: '\\.(html|svg)$', + }, + }, + moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'], + resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js', + snapshotSerializers, + testEnvironment: 'jsdom', + transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'], + transform: { + '^.+\\.(ts|js|mjs|html|svg)$': 'jest-preset-angular', + }, +}; +``` + +:::important + +Jest runs with `jest-preset-angular` neither in browser nor through dev server. It uses `JSDOM` to abstract browser environment hence we depend on +`JSDOM` implementation for real browser features. + +::: + +### Brief explanation of config + +- we're using some `"globals"` to pass information about where our tsconfig.json file is that we'd like to be able to transform HTML files through `ts-jest`. +- `"moduleFileExtensions"` – our modules are TypeScript (`ts`), HTML (`html`), JavaScript (`js`), JSON (`json`) and ESM JavaScript (`mjs`) files. +- `"moduleNameMapper"` – if you're using absolute imports here's how to tell Jest where to look for them; uses `RegExp`. +- `"resolver"` - instruct Jest how to resolve entry file based on `package.json` definitions. +- `"snapshotSerializers"` - array of serializers which will be applied to snapshot the code. Note: by default angular adds + some angular-specific attributes to the code (like `ng-reflect-*`, `ng-version="*"`, `_ngcontent-c*` etc). + This package provides serializer to remove such attributes. This makes snapshots cleaner and more human-readable. + To remove such specific attributes use `no-ng-attributes` serializer. You need to add `no-ng-attributes` serializer manually. +- `"testEnvironment"` – the test environment to run on. +- `"transformIgnorePatterns"`: instruct Jest to transform any `.mjs` files which come from `node_modules`. +- `"transform"` – run every `TS`, `JS`, `MJS`, or `HTML` file through so called _Jest transformer_; this lets Jest understand non-JS syntax. diff --git a/website/versioned_docs/version-11.x/getting-started/presets.md b/website/versioned_docs/version-11.x/getting-started/presets.md new file mode 100644 index 0000000000..63169d2500 --- /dev/null +++ b/website/versioned_docs/version-11.x/getting-started/presets.md @@ -0,0 +1,91 @@ +--- +id: presets +title: Presets +--- + +### The presets + +`jest-preset-angular` comes with 2 presets, covering most of the project's base configuration: + +| Preset name | Description | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| `jest-preset-angular/presets/default`
or `jest-preset-angular` | TypeScript, JavaScript and HTML files (`js`, `.ts`, `.html`) will be transformed by `jest-preset-angular` to **CommonJS** syntax. | +| `jest-preset-angular/presets/defaults-esm`
| TypeScript, JavaScript and HTML files (`js`, `.ts`, `.html`) will be transformed by `jest-preset-angular` to **ESM** syntax. | + +### Basic usage + +In most cases, simply setting the `preset` key to the desired preset name in your Jest config should be enough to start +using TypeScript with Jest (assuming you added `jest-preset-angular` to your `devDependencies` of course): + +```js +// jest.config.js +module.exports = { + // [...] + // Replace `jest-preset-angular` with the preset you want to use + // from the above list + preset: 'jest-preset-angular', +}; +``` + +```json +// OR package.json +{ + // [...] + "jest": { + // Replace `jest-preset-angular` with the preset you want to use + // from the above list + "preset": "jest-preset-angular" + } +} +``` + +### Advanced + +All presets come with default `ts-jest` config options. +If you want to override any of the options, you'll need to use the JavaScript version of Jest config, +copy the original options and override the options you need: + +```js +// jest.config.js +const { defaults: jestNgPreset } = require('jest-preset-angular/presets'); +// const { defaultsESM: jestNgPreset } = require('jest-preset-angular/presets') + +module.exports = { + // [...] + globals: { + 'ts-jest': { + ...jestNgPreset.globals['ts-jest'], + // [...your overriden options] + }, + }, +}; +``` + +Or through TypeScript (if `ts-node` is installed): + +```ts +// jest.config.ts +import type { InitialOptionsTsJest } from 'ts-jest/dist/types'; +import { defaults as jestNgPreset } from 'jest-preset-angular/presets'; +// import { defaultsESM as jestNgPreset } from 'jest-preset-angular/presets' + +const config: InitialOptionsTsJest = { + // [...] + globals: { + 'ts-jest': { + ...jestNgPreset.globals['ts-jest'], + // [...your overriden options] + }, + }, +}; + +export default config; +``` + +:::important + +If you choose to override `globals` in order to point at a specific tsconfig, you will need to make sure that original `ts-jest` +options provided through the default preset are defined to the `globals.ts-jest` section too, otherwise you will get +errors. + +::: diff --git a/website/versioned_docs/version-11.x/getting-started/test-environment.md b/website/versioned_docs/version-11.x/getting-started/test-environment.md new file mode 100644 index 0000000000..1ae187b8c5 --- /dev/null +++ b/website/versioned_docs/version-11.x/getting-started/test-environment.md @@ -0,0 +1,8 @@ +--- +id: test-environment +title: Test environment +--- + +If you look at [`setup-jest.ts`](https://github.com/thymikee/jest-preset-angular/blob/main/src/config/setup-jest.ts), +what we're doing here is we're adding globals required by Angular. With the included [jest-zone-patch](https://github.com/thymikee/jest-preset-angular/tree/main/src/zone-patch) +we also make sure Jest test methods run in Zone context. Then we initialize the Angular testing environment like normal. diff --git a/website/versioned_docs/version-11.x/guides/absolute-imports.md b/website/versioned_docs/version-11.x/guides/absolute-imports.md new file mode 100644 index 0000000000..e679d83e3b --- /dev/null +++ b/website/versioned_docs/version-11.x/guides/absolute-imports.md @@ -0,0 +1,9 @@ +--- +id: absolute-imports +title: Absolute Imports +--- + +If you wish to use TypeScript path mappings which are defined in `paths` of your tsconfig, make sure that you create the +similar mapping for `moduleNameMapper` in Jest config. + +More information see `ts-jest` [paths mapping](https://kulshekhar.github.io/ts-jest/docs/getting-started/paths-mapping) configuration documentation diff --git a/website/versioned_docs/version-11.x/guides/angular-13+.md b/website/versioned_docs/version-11.x/guides/angular-13+.md new file mode 100644 index 0000000000..eecfa0c399 --- /dev/null +++ b/website/versioned_docs/version-11.x/guides/angular-13+.md @@ -0,0 +1,89 @@ +--- +id: angular-13+ +title: Angular >=13 +--- + +**Angular 13** introduces ESM package format for Angular packages. `jest-preset-angular` +currently supports testing with Jest in `CommonJS` mode with **Angular 13** using [default preset](../getting-started/presets.md). +Jest ESM support with **Angular 13** is being worked on and will come in the future releases. + +Starting from **11.0.0**, `jest-preset-angular` introduces a few extra changes to be able to run Jest with **Angular 13**: + +- `ng-jest-resolver` is introduced as a custom Jest resolver to resolve `.mjs` files. + +- `moduleFileExtensions` is updated to include `mjs` files as accepted module format. + +- `transformIgnorePatterns` is added to inform Jest to transform `.mjs` files. + +- `transform` is updated to include `.mjs` extension to transform to `CommonJS` codes. + +## Migration steps from Angular < 13 + +- Upgrade the project to **Angular 13** following https://update.angular.io/ + +- If one is using the default preset as following: + +```js +// jest.config.js +module.exports = { + preset: 'jest-preset-angular', +}; +``` + +there are no migration steps required + +- If one is **NOT** having `preset: 'jest-preset-angular'` in Jest config, the config needs to be updated with new values for + `resolver`, `transformIgnorePatterns` and `transform`: + +```js +// jest.config.js +module.exports = { + // ...other options + moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'], + resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js', + transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'], + transform: { + '^.+\\.(ts|js|mjs|html|svg)$': 'jest-preset-angular', + }, +}; +``` + +## Potential issues with Angular 13 ESM package format and workaround + +### `Cannot find modules` error when importing any deep paths from Angular ESM format packages + +- Angular 13 ESM package format makes Jest resolution not able to resolve the correct `.mjs` files. Even though we introduced + `ng-jest-resolver` as a part of the preset, this resolver won't work for all scenarios. One might get Jest error like + +``` +Cannot find module '@angular/common/locales/xx' from 'src/app/app.component.spec.ts' +``` + +To fix this issue, one needs to add `mjs` to `moduleFileExtensions` as following + +```js +// jest.config.js +module.exports = { + // ...other options + moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'], +}; +``` + +If the issue still **persists**, you might need to configure [moduleNameMapper](https://jestjs.io/docs/configuration#modulenamemapper-objectstring-string--arraystring) +or extend the behavior the default [resolver](https://github.com/thymikee/jest-preset-angular/blob/main/src/resolvers/ng-jest-resolver.ts) of this preset. + +### Usage with Angular libraries which are built with Angular CLI 13 + +Besides, the changes in Angular packages themselves, **Angular** libraries which are built with **Angular CLI 13** also introduce +ESM package format. Similar to Angular packages, Jest doesn't understand `.mjs` files which are in these new format +libraries in Jest **CommonJS** mode. + +To fix this issue, one should modify `transformIgnorePatterns` to be as following: + +```js +// jest.config.js +module.exports = { + // ...other options + transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'], +}; +``` diff --git a/website/versioned_docs/version-11.x/guides/angular-ivy.md b/website/versioned_docs/version-11.x/guides/angular-ivy.md new file mode 100644 index 0000000000..900c843f4b --- /dev/null +++ b/website/versioned_docs/version-11.x/guides/angular-ivy.md @@ -0,0 +1,20 @@ +--- +id: angular-ivy +title: Angular Ivy +--- + +Starting from **v9.0.0+**, `jest-preset-angular` is fully compatible with Angular Ivy. To make sure that Jest uses the +Angular Ivy, you must run `ngcc` before running tests. `ngcc` will transform all Angular-format packages to be compatible +with Ivy compiler. + +`jest-preset-angular` also provides util script to help you to run `ngcc` with Jest but this script only works via the +JavaScript version of Jest config + +```js +// jest.config.js +require('jest-preset-angular/ngcc-jest-processor'); + +module.exports = { + // [...] +}; +``` diff --git a/website/versioned_docs/version-11.x/guides/esm-support.md b/website/versioned_docs/version-11.x/guides/esm-support.md new file mode 100644 index 0000000000..c0be22e9e5 --- /dev/null +++ b/website/versioned_docs/version-11.x/guides/esm-support.md @@ -0,0 +1,77 @@ +--- +id: esm-support +title: ESM Support +--- + +To use `jest-preset-angular` with ESM support, you'll first need to check [ESM Jest documentation](https://jestjs.io/docs/en/ecmascript-modules). + +`jest-preset-angular` supports ESM via a `ts-jest` config option [useESM](https://kulshekhar.github.io/ts-jest/docs/getting-started/options/useESM) in combination with jest config option [extensionsToTreatAsEsm](https://jestjs.io/docs/en/configuration#extensionstotreatasesm-arraystring). + +There is also a [preset](../getting-started/presets.md) to work with ESM. + +### Examples + +#### Manual configuration + +```js +// jest.config.js +module.exports = { + // [...] + extensionsToTreatAsEsm: ['.ts'], + globals: { + 'ts-jest': { + tsconfig: '/tsconfig.spec.json', + stringifyContentPathRegex: '\\.html$', + useESM: true, + }, + }, +}; +``` + +```json +// OR package.json +{ + // [...] + "jest": { + "extensionsToTreatAsEsm": [".ts"], + "globals": { + "ts-jest": { + "tsconfig": "/tsconfig.spec.json", + "stringifyContentPathRegex": "\\.html$", + "useESM": true + } + } + } +} +``` + +#### Use ESM presets + +```js +// jest.config.js +module.exports = { + // [...] + preset: 'jest-preset-angular/presets/defaults-esm', +}; +``` + +```json +// OR package.json +{ + // [...] + "jest": { + "preset": "jest-preset-angular/presets/defaults-esm" + } +} +``` + +:::tip + +Jest will attempt to load **ESM** files from `node_modules` with default `jest-resolve` which usually works for most of the cases. +However, there are cases like Angular libraries **ESM** built files or **ESM** files which are outside `node_modules` might not be loaded +correctly. + +To fix that, one can use `moduleNameMapper` in jest config to instruct Jest to load the correct **ESM** files or create a +custom Jest [resolver](https://jestjs.io/docs/configuration#resolver-string). + +::: diff --git a/website/versioned_docs/version-11.x/guides/jsdom-version.md b/website/versioned_docs/version-11.x/guides/jsdom-version.md new file mode 100644 index 0000000000..a36451b817 --- /dev/null +++ b/website/versioned_docs/version-11.x/guides/jsdom-version.md @@ -0,0 +1,19 @@ +--- +id: jsdom-version +title: Configure other JSDOM versions +--- + +**Jest** v26+ by default uses **JSDOM** 16 to support Node 10+. + +If you need a different JSDOM version than the one that ships with Jest, you can install a jsdom environment +package, e.g. `jest-environment-jsdom-sixteen` and edit your Jest config like so: + +``` +{ + "testEnvironment": "jest-environment-jsdom-sixteen" +} +``` + +If you use JSDOM v11 or lower, you might have to mock `localStorage` or `sessionStorage` on your own or using some third-party library by loading it in `setupFilesAfterEnv`. + +Reference: https://jestjs.io/docs/en/configuration.html#testenvironment-string, https://github.com/jsdom/jsdom/blob/main/Changelog.md#1200 diff --git a/website/versioned_docs/version-11.x/guides/troubleshooting.md b/website/versioned_docs/version-11.x/guides/troubleshooting.md new file mode 100644 index 0000000000..82b7240923 --- /dev/null +++ b/website/versioned_docs/version-11.x/guides/troubleshooting.md @@ -0,0 +1,108 @@ +--- +id: troubleshooting +title: Troubleshooting +--- + +You can check Jest [troubleshooting guide](https://jestjs.io/docs/en/troubleshooting) + +## Common issues + +Problems may arise if you're using custom builds (this preset is tailored for `angular-cli` as firstly priority). Please be advised that every entry in default configuration may be overridden to best suite your app's needs. + +### Can't resolve all parameters for SomeClass(?) + +With Angular 8 and higher, a [change to the way the Angular CLI works](https://github.com/thymikee/jest-preset-angular/issues/288) may be causing your metadata to be lost. You can update your `tsconfig.spec.json` to include the `emitDecoratorMetadata` compiler option: + +``` + "compilerOptions": { + "emitDecoratorMetadata": true +``` + +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`: + +```typescript +require('core-js/es/reflect'); +require('core-js/proposals/reflect-metadata'); +``` + +Note that this might also be related to other issues with the dependency injection and parameter type reflection. + +### @Input() bindings are not reflected into fixture when `ChangeDetectionStrategy.OnPush` is used + +This issue is not related to Jest, [it's a known Angular bug](https://github.com/angular/angular/issues/12313) + +To mitigate this, you need to wrap your component under test, into some container component with default change detection strategy (`ChangeDetectionStrategy.Default`) and pass props through it, or overwrite change detection strategy within `TestBed` setup, if it's not critical for the test. + +```ts +// override change detection strategy +beforeEach(async(() => { + TestBed.configureTestingModule({ declarations: [PizzaItemComponent] }) + .overrideComponent(PizzaItemComponent, { + set: { changeDetection: ChangeDetectionStrategy.Default }, + }) + .compileComponents(); +})); +``` + +### The animation trigger "transformMenu" has failed + +The currently used JSDOM version handles this, but older versions used before v7 of this preset was missing transform property. To patch it for Angular Material, use this workaround. + +Add this to your `jestGlobalMocks` file + +```js +Object.defineProperty(document.body.style, 'transform', { + value: () => { + return { + enumerable: true, + configurable: true, + }; + }, +}); +``` + +Reference: https://github.com/angular/material2/issues/7101 + +### Unexpected token [import|export|other] + +This means, that a file is not transformed through `TypeScript` compiler, e.g. because it is a `JS` file with `TS` syntax, or +it is published to npm as uncompiled source files. Here's what you can do. A typical Jest error is like this: + +``` +({"Object.":function(module,exports,require,__dirname,__filename,jest){import * as i0 from '@angular/core'; + ^^^^^^ + SyntaxError: Cannot use import statement outside a module +``` + +To fix the issue, one needs to adjust `transformIgnorePatterns` whitelist: + +```js +// jest.config.js +module.exports = { + // ...other options + transformIgnorePatterns: ['node_modules/(?!@angular|@ngrx)'], +}; +``` + +By default, Jest doesn't transform `node_modules`, because they should be valid JavaScript files. However, it happens that +library authors assume that you'll compile their sources. So you have to tell this to Jest explicitly. +Above snippet means that `@angular`, `@ngrx` will be transformed, even though they're `node_modules`. + +### Allow vendor libraries like jQuery, etc... + +The same like normal Jest configuration, you can load jQuery in your Jest setup file. For example your Jest setup file is `setup-jest.ts` you can declare jQuery: + +```js +window.$ = require('path/to/jquery'); +``` + +or + +```js +import $ from 'jquery'; +global.$ = global.jQuery = $; +``` + +The same declaration can be applied to other vendor libraries. + +Reference: https://github.com/facebook/jest/issues/708 diff --git a/website/versioned_docs/version-11.x/guides/using-with-babel.md b/website/versioned_docs/version-11.x/guides/using-with-babel.md new file mode 100644 index 0000000000..58e46790ae --- /dev/null +++ b/website/versioned_docs/version-11.x/guides/using-with-babel.md @@ -0,0 +1,37 @@ +--- +id: using-with-babel +title: Using with Babel +--- + +If you wish to use `Babel`, you need to say jest to transpile such files manually. + +1. Install dependencies required by the official Jest documentation for [Babel integration](https://jest-bot.github.io/jest/docs/babel.html). + +2. Install `@babel/preset-env` and add `babel.config.js` (or modify existing if needed) with the following content: + +```js +module.exports = function (api) { + api.cache(true); + + const presets = ['@babel/preset-env']; + const plugins = []; + + return { + presets, + plugins, + }; +}; +``` + +_Note: do not use a `.babelrc` file otherwise the packages that you specify in the next step will not be picked up. CF [Babel documentation](https://babeljs.io/docs/en/configuration#what-s-your-use-case) and the comment `You want to compile node_modules? babel.config.js is for you!`_. + +3. Update Jest configuration (by default TypeScript process untranspiled JS files which is source of the problem): + +```js +module.exports = { + transform: { + '^.+\\.(ts|html)$': 'jest-preset-angular', + '^.+\\.js$': 'babel-jest', + }, +}; +``` diff --git a/website/versioned_docs/version-11.x/introduction.md b/website/versioned_docs/version-11.x/introduction.md new file mode 100644 index 0000000000..01d52b7a75 --- /dev/null +++ b/website/versioned_docs/version-11.x/introduction.md @@ -0,0 +1,17 @@ +--- +id: introduction +title: Introduction +description: Jest preset configuration for Angular projects. +slug: / +--- + +`jest-preset-angular` is Jest preset configuration and TypeScript preprocessor with source map support for Jest that lets you use Jest to test Angular projects. + +This is a part of the article: [Testing Angular faster with Jest](https://www.xfive.co/blog/testing-angular-faster-jest/). + +:::important + +Starting from **v9.0.0**, we follow closely native `Karma + Jasmine` implementation which is default provided by +`@angular/cli`. This will make the testing experience with Jest more inline native with Angular testing experience. + +::: diff --git a/website/versioned_docs/version-11.x/processing.md b/website/versioned_docs/version-11.x/processing.md new file mode 100644 index 0000000000..77b8f5a295 --- /dev/null +++ b/website/versioned_docs/version-11.x/processing.md @@ -0,0 +1,6 @@ +--- +id: processing +title: Processing flow +--- + +`jest-preset-angular` follows the processing flow of `ts-jest`, see more at https://kulshekhar.github.io/ts-jest/docs/processing diff --git a/website/versioned_sidebars/version-11.x-sidebars.json b/website/versioned_sidebars/version-11.x-sidebars.json new file mode 100644 index 0000000000..dd28c2e19a --- /dev/null +++ b/website/versioned_sidebars/version-11.x-sidebars.json @@ -0,0 +1,77 @@ +{ + "version-11.x-docs": [ + { + "collapsed": true, + "type": "category", + "label": "jest-preset-angular", + "items": [ + { + "type": "doc", + "id": "version-11.x/introduction" + }, + { + "type": "doc", + "id": "version-11.x/processing" + } + ] + }, + { + "collapsed": false, + "type": "category", + "label": "Getting Started", + "items": [ + { + "type": "doc", + "id": "version-11.x/getting-started/installation" + }, + { + "type": "doc", + "id": "version-11.x/getting-started/presets" + }, + { + "type": "doc", + "id": "version-11.x/getting-started/options" + }, + { + "type": "doc", + "id": "version-11.x/getting-started/test-environment" + } + ] + }, + { + "collapsed": false, + "type": "category", + "label": "Guides", + "items": [ + { + "type": "doc", + "id": "version-11.x/guides/angular-ivy" + }, + { + "type": "doc", + "id": "version-11.x/guides/angular-13+" + }, + { + "type": "doc", + "id": "version-11.x/guides/esm-support" + }, + { + "type": "doc", + "id": "version-11.x/guides/jsdom-version" + }, + { + "type": "doc", + "id": "version-11.x/guides/using-with-babel" + }, + { + "type": "doc", + "id": "version-11.x/guides/absolute-imports" + }, + { + "type": "doc", + "id": "version-11.x/guides/troubleshooting" + } + ] + } + ] +} diff --git a/website/versions.json b/website/versions.json index 848c47bdc1..a79e61d326 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,5 @@ [ + "11.x", "10.x", "9.x", "8.x"