docs: release docs v13 and update CHANGELOG

CHANGELOG.md

@@ -19,6 +19,7 @@
 * Drop support for Angular 11, 12
 * Jest 29 is required
 * `destroyAfterEach` and `teardown` are no longer available to use, please use `testEnvironmentOptions` instead.
+* `target` is `tsconfig` is now respected according to user configuration, it is no longer hardcoded at `ES2015`. See also note at https://thymikee.github.io/jest-preset-angular/docs/getting-started/installation
 
 
 

website/docs/getting-started/installation.md

@@ -21,6 +21,12 @@ yarn add -D jest jest-preset-angular @types/jest
 
 ### Configuration
 
+:::important
+
+Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
+
+:::
+
 In your project root, create `setup-jest.ts` file with following contents:
 
 ```ts
@@ -75,12 +81,6 @@ Adjust your `tsconfig.spec.json` to be:
 }
 ```
 
-:::important
-
-Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
-
-:::
-
 ### Customizing
 
 #### Global mocks

website/versioned_docs/version-10.x/getting-started/installation.md

@@ -21,6 +21,12 @@ yarn add -D jest jest-preset-angular @types/jest
 
 ### Configuration
 
+:::important
+
+Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
+
+:::
+
 In your project root, create `setup-jest.ts` file with following contents:
 
 ```ts

website/versioned_docs/version-11.0/getting-started/installation.md

@@ -21,6 +21,12 @@ yarn add -D jest jest-preset-angular @types/jest
 
 ### Configuration
 
+:::important
+
+Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
+
+:::
+
 In your project root, create `setup-jest.ts` file with following contents:
 
 ```ts

website/versioned_docs/version-11.1/getting-started/installation.md

@@ -21,6 +21,12 @@ yarn add -D jest jest-preset-angular @types/jest
 
 ### Configuration
 
+:::important
+
+Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
+
+:::
+
 In your project root, create `setup-jest.ts` file with following contents:
 
 ```ts

website/versioned_docs/version-12.0/getting-started/installation.md

@@ -21,6 +21,12 @@ yarn add -D jest jest-preset-angular @types/jest
 
 ### Configuration
 
+:::important
+
+Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
+
+:::
+
 In your project root, create `setup-jest.ts` file with following contents:
 
 ```ts
@@ -75,12 +81,6 @@ Adjust your `tsconfig.spec.json` to be:
 }
 ```
 
-:::important
-
-Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
-
-:::
-
 ### Customizing
 
 #### Global mocks

website/versioned_docs/version-13.0/getting-started/installation.md

@@ -0,0 +1,135 @@
+---
+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
+
+:::important
+
+Angular doesn't support native `async/await` in testing with `target` higher than `ES2016`, see https://github.com/angular/components/issues/21632#issuecomment-764975917
+
+:::
+
+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 tab
+module.exports = {
+  preset: 'jest-preset-angular',
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+  globalSetup: 'jest-preset-angular/global-setup',
+};
+```
+
+```ts tab
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  preset: 'jest-preset-angular',
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+  globalSetup: 'jest-preset-angular/global-setup',
+};
+
+export default jestConfig;
+```
+
+```JSON tab
+{
+  "jest": {
+    "preset": "jest-preset-angular",
+    "setupFilesAfterEnv": ["<rootDir>/setup-jest.ts"],
+    "globalSetup": "jest-preset-angular/global-setup"
+  }
+}
+```
+
+Adjust your `tsconfig.spec.json` to be:
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/spec",
+    "module": "CommonJs",
+    "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
+simulate 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-13.0/getting-started/options.md

@@ -0,0 +1,143 @@
+---
+id: options
+title: Options
+---
+
+`jest-preset-angular` uses `ts-jest` options under the hood, which are located under the `transform` 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 **v9.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.
+
+```js tab
+module.exports = {
+  //...
+  moduleNameMapper: {
+    '^src/(.*)$': '<rootDir>/src/$1',
+    '^app/(.*)$': '<rootDir>/src/app/$1',
+    '^assets/(.*)$': '<rootDir>/src/assets/$1',
+    '^environments/(.*)$': '<rootDir>/src/environments/$1',
+  },
+};
+```
+
+```ts tab
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  //...
+  moduleNameMapper: {
+    '^src/(.*)$': '<rootDir>/src/$1',
+    '^app/(.*)$': '<rootDir>/src/app/$1',
+    '^assets/(.*)$': '<rootDir>/src/assets/$1',
+    '^environments/(.*)$': '<rootDir>/src/environments/$1',
+  },
+};
+
+export default jestConfig;
+```
+
+### Processing with esbuild
+
+Since **v11.0.0**, `jest-preset-angular` introduced the usage of `esbuild` to process files besides TypeScript API. By default, all `.mjs` files
+will be processed by `esbuild` in `jest-preset-angular`. To configure extra files to process with `esbuild`, one can do the following:
+
+```js tab
+module.exports = {
+  //...
+  globals: {
+    ngJest: {
+      processWithEsbuild: [<glob_to_files>],
+    },
+  },
+}
+```
+
+```ts tab
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  //...
+  globals: {
+    ngJest: {
+      processWithEsbuild: [<glob_to_files>],
+    },
+  },
+}
+
+export default jestConfig;
+```
+
+:::
+
+### Exposed configuration
+
+```js tab
+const snapshotSerializers = require('../build/serializers');
+
+module.exports = {
+  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',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+        stringifyContentPathRegex: '\\.(html|svg)$',
+      },
+    ],
+  },
+};
+```
+
+```ts tab
+import type { Config } from 'jest';
+import snapshotSerializers from 'jest-preset-angular/build/serializers';
+
+const jestConfig: Config = {
+  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',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+        stringifyContentPathRegex: '\\.(html|svg)$',
+      },
+    ],
+  },
+};
+
+export default jestConfig;
+```
+
+:::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 `"transform"` to pass information about configuration to use for code compilation with `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`, `HTML`, or `SVG` file through so called _Jest transformer_; this lets Jest understand non-JS syntax.