docs(angular): moving from karma to jest (#4008)

docs/angular/guides/modern-angular/karma-to-jest.md

@@ -0,0 +1,102 @@
+# Migrating from Karma to Jest
+
+By default, the Angular CLI provides Karma as a test runner and Jasmine as the test framework. Nx offers the choice of using Jest for both runner and framework. If a library in your Angular workspace was created to use Karma, there are three steps to migrate to Jest:
+
+## 1. Add Jest support to the workspace
+
+The following command adds Jest support to the workspace. This only needs to be performed once per workspace. You can skip this step if Jest is already added to the workspace.
+
+```bash
+ng generate jest
+```
+
+## 2. Replace Karma config with Jest config files for a lib
+
+Assuming we have the default configuration produced by the Angular CLI, we need to perform the following operations:
+
+**Step 1**
+
+Delete `karma.conf.js` from the lib's folder. If you have custom code or options here you will need to make a copy so that you can try to recreate this behavior with Jest in `src/jest.config.js` after step 4.
+
+**Step 2**
+
+Delete `src/test.ts`. Again if you have custom code in here you will need to make a copy and recreate the behavior after Step 4 in the `src/lib/test-setup.ts`.
+
+**Step 3**
+
+Remove the test section for the project in your `angular.json` or `workspace.json`:
+
+```json
+<project_name>: {
+  "architect": {
+    "test": {
+      "builder": "@angular-devkit/build-angular:karma",
+      "options": {
+        "main": "libs/shared/view-component/src/test.ts",
+        "tsConfig": "libs/shared/view-component/tsconfig.spec.json",
+        "karmaConfig": "libs/shared/view-component/karma.conf.js"
+      }
+    }
+  }
+}
+```
+
+**Step 4**
+
+```bash
+ng generate jest-project --project <project_name>
+```
+
+Any custom code that was present in Step 1 and 2 should be recreated now in the new Jest config files that were generated by this command.
+
+**Step 5**
+
+Modify `tsconfig.spec.ts` in the lib’s folder and add Jest typings: add jest under types and remove previous framework (e.g. jasmine)
+
+```bash
+"types": [ "jest", "node" ]
+```
+
+## 3. Migrate spec files to Jest
+
+This step is very manual and varies widely based on the usage of features from various frameworks. Below are some common migrations for Jasmine. Jest’s API is very close to Jasmine’s but there are some differences.
+
+**Spies**
+
+- Bare spies
+  - Jasmine
+    ```ts
+    const myMock = jasmine.createSpy('myMock);
+    ```
+  - Jest
+    ```ts
+    const myMock = jest.fn();
+    ```
+- Spies on existing objects
+  - Jasmine
+    ```ts
+    spyOn(foo, 'setBar');
+    ```
+  - Jest
+    ```ts
+    jest.spyOn(foo, ‘setBar’);
+    ```
+
+It’s a good practice to avoid relying on `spyOn` being global and instead using `jest.spyOn`. The behavior of the Jest spies is different from the Jasmine spies in the following ways:
+
+- The method being spied on is called by default in Jest, similar to Jasmine’s `spyOn(foo, ‘setBar’).and.callThrough();` To avoid calling through to the original function, set the `mockImplementation` to override it: `jest.spyOn(foo, ‘setBar’).mockImplementation(() => {})`. This is similar to Jasmine’s `spyOn(foo, ‘setBar’).and.callFake`
+- Jasmine’s `spyOn(foo, "getBar").and.returnValue(745);` would become `jest.spyOn(foo, ‘setBar’).mockImplementation(() => 745)` in Jest
+
+It is worth looking at the documentation for Jasmine (or your previous test framework) and compare against the Jest documentation - most functionality should be supported but some code changes might be needed.
+
+**Marbles: `hot` and `cold`**
+
+`@nrwl/nx/testing` exports `hot` and `cold` from `jasmine-marbles`. We now need to import these from `jest-marbles` instead.
+
+At this point, the spec files might have issues that need to be fixed before tests can be run: the linter will highlight these issues.
+
+Once the spec files have been fixed we can run the tests (using Jest):
+
+```bash
+ng test <project_name>
+```

docs/map.json

@@ -995,6 +995,11 @@
                 "name": "Moving from Protractor to Cypress",
                 "id": "protractor-to-cypress",
                 "file": "angular/guides/modern-angular/protractor-to-cypress"
+              },
+              {
+                "name": "Moving from Karma to Jest",
+                "id": "karma-to-jest",
+                "file": "angular/guides/modern-angular/karma-to-jest.md"
               }
             ]
           },