docs: new testing approach for NgRx

Co-authored-by: MWallnisch <M.Wallnisch@intershop.de>

docs/README.md

@@ -27,12 +27,13 @@ kb_sync_latest_only
 ### Developing
 
 - [Guide - Development Environment](./guides/development.md)
+- [Guide - Angular Component Development](./guides/angular-component-development.md)
 - [Concept - Styling](./concepts/styling-behavior.md)
 - [Concept - Testing](./concepts/testing.md)
   - [Guide - Testing with Jest](./guides/testing-jest.md)
   - [Guide - Testing with Cypress](./guides/testing-cypress.md)
+  - [Guide - State Management > Testing](./guides/state-management.md#testing-ngrx-artifacts)
 - [Guide - Code Documentation](./guides/code-documentation.md)
-- [Guide - Angular Component Development](./guides/angular-component-development.md)
 - [Guide - Angular Change Detection](./guides/angular-change-detection.md)
 - [Guide - Data Handling with Mappers](./guides/data-handling-with-mappers.md)
 

docs/concepts/configuration.md

@@ -181,6 +181,14 @@ export class SomeService {
 }
 ```
 
+### Unit Testing with Feature Toggles
+
+With Version 0.21 we introduced [`FeatureToggleModule.forTesting`][feature-toggle-module] which provides a shallow implementation for testing with feature toggles not depending on the state management.
+Use it in the `imports` of the `TestBed` declaration of the unit test.
+Switching features in tests can be triggered by calling [`FeatureToggleModule.switchTestingFeatures`][feature-toggle-module] with a new set of activated feature toggles.
+
+[feature-toggle-module]: ../../src/app/core/feature-toggle.module.ts
+
 ## Setting Default Locale
 
 You can set the default locale statically by modifying the order of the provided locales in the Angular CLI environment files.

docs/guides/angular-component-development.md

@@ -136,3 +136,13 @@ Consider splitting one into multiple components when:
 - **Async data**: Component relies on async data from the store which makes the component code unnecessarily complex. Use a container component then which resolves the observables at the outside of the child component and passes data in via property bindings. Do not do this for simple cases.
 
 Single-use dumb components are always okay if it improves readability.
+
+## Mock Facades in Tests
+
+Angular Artifacts like Components, Directives and Pipes should solely depend on facades to interact with the [State Management](../concepts/state-management.md).
+This is enforced with the TSLint rule `no-intelligence-in-artifacts` which rejects every usage of REST API Services and NgRx Artifacts.
+
+Use [ts-mockito](https://github.com/NagRock/ts-mockito) for creating and managing these mocks.
+Providers for Facades can easily be added by using the VSCode snippet `ish-provider-ts-mockito`:
+
+![ish-provider-ts-mockito](ish-provider-ts-mockito.gif 'VSCode snippet ish-provider-ts-mockito in action')

docs/guides/migrations.md

@@ -7,6 +7,14 @@ kb_sync_latest_only
 
 # Migrations
 
+## 0.20 to 0.21
+
+We deprecated and reworked the way of testing with NgRx.
+The old format using `ngrxTesting` with `combineReducers` is now deprecated and replaced by the [new approach](./state-management.md#testing-ngrx-artifacts).
+The old testing mechanism will be removed in version 0.23.
+
+We introduced a way to do [shallow testing with feature toggles](../concepts/configuration.md#unit-testing-with-feature-toggles) and used it in the tests.
+
 ## 0.19.1 to 0.20
 
 We upgraded from Angular 8 to version 9 and activated the new rendering engine Ivy with this (following the [official upgrade guide](https://update.angular.io/#8.0:9.0l3)).

docs/guides/state-management.md

@@ -36,3 +36,37 @@ See [RxJS: Avoiding switchMap-Related Bugs](https://medium.com/angular-in-depth/
 ### Should I put XYZ into the Store or the Component?
 
 Follow the [SHARI-Principle](https://ngrx.io/docs#when-should-i-use-ngrx-for-state-management).
+
+## Testing NgRx Artifacts
+
+### Using the State Management in Tests
+
+With version 0.21 we introduced a new format for instantiating reducers and effects in `TestBed` for unit tests.
+Each store module now has a `forTesting` method which provides a selective subset of reducers to be instantiated for testing.
+The implementation is type safe and VSCode IntelliSense can be used:
+
+![Type safe forTesting](./state-management-fortesting-typesafe.png)
+
+If reducers for feature store modules are instantiated, the [CoreStoreModule][core-store-module] also has to be added to the `imports`.
+It takes care of initializing the [`StoreModule.forRoot`](https://ngrx.io/api/store/StoreModule#forroot).
+For more specific information consult the JSDoc of [CoreStoreModule][core-store-module].
+
+[core-store-module]: ../../src/app/core/store/core-store.module.ts
+
+### Reducers and Actions
+
+Actions are simple data structures that require no testing.
+Reducers are not part of the public API of the state management, so testing involves managing internals and should be kept to a minimum if not omitted at all.
+
+### Selectors
+
+Selectors in combination with Actions are part of the public API of the state management.
+The test should be composed as an integration test.
+A good model is to look at the store as a state machine, where actions trigger state transitions and selectors provide access to the new state.
+
+### Effects
+
+Effects implement business logic and should be tested individually.
+If they do not depend on the NgRx Store, no reducers have to be instantiated.
+For query interaction the new testing mechanism for [mocked stores](https://ngrx.io/guide/store/testing) can be used.
+If the Effect heavily interacts with the state management, store modules have to be instantiated with the `forTesting` approach.

docs/guides/testing-jest.md

@@ -328,7 +328,7 @@ Unused variables, classes and imports reduce the readability of unit tests.
 
 This way less code needs to be implemented which again increases readability of unit tests.
 Also mocks can be stubbed on time, depending on the current method.
-We decided to use _ts-mockito_ as the Test Mocking Framework.
+We decided to use [ts-mockito](https://github.com/NagRock/ts-mockito) as the Test Mocking Framework.
 
 ## Do not Change Implementation to Satisfy Tests
 
@@ -504,7 +504,7 @@ describe('Emitter', () => {
 ```
 
 As `EventEmitter` is `Observable`, subscribing to it might be the most logical way of testing it.
-We, however, would recommend using `ts-mockito` to increase readability.
+We, however, would recommend using [ts-mockito](https://github.com/NagRock/ts-mockito) to increase readability.
 The ways 1 and 2 portrait two options, we would recommend using the first one.
 
 |                                | 1 (preferred)                                                                                                                     | 2                                                                          | 3                                                                            |