chore(release): 11.0.0 (#1186)

Author: ahnpnl

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)
 
 

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": {

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
 

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**:

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.
 

website/src/pages/index.js

@@ -79,7 +79,7 @@ function Home() {
             Angular Ivy? Check out our <Link to="/docs/guides/angular-ivy">Angular Ivy guidance</Link>.
           </div>
           <div className={styles.announcementInner}>
-            Migrate to Angular >=13? Check out our <Link to="/docs/next/guides/angular-13+">Angular >=13 guidance</Link>
+            Migrate to Angular >=13? Check out our <Link to="/docs/guides/angular-13+">Angular >=13 guidance</Link>
             .
           </div>
         </div>

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: ['<rootDir>/setup-jest.ts'],
+};
+```
+
+- or to your root `package.json`
+
+```json
+{
+  "jest": {
+    "preset": "jest-preset-angular",
+    "setupFilesAfterEnv": ["<rootDir>/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: '<!DOCTYPE html>',
+});
+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 `<rootDir>/src/test.ts` to jest `testPathIgnorePatterns` option.

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/(.*)$': '<rootDir>/src/$1',
+  '^app/(.*)$': '<rootDir>/src/app/$1',
+  '^assets/(.*)$': '<rootDir>/src/assets/$1',
+  '^environments/(.*)$': '<rootDir>/src/environments/$1',
+}
+```
+
+:::
+
+### Exposed configuration
+
+```js
+const snapshotSerializers = require('../build/serializers');
+
+module.exports = {
+  globals: {
+    'ts-jest': {
+      tsconfig: '<rootDir>/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.

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`<br/>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`<br/>                    | 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.
+
+:::

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.