chore(release): 14.5.0

CHANGELOG.md

@@ -1,3 +1,23 @@
+## [14.5.0](https://github.com/thymikee/jest-preset-angular/compare/v14.4.2...v14.5.0) (2025-01-10)
+
+
+### Features
+
+* feat: add custom `jsdom` env [#2904](https://github.com/thymikee/jest-preset-angular/issues/2904) ([6045a96](https://github.com/thymikee/jest-preset-angular/commit/6045a96)), closes [#2883](https://github.com/thymikee/jest-preset-angular/issues/2883)
+
+
+### Code Refactoring
+
+* refactor: add type for `serializers/index.ts` ([dd64d78](https://github.com/thymikee/jest-preset-angular/commit/dd64d78))
+
+
+### DEPRECATIONS
+
+* refactor: deprecate `defaultTransformerOptions` in `presets` ([99d3112](https://github.com/thymikee/jest-preset-angular/commit/99d3112))
+* refactor: deprecate `ngcc` util via `globalSetup` ([edeaa3f](https://github.com/thymikee/jest-preset-angular/commit/edeaa3f))
+
+
+
 ## [14.4.2](https://github.com/thymikee/jest-preset-angular/compare/v14.4.1...v14.4.2) (2024-12-03)
 
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "jest-preset-angular",
-  "version": "14.4.2",
+  "version": "14.5.0",
   "description": "Jest preset configuration for Angular projects",
   "license": "MIT",
   "engines": {

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

@@ -0,0 +1,164 @@
+---
+id: installation
+title: Installation
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+### Dependencies
+
+You can install `jest-preset-angular` and dependencies all at once with one of the following commands.
+
+```bash npm2yarn
+npm install -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 a setup file with following contents:
+
+```ts title="setup-jest.ts" tab={"label":"TypeScript CJS"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+
+setupZoneTestEnv();
+```
+
+```ts title="setup-jest.ts" tab={"label":"TypeScript ESM"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
+
+setupZoneTestEnv();
+```
+
+Add the following section to your root Jest config
+
+```ts title="jest.config.ts" tab={"label":"TypeScript CJS"}
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  preset: 'jest-preset-angular',
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+};
+
+export default jestConfig;
+```
+
+```ts title="jest.config.mts" tab={"label":"TypeScript ESM"}
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  preset: 'jest-preset-angular',
+  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
+};
+
+export default jestConfig;
+```
+
+Adjust your `tsconfig.spec.json` to be:
+
+```json5 title="tsconfig.spec.json" tab={"label": "Tsconfig CJS"}
+{
+  //...
+  extends: './tsconfig.json',
+  compilerOptions: {
+    //...
+    module: 'CommonJS',
+    types: ['jest'],
+  },
+  include: ['src/**/*.spec.ts', 'src/**/*.d.ts'],
+  //...
+}
+```
+
+```json title="tsconfig.spec.json" tab={"label": "Tsconfig ESM"}
+{
+  //...
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    //...
+    "module": "ES2022",
+    "types": ["jest"]
+  },
+  "include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
+  //...
+}
+```
+
+Adjust `scripts` part your `package.json` to use `jest` instead of `ng`, e.g.
+
+```json title="package.json"
+{
+  //...
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch"
+  }
+  //...
+}
+```
+
+### 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 title="setup-jest.ts" tab={"label":"TypeScript CJS"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone';
+import './jest-global-mocks';
+
+setupZoneTestEnv();
+```
+
+```ts title="setup-jest.ts" tab={"label":"TypeScript ESM"}
+import { setupZoneTestEnv } from 'jest-preset-angular/setup-env/zone/index.mjs';
+import './jest-global-mocks';
+
+setupZoneTestEnv();
+```
+
+:::tip
+
+An example for `jest-global-mocks.ts`
+
+```ts title="jest-global-mocks.ts"
+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-14.5/getting-started/options.md

@@ -0,0 +1,134 @@
+---
+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 [doc](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.
+
+:::
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+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;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+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:
+
+```ts title="jest.config.ts" tab={"label": "TypeScript CJS"}
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  //...
+  transform: {
+    '^.+\\.(ts|js|mjs|html|svg)$': [
+      'jest-preset-angular',
+      {
+        processWithEsbuild: [<glob_to_files>]
+      }
+    ]
+  }
+};
+
+export default jestConfig;
+```
+
+```ts title="jest.config.mts" tab={"label": "TypeScript ESM"}
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  //...
+  transform: {
+    '^.+\\.(ts|js|mjs|html|svg)$': [
+      'jest-preset-angular',
+      {
+        processWithEsbuild: [<glob_to_files>]
+      }
+    ]
+  }
+};
+
+export default jestConfig;
+```
+
+### Exposed configuration
+
+```ts title="jest.config.ts"
+import type { Config } from 'jest';
+
+const jestConfig: Config = {
+  moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'],
+  snapshotSerializers: [
+    'jest-preset-angular/build/serializers/html-comment',
+    'jest-preset-angular/build/serializers/ng-snapshot',
+    'jest-preset-angular/build/serializers/no-ng-attributes',
+  ],
+  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`.
+- `"snapshotSerializers"` - array of serializers which will be applied to snapshot the code. See more in [Snapshot testing](../guides/snapshot-testing.md)
+- `"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.