chore(release): v11.0.0-rc.0 (#1131)

Author: ahnpnl

CHANGELOG.md

@@ -1,3 +1,39 @@
+# [11.0.0-rc.0](https://github.com/thymikee/jest-preset-angular/compare/v10.0.1...v11.0.0-rc.0) (2021-11-04)
+
+
+### 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))
+
+
+## BREAKING CHANGES
+
+* **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**:
+  + `ng-jest-resolver` is introduced as a custom Jest resolver to resolve `.mjs` files.
+  + `transformIgnorePatterns` is added to inform Jest to transform `.mjs` files.
+  + `transform` is updated to include `.mjs` extension to transform to `CommonJS` codes.
+
+If one has custom Jest config, please make sure to adjust Jest config for CJS mode as following:
+```
+// jest.config.js
+module.exports = {
+  // other config
+  resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js',
+  transformIgnorePatterns: ['node_modules/(?!@angular)'],
+  transform: {
+    '^.+\\.(ts|js|mjs|html|svg)$': 'jest-preset-angular',
+  },
+}
+```
+
+
+### Special Thanks
+
+Alan Agius, Pete Bacon Darwin from Angular team
+
+
+
 ## [10.1.0](https://github.com/thymikee/jest-preset-angular/compare/v10.0.1...v10.1.0) (2021-10-26)
 
 

README.md

@@ -71,13 +71,19 @@ Adjust your `tsconfig.spec.json` to be:
 }
 ```
 
+## Notes on usage with Angular >=13
+
+Check out our [Angular >=13 usage notes](https://thymikee.github.io/jest-preset-angular/docs/guides/angular-13)
+
 ## Angular Ivy
 
 Check out our [Angular Ivy guidance](https://thymikee.github.io/jest-preset-angular/docs/guides/angular-ivy)
 
-## Example apps
+## Example projects with base Jest configuration
 
 We have [example apps](https://github.com/thymikee/jest-preset-angular/tree/main/examples) to provide a basic setup to use Jest in an Angular project.
+The `examples` folder consist of several example Angular applications from **v10** to **13**, as well as example projects
+with `yarn workspace` or monorepo structure.
 
 ## Built With
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "jest-preset-angular",
-  "version": "10.1.0",
+  "version": "11.0.0-rc.0",
   "description": "Jest preset configuration for Angular projects",
   "license": "MIT",
   "engines": {

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

@@ -0,0 +1,45 @@
+---
+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](https://thymikee.github.io/jest-preset-angular/docs/next/getting-started/presets).
+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.
+
+- `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 using custom Jest config options for `transformIgnorePatterns`, `transform` and not using `preset: 'jest-preset-angular'`,
+  there are a few changes needed to be added to the Jest config:
+
+```js
+// jest.config.js
+module.exports = {
+  resolver: 'jest-preset-angular/build/resolvers/ng-jest-resolver.js',
+  transformIgnorePatterns: ['node_modules/(?!@angular)'],
+  transform: {
+    '^.+\\.(ts|js|mjs|html|svg)$': 'jest-preset-angular',
+  },
+};
+```

website/sidebars.js

@@ -22,6 +22,7 @@ module.exports = {
       collapsed: false,
       items: [
         'guides/angular-ivy',
+        'guides/angular-13+',
         'guides/esm-support',
         'guides/jsdom-version',
         'guides/using-with-babel',

website/src/pages/index.js

@@ -78,6 +78,10 @@ function Home() {
           <div className={styles.announcementInner}>
             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>
+            .
+          </div>
         </div>
       </header>
       <main>

website/versioned_docs/version-10.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-10.x/getting-started/options.md

@@ -0,0 +1,65 @@
+---
+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/next/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)$',
+    },
+  },
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(ts|js|html|svg)$': 'jest-preset-angular',
+  },
+  moduleFileExtensions: ['ts', 'html', 'js', 'json'],
+  snapshotSerializers,
+};
+```
+
+:::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`.
+- `"transform"` – run every TS, JS, or HTML file through so called _Jest transformer_; this lets Jest understand non-JS syntax.
+- `"testEnvironment"` – the test environment to run on.
+- `"moduleFileExtensions"` – our modules are TypeScript and JavaScript files.
+- `"moduleNameMapper"` – if you're using absolute imports here's how to tell Jest where to look for them; uses regex.
+- `"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.