docs(devs-infra): documentation for v9.0.0 (#931)

Author: ahnpnl

website/docs/getting-started/presets.md

@@ -47,14 +47,14 @@ copy the original options and override the options you need:
 
 ```js
 // jest.config.js
-const { defaults: tsjPreset } = require('jest-preset-angular/presets');
-// const { defaultsESM: tsjPreset } = require('jest-preset-angular/presets')
+const { defaults: jestNgPreset } = require('jest-preset-angular/presets');
+// const { defaultsESM: jestNgPreset } = require('jest-preset-angular/presets')
 
 module.exports = {
   // [...]
   globals: {
     'ts-jest': {
-      ...tsjPreset.globals['ts-jest'],
+      ...jestNgPreset.globals['ts-jest'],
       // [...your overriden options]
     },
   },
@@ -66,14 +66,14 @@ Or through TypeScript (if `ts-node` is installed):
 ```ts
 // jest.config.ts
 import type { InitialOptionsTsJest } from 'ts-jest/dist/types';
-import { defaults as tsjPreset } from 'jest-preset-angular/presets';
-// import { defaultsESM as tsjPreset } from 'jest-preset-angular/presets'
+import { defaults as jestNgPreset } from 'jest-preset-angular/presets';
+// import { defaultsESM as jestNgPreset } from 'jest-preset-angular/presets'
 
 const config: InitialOptionsTsJest = {
   // [...]
   globals: {
     'ts-jest': {
-      ...tsjPreset.globals['ts-jest'],
+      ...jestNgPreset.globals['ts-jest'],
       // [...your overriden options]
     },
   },

website/package.json

@@ -12,15 +12,19 @@
     "clear": "docusaurus clear"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-alpha.70",
-    "@docusaurus/plugin-ideal-image": "2.0.0-alpha.70",
-    "@docusaurus/plugin-pwa": "2.0.0-alpha.70",
-    "@docusaurus/preset-classic": "2.0.0-alpha.70",
+    "@docusaurus/core": "^2.0.0-beta.0",
+    "@docusaurus/plugin-ideal-image": "^2.0.0-beta.0",
+    "@docusaurus/plugin-pwa": "^2.0.0-beta.0",
+    "@docusaurus/preset-classic": "^2.0.0-beta.0",
     "@mdx-js/react": "^1.6.21",
     "clsx": "^1.1.1",
     "latest-version": "^5.1.0",
-    "react": "^16.8.4",
-    "react-dom": "^16.8.4"
+    "react": "^16.14.0",
+    "react-dom": "^16.14.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.0.0",
+    "@types/react": "^17.0.3"
   },
   "browserslist": {
     "production": [

website/static/manifest.json

@@ -8,42 +8,42 @@
   "start_url": "./index.html",
   "icons": [
     {
-      "src": "img/icons/icon-72x72.png",
+      "src": "img/logo.png",
       "sizes": "72x72",
       "type": "image/png"
     },
     {
-      "src": "img/icons/icon-96x96.png",
+      "src": "img/logo.png",
       "sizes": "96x96",
       "type": "image/png"
     },
     {
-      "src": "img/icons/icon-128x128.png",
+      "src": "img/logo.png",
       "sizes": "128x128",
       "type": "image/png"
     },
     {
-      "src": "img/icons/icon-144x144.png",
+      "src": "img/logo.png",
       "sizes": "144x144",
       "type": "image/png"
     },
     {
-      "src": "img/icons/icon-152x152.png",
+      "src": "img/logo.png",
       "sizes": "152x152",
       "type": "image/png"
     },
     {
-      "src": "img/icons/icon-192x192.png",
+      "src": "img/logo.png",
       "sizes": "192x192",
       "type": "image/png"
     },
     {
-      "src": "img/icons/icon-384x384.png",
+      "src": "img/logo.png",
       "sizes": "384x384",
       "type": "image/png"
     },
     {
-      "src": "img/icons/icon-512x512.png",
+      "src": "img/logo.png",
       "sizes": "512x512",
       "type": "image/png"
     }

website/versioned_docs/version-8.x/getting-started/presets.md

@@ -42,13 +42,13 @@ copy the original options and override the options you need:
 
 ```js
 // jest.config.js
-const { defaults: tsjPreset } = require('jest-preset-angular');
+const { defaults: jestNgPreset } = require('jest-preset-angular');
 
 module.exports = {
   // [...]
   globals: {
     'ts-jest': {
-      ...tsjPreset.globals['ts-jest'],
+      ...jestNgPreset.globals['ts-jest'],
       // [...your overriden options]
     },
   },

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

@@ -0,0 +1,90 @@
+---
+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
+
+Feel free to copy the [`jest-global-mocks.ts`](https://github.com/thymikee/jest-preset-angular/blob/master/e2e/test-app-v9/jest-global-mocks.ts) file from the test app directory and save it next to the `setup-jest.ts` file.
+
+:::
+
+#### 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-9.x/getting-started/options.md

@@ -0,0 +1,49 @@
+---
+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
+
+### Exposed configuration
+
+```js
+const snapshotSerializers = require('../build/serializers');
+
+module.exports = {
+  globals: {
+    'ts-jest': {
+      tsconfig: '<rootDir>/tsconfig.spec.json',
+      stringifyContentPathRegex: '\\.html$',
+    },
+  },
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(ts|js|html)$': '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.

website/versioned_docs/version-9.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/default-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-9.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/master/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/master/src/zone-patch)
+we also make sure Jest test methods run in Zone context. Then we initialize the Angular testing environment like normal.

website/versioned_docs/version-9.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