feat(spectator): move spectator code into repo

Author: yharaskrik

nx.json

@@ -31,6 +31,9 @@
     "playground-e2e": {
       "tags": [],
       "implicitDependencies": ["playground"]
+    },
+    "spectator": {
+      "tags": []
     }
   },
   "workspaceLayout": {

packages/spectator/.eslintrc

@@ -0,0 +1 @@
+{ "extends": "../../.eslintrc", "rules": {}, "ignorePatterns": ["!**/*"] }

packages/spectator/README.md

@@ -0,0 +1,168 @@
+<h1 align="center">Welcome to nest-spectator 👋</h1>
+<p>
+  <a href="https://www.npmjs.com/package/nest-spectator" target="_blank">
+    <img alt="Version" src="https://img.shields.io/npm/v/nest-spectator.svg">
+  </a>
+  <a href="#" target="_blank">
+    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" />
+  </a>
+</p>
+
+> Auto-mocking for Nestjs providers
+
+### 🏠 [Homepage](https://www.npmjs.com/package/nest-spectator)
+
+## Author
+
+👤 **Jay Bell <[email protected]>**
+
+## Usage
+
+See `packages/nest-spectator/__tests__` for reference:
+
+Let's assume you we have the following 2 different Nestjs services:
+
+```
+@Injectable()
+class PrimaryService {
+  constructor(secondaryService: SecondaryService) {
+  }
+
+  testFunction(): string {
+    return 'test';
+  }
+}
+```
+
+and
+
+```
+@Injectable()
+class SecondaryService {
+}
+```
+
+and this controller:
+
+```
+@Controller()
+class PrimaryController {
+  constructor(primaryService: PrimaryService) {
+  }
+}
+```
+
+Currently we have something like:
+
+```
+import { Test } from '@nestjs/testing';
+import { PrimaryController } from './primary.controller';
+import { PrimaryService } from './primary.service';
+import { SecondaryService } from './secondary.service';
+
+describe('PrimaryController', () => {
+  let primaryController: PrimaryController;
+  let primaryService: PrimaryService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+        controllers: [PrimaryController],
+        providers: [PrimaryService, SecondaryService],
+      }).compile();
+
+    primaryService = module.get<PrimaryService>(PrimaryService);
+    primaryController = module.get<PrimaryController>(PrimaryController);
+  });
+});
+```
+
+Which is fine for small projects but as your code base grows you could have many injections in your classes constructor that you are testing.
+Assuming you plan on creating mocks for the services injected into `PrimaryController` classes or you want to spy on the classes methods of `PrimaryService` your code can start to grow more and more for each time you have a new spec file.
+
+If you do not mock our your services and instead just want to spy on them, your spec files will grow very large because each service you provider in the `Test.createTestingModule` will need to have all of it's services injected as well.
+
+You can see the effect of this in the sample above, `SecondaryService` is injected because `PrimaryService` injects it which in turn is injected into `PrimaryController`
+
+If you are wanting to create mocks for each of these services injected in your class being tested then it would look something like this:
+
+```
+import { Test } from '@nestjs/testing';
+import { PrimaryController } from './primary.controller';
+import { PrimaryService } from './primary.service';
+import { SecondaryService } from './secondary.service';
+
+const mockPrimaryService = {
+    testFunction: () => {}
+}
+
+class MockPrimaryService {
+    testFunction(): void {
+    }
+}
+
+describe('PrimaryController', () => {
+  let primaryController: PrimaryController;
+  let primaryService: PrimaryService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+        controllers: [PrimaryController],
+        providers: [
+            {provide: PrimaryService, useValue: mockPrimaryService}
+            // OR
+            {provide: PrimaryService, useClass: MockPrimaryService}
+        ],
+      }).compile();
+
+    primaryService = module.get<PrimaryService>(PrimaryService);
+    primaryController = module.get<PrimaryController>(PrimaryController);
+  });
+});
+```
+
+Now you will have to maintain these mock objects for each of your services and ensure you provide over your implementation services in each of your spec files.
+
+This is where `nest-spectator` comes in, inspired by [@ngneat/spectator](https://github.com/ngneat/spectator) for Angular, `nest-spectator` creates a layer on top of the `@nestjs/testing`
+`Test.creatingTestingModule` to provide the functionality to auto mock your services so that your module instantiation in tests turns into:
+
+```
+beforeEach(async () => {
+  module = await createTestingModuleFactory(
+      {
+        imports: [],
+        controllers: [PrimaryController],
+        providers: [PrimaryService],
+        mocks: [PrimaryService]
+      },
+  ).compile();
+});
+```
+
+The `createTestingModuleFactory` accepts all the same values as the `Test.createTestingModule` function except that there is an option property `mocks?: Array<Type<any>>`
+that will accept the providers you want to auto mock. This function will return the same value (`TestingModuleBuilder`) as `Test.createTestingModule` will which means we just call
+`.compile()` on it after to get our testing module.
+
+If we need access to our services provided to this testing module we get them the same way as we would before since we just have a `TestingModule`.
+
+```
+const primaryService = module.get<PrimaryService>(PrimaryService);
+```
+
+If `PrimaryService` was included in the `mocks` array during test module instantiation than it will be an object that mirrors the structure of your class as if it was provided normally except
+that the methods, getters and setters will all be `jest` Spys themselves.
+
+When providing `PrimaryService` in the mocks array and using `module.get<T>(T)` to get the instance of the provider it will return `SpyObject<PrimaryService>` instead of just `PrimaryService`.
+
+This package is still in alpha so there way be unintended side effects or gaps in the logic. If there is anything you would like to see include please feel free to open an issue.
+
+## 🤝 Contributing
+
+Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](https://github.com/yharaskrik/nest-testing/issues). You can also take a look at the [contributing guide](https://www.npmjs.com/package/nest-spectator/blob/master/CONTRIBUTING.md).
+
+## Show your support
+
+Give a ⭐️ if this project helped you!
+
+---
+
+_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_

packages/spectator/jest.config.js

@@ -0,0 +1,14 @@
+module.exports = {
+  name: 'spectator',
+  preset: '../../jest.config.js',
+  globals: {
+    'ts-jest': {
+      tsConfig: '<rootDir>/tsconfig.spec.json',
+    },
+  },
+  transform: {
+    '^.+\\.[tj]sx?$': 'ts-jest',
+  },
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
+  coverageDirectory: '../../coverage/packages/spectator',
+};

packages/spectator/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nestjs-addons/spectator",
+  "version": "0.0.11",
+  "description": "Auto-mocking for Nestjs providers",
+  "author": "Jay Bell <[email protected]>",
+  "homepage": "https://www.npmjs.com/package/nest-spectator",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "directories": {
+    "lib": "lib",
+    "test": "__tests__"
+  },
+  "files": [
+    "lib"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nestjs-addons/platform"
+  },
+  "bugs": {
+    "url": "https://github.com/nestjs-addons/platform"
+  },
+  "keywords": [
+    "nestjs",
+    "nest",
+    "typescript",
+    "testing",
+    "jest"
+  ]
+}

packages/spectator/src/index.ts

@@ -0,0 +1,2 @@
+export * from './lib/testing-module';
+export * from './lib/mock';

packages/spectator/src/lib/internal/merge.ts

@@ -0,0 +1,11 @@
+import { OptionalsRequired } from '../types';
+
+/**
+ * @internal
+ */
+export function merge<T>(
+  defaults: OptionalsRequired<T>,
+  overrides?: T,
+): Required<T> {
+  return { ...defaults, ...overrides } as Required<T>;
+}

packages/spectator/src/lib/mock.ts

@@ -0,0 +1,133 @@
+/** Credit to: Valentin Buryakov
+ * @ngneat/spectator - https://github.com/ngneat/spectator
+ */
+import { Provider, Type } from '@nestjs/common';
+import { FactoryProvider } from '@nestjs/common/interfaces';
+
+type Writable<T> = { -readonly [P in keyof T]: T[P] };
+
+/**
+ * @publicApi
+ */
+export type BaseSpyObject<T> = T &
+  { [P in keyof T]: T[P] extends Function ? T[P] & CompatibleSpy : T[P] } & {
+    /**
+     * Casts to type without readonly properties
+     */
+    castToWritable(): Writable<T>;
+  };
+
+/**
+ * @publicApi
+ */
+export interface CompatibleSpy extends jasmine.Spy {
+  /**
+   * By chaining the spy with and.returnValue, all calls to the function will return a specific
+   * value.
+   */
+  andReturn(val: any): void;
+
+  /**
+   * By chaining the spy with and.callFake, all calls to the spy will delegate to the supplied
+   * function.
+   */
+  andCallFake(fn: Function): this;
+
+  /**
+   * removes all recorded calls
+   */
+  reset(): void;
+}
+
+/**
+ * @publicApi
+ */
+export type SpyObject<T> = BaseSpyObject<T> &
+  {
+    [P in keyof T]: T[P] &
+      (T[P] extends (...args: any[]) => infer R ? jest.Mock<R> : T[P]);
+  };
+
+/**
+ * @internal
+ */
+export function installProtoMethods<T>(
+  mock: any,
+  proto: any,
+  createSpyFn: Function,
+): void {
+  if (proto === null || proto === Object.prototype) {
+    return;
+  }
+
+  for (const key of Object.getOwnPropertyNames(proto)) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+
+    if (!descriptor) {
+      continue;
+    }
+
+    if (
+      typeof descriptor.value === 'function' &&
+      key !== 'constructor' &&
+      typeof mock[key] === 'undefined'
+    ) {
+      mock[key] = createSpyFn(key);
+    } else if (descriptor.get && !mock.hasOwnProperty(key)) {
+      Object.defineProperty(mock, key, {
+        set: (value) => (mock[`_${key}`] = value),
+        get: () => mock[`_${key}`],
+      });
+    }
+  }
+
+  installProtoMethods(mock, Object.getPrototypeOf(proto), createSpyFn);
+
+  mock.castToWritable = () => mock;
+}
+
+/**
+ * @publicApi
+ */
+export function createSpyObject<T>(
+  type: Provider<T> & { prototype: T },
+  template?: Partial<Record<keyof T, any>>,
+): SpyObject<T> {
+  const mock: any = { ...template } || {};
+
+  installProtoMethods(mock, type.prototype, () => {
+    const jestFn = jest.fn();
+    const newSpy: CompatibleSpy = jestFn as any;
+
+    newSpy.andCallFake = (fn: Function) => {
+      jestFn.mockImplementation(fn as (...args: any[]) => any);
+
+      return newSpy;
+    };
+
+    newSpy.andReturn = (val: any) => {
+      jestFn.mockReturnValue(val);
+    };
+
+    newSpy.reset = () => {
+      jestFn.mockReset();
+    };
+
+    return newSpy;
+  });
+
+  return mock;
+}
+
+/**
+ * @publicApi
+ */
+export function mockProvider<T>(
+  type: Type<T>,
+  properties?: Partial<Record<keyof T, any>>,
+): FactoryProvider {
+  return {
+    provide: type,
+    useFactory: () => createSpyObject(type, properties),
+  };
+}