Merge pull request #2340 from omermorad/master

docs(recipes): add recipe for automock library

Author: kamilmysliwiec

content/recipes/automock.md

@@ -0,0 +1,167 @@
+### Automock
+
+Automock is a standalone library for unit testing. Using TypeScript Reflection
+API (`reflect-metadata`) internally to produce mock objects, Automock streamlines
+test development by automatically mocking class external dependencies.
+> info **info** `Automock` is a third party package and is not managed by the NestJS core team.
+> Please, report any issues found with the library in the [appropriate repository](https://github.com/omermorad/automock)
+
+#### Introduction
+
+The dependency injection (DI) container is an essential component of the Nest module system.
+This container is utilized both during testing, and the application execution.
+Unit tests vary from other types of tests, such as integration tests, in that they must
+fully override providers/services within the DI container. External class dependencies
+(providers) of the so-called "unit", have to be totally isolated. That is, all dependencies
+within the DI container should be replaced by mock objects.
+As a result, loading the target module and replacing the providers inside it is a process
+that loops back on itself. Automock tackles this issue by automatically mocking all the
+class external providers, resulting in total isolation of the unit under test.
+
+#### Installation
+
+```bash
+$ npm i -D @automock/jest
+```
+
+Automock does not require any additional setup.
+
+> info **info** Jest is the only test framework currently supported by Automock.
+Sinon will shortly be released.
+
+#### Example
+
+Consider the following cats service, which takes three constructor parameters:
+
+```ts
+@@filename(cats.service)
+import { Injectable } from '@nestjs/core';
+
+@Injectable()
+export class CatsService {
+  constructor(
+    private logger: Logger,
+    private httpService: HttpService,
+    private catsDal: CatsDal,
+  ) {}
+
+  async getAllCats() {
+    const cats = await this.httpService.get('http://localhost:3000/api/cats');
+    this.logger.log('Successfully fetched all cats');
+    
+    this.catsDal.saveCats(cats);
+  }
+}
+```
+
+The service contains one public method, `getAllCats`, which is the method
+we use an example for the following unit test:
+
+```ts
+@@filename(cats.service.spec)
+import { TestBed } from '@automock/jest';
+import { CatsService } from './cats.service';
+
+describe('CatsService unit spec', () => {
+  let underTest: CatsService;
+  let logger: jest.Mocked<Logger>;
+  let httpService: jest.Mocked<HttpService>;
+  let catsDal: jest.Mocked<CatsDal>;
+  
+  beforeAll(() => {
+    const { unit, unitRef } = TestBed.create(CatsService)
+      .mock(HttpService)
+      .compile();
+
+    underTest = unit;
+
+    logger = unitRef.get(Logger);
+    httpService = unitRef.get(HttpService);
+    catsDal = unitRef.get(CatsDal);
+  });
+
+  describe('when getting all the cats', () => {
+    test('then meet some expectations', async () => {
+      httpService.mockResolvedValueOnce([{ id: 1, name: 'Catty' }]);
+      await catsService.getAllCats();
+
+      expect(logger.log).toBeCalled();
+      expect(catsDal).toBeCalledWith([{ id: 1, name: 'Catty' }]);
+    });
+  });
+});
+```
+
+> info **info** The jest.Mocked<Source> utility type returns the Source type
+> wrapped with type definitions of Jest mock function. ([reference](https://jestjs.io/docs/mock-function-api/#jestmockedsource))
+
+#### About `unit` and `unitRef`
+
+Let's examine the following code:
+
+```typescript
+const { unit, unitRef } = TestBed.create(CatsService).compile();
+```
+
+Calling `.compile()` returns an object with two properties, `unit`, and `unitRef`.
+
+**`unit`** is the unit under test, it is an actual instance of class being tested.
+
+**`unitRef`** is the "unit reference", where the mocked dependencies of the tested class
+are stored, in a small container. The container's `.get()` method returns the mocked
+dependency with all of its methods automatically stubbed (using `jest.fn()`):
+
+```typescript
+const { unit, unitRef } = TestBed.create(CatsService).compile();
+
+let httpServiceMock: jest.Mocked<HttpService> = unitRef.get(HttpService);
+```
+
+> info **info** The `.get()` method can accept either a `string` or an actual class (`Type`) as its argument.
+> This essentially depends on how the provider is being injected to the class under test.
+
+#### Working with different providers
+Providers are one of the most important elements in Nest. You can think of many of
+the default Nest classes as providers, including services, repositories, factories,
+helpers, and so on. A provider's primary function is to take the form of an
+`Injectable` dependency.
+
+Consider the following `CatsService`, it takes one parameter, which is an instance
+of the following `Logger` interface:
+
+```typescript
+export interface Logger {
+  log(message: string): void;
+}
+
+export class CatsService {
+  constructor(private logger: Logger) {}
+}
+```
+
+TypeScript's Reflection API does not support interface reflection yet.
+Nest solves this issue with string-based injection tokens (see [Custom Providers](https://docs.nestjs.com/fundamentals/custom-providers)):
+
+```typescript
+export const MyLoggerProvider = {
+  provide: 'MY_LOGGER_TOKEN',
+  useValue: { ... },
+}
+
+export class CatsService {
+  constructor(@Inject('MY_LOGGER_TOKEN') private readonly logger: Logger) {}
+}
+```
+
+Automock follows this practice and lets you provide a string-based token instead
+of providing the actual class in the `unitRef.get()` method:
+
+```typescript
+const { unit, unitRef } = TestBed.create(CatsService).compile();
+
+let loggerMock: jest.Mocked<Logger> = unitRef.get('MY_LOGGER_TOKEN');
+```
+
+#### More Information
+Visit [Automock GitHub repository](https://github.com/omermorad/automock) for more
+information.

src/app/homepage/menu/menu.component.ts

@@ -240,6 +240,7 @@ export class MenuComponent implements OnInit {
         { title: 'Prisma', path: '/recipes/prisma' },
         { title: 'Serve static', path: '/recipes/serve-static' },
         { title: 'Commander', path: '/recipes/nest-commander' },
+        { title: 'Automock', path: '/recipes/automock' },
       ],
     },
     {

src/app/homepage/pages/recipes/automock/automock.component.ts

@@ -0,0 +1,9 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { BasePageComponent } from '../../page/page.component';
+
+@Component({
+  selector: 'app-automock',
+  templateUrl: './automock.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AutomockComponent extends BasePageComponent {}

src/app/homepage/pages/recipes/recipes.module.ts

@@ -16,6 +16,7 @@ import { SqlTypeormComponent } from './sql-typeorm/sql-typeorm.component';
 import { TerminusComponent } from './terminus/terminus.component';
 import { RouterModuleComponent } from './router-module/router-module.component';
 import { NestCommanderComponent } from './nest-commander/nest-commander.component';
+import { AutomockComponent } from './automock/automock.component';
 
 const routes: Routes = [
   {
@@ -100,6 +101,11 @@ const routes: Routes = [
     component: ReplComponent,
     data: { title: 'REPL' },
   },
+  {
+    path: 'automock',
+    component: AutomockComponent,
+    data: { title: 'Automock' },
+  },
 ];
 
 @NgModule({
@@ -118,6 +124,7 @@ const routes: Routes = [
     RouterModuleComponent,
     ServeStaticComponent,
     NestCommanderComponent,
+    AutomockComponent,
     ReplComponent,
   ],
 })