From a4b6f0af99ed4e22e4789d076fd70ff0ac397529 Mon Sep 17 00:00:00 2001 From: omermorad Date: Fri, 23 Jul 2021 18:12:21 +0300 Subject: [PATCH] chore(repo): update docs and sample --- README.md | 64 ++++----- packages/generator/README.md | 122 ++++++++++++++---- sample/mockingbird-typeorm/jest.config.js | 9 ++ sample/mockingbird-typeorm/package.json | 2 +- .../src/user.controller.ts | 2 +- .../mockingbird-typeorm/test/app-e2e.test.ts | 2 +- 6 files changed, 144 insertions(+), 57 deletions(-) create mode 100644 sample/mockingbird-typeorm/jest.config.js diff --git a/README.md b/README.md index 8173c23..5ed5bee 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@ [![ISC license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) [![npm version](http://img.shields.io/npm/v/mockingbird-ts.svg?style=flat)](https://npmjs.org/package/mockingbird-ts "View this project on npm") [![Codecov Coverage](https://img.shields.io/codecov/c/github/omermorad/mockingbird-ts/master.svg?style=flat-square)](https://codecov.io/gh/omermorad/mockingbird-ts) -[![Master](https://github.com/omermorad/mockingbird-ts/actions/workflows/release.yml/badge.svg?branch=release)](https://github.com/omermorad/mockingbird-ts/actions) -[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) +[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)

Mockingbird Logo @@ -10,7 +9,7 @@

Mockingbird

- Decorator Powered TypeScript Library for Creating Mocks + The First TypeScript Mocking Framework

@@ -19,10 +18,9 @@

## Installation -Install the package alongside `faker` and `@types/faker` peer dependencies: ```bash -npm i generator faker @types/faker +npm i -D mockingbird-ts ``` ## Usage @@ -35,7 +33,7 @@ import { Mock, MockFactory } from 'mockingbird-ts'; class Dog { @Mock(faker => faker.name.firstName()) readonly name: string; - + @Mock() readonly birthday: Date; // Will generate a recent date @@ -43,7 +41,8 @@ class Dog { readonly goodPoints: number; // Will generate a random number } -const result = MockFactory.create(Dog); +const oneDog = MockFactory(Dog).one(); +const lotsOfDogs = MockFactory(Dog).many(3); ``` ## Documentation @@ -51,42 +50,47 @@ const result = MockFactory.create(Dog); There are many more options that you can use with the `@Mock` decorator (and also the `MockFactory`). \ [Click here to jump to the full documentation and explore the full API](https://github.com/omermorad/faker.ts/blob/master/docs/README.md) -**Besides, we have also created a full working example for you; [you can find it under -the sample folder](https://github.com/omermorad/mockingbird-ts/tree/master/sample)** - +**Besides, we have also created a full working example for +you; [you can find it under the sample folder](https://github.com/omermorad/mockingbird-ts/tree/master/sample)** ## Playground -**We have created a [REPL Playground](https://repl.it/@omermorad/Mockingbird-Playground) where you can see Mockingbird in action!** + +**We have created a [REPL Playground](https://repl.it/@omermorad/Mockingbird-Playground) where you can see Mockingbird +in action!** + +## Use Cases + - Generate fake (but reasonable) data for your integration tests + - Prepare as many of different fixtures for your tests + - Persist the ## Motivation -When it comes to writing unit tests of large projects containing different and -diverse entities, mocks are widely used to simulate real data. -Creating mocks can be a tedious and cumbersome process and is usually created -manually or by using libraries like Faker or Chance, which also do not offer a complete solution, -especially not when deciding to develop in TypeScript and most of the code becomes object oriented. +When it comes to writing tests of large projects containing different and diverse entities, mocks (sometimes called " +fixtures") are widely used to simulate real data. -Therefore, we thought of a convenient and efficient solution that allows the use -of only one decorator, Mock decorator that allows to create mocks by placing it above the properties of the class. +Creating mocks (or fixtures) can be a tedious and cumbersome process and is usually created manually or by using +libraries like Faker or Chance, which also do not offer a complete solution, especially not when you write TypeScript +only, and most of the code is object-oriented and arranged with classes. -Mockingbird offers several options for creating mocks, including the use of the -well-known library Faker, which allows you to create information such as a fake email, a fake username, -a fake address and more. +We came up with a simple (and efficient) yet super convenient solution: all you have to do to get fixtures out of the +box is to decorate your classes (whether it's an entity, or a model representing the database layer) and generate simple +or complex fixtures. -### What is faker.js (aka Faker)? -For those of you who are unfamiliar with `faker.js`, it is an old library written -with pure JavaScript, which is used to "generate massive amounts of fake data in -the browser and Node". +Mockingbird offers several options for creating mocks, including the use of the well-known library Faker, which allows +you to create data such as a fake email, a fake username, a fake address and more.u to create information such as a fake +email, a fake username, a fake address and more. -Fake data is usually needed for testing purposes, to assist in the development process itself, -and sometimes, also for the purpose of demonstrations and training. +### What is `faker.js` (aka Faker)? -Mockingbird uses Faker under the hood and making it possible to use faker.js in -a "TypeScript" way, and thereby allows to create mocks that are meaningful like -email, first name, address and many more. +For those of you who are unfamiliar with `faker.js`, it is a library which is used to "generate massive amounts of fake data in the browser and Node". + +Mockingbird uses `faker.js` under the hood, making it possible to use Faker in it's "TypeScript" way, and thereby allows +to create mocks that are meaningful like email, first name, address and many more. ## License + Distributed under the MIT License. See `LICENSE` for more information. ## Acknowledgements + [faker.js](https://github.com/marak/Faker.js) diff --git a/packages/generator/README.md b/packages/generator/README.md index 4587ccd..2348458 100644 --- a/packages/generator/README.md +++ b/packages/generator/README.md @@ -18,6 +18,7 @@

## Installation + ```bash npm i -D mockingbird-ts ``` @@ -32,7 +33,7 @@ import { Mock, MockFactory } from 'mockingbird-ts'; class Dog { @Mock(faker => faker.name.firstName()) readonly name: string; - + @Mock() readonly birthday: Date; // Will generate a recent date @@ -49,42 +50,115 @@ const lotsOfDogs = MockFactory(Dog).many(3); There are many more options that you can use with the `@Mock` decorator (and also the `MockFactory`). \ [Click here to jump to the full documentation and explore the full API](https://github.com/omermorad/faker.ts/blob/master/docs/README.md) -**Besides, we have also created a full working example for you; [you can find it under -the sample folder](https://github.com/omermorad/mockingbird-ts/tree/master/sample)** - +**Besides, we have also created a full working example for +you; [you can find it under the sample folder](https://github.com/omermorad/mockingbird-ts/tree/master/sample)** ## Playground -**We have created a [REPL Playground](https://repl.it/@omermorad/Mockingbird-Playground) where you can see Mockingbird in action!** + +**We have created a [REPL Playground](https://repl.it/@omermorad/Mockingbird-Playground) where you can see Mockingbird +in action!** + +## Use Cases + - Generate fake (but reasonable) data for your integration tests + - Generate fake (but reasonable) data for your seeding a database + - Prepare as many unique fixtures as you need for your tests + +#### How can Mockingbird help me? +Consider the following snippets: + +**`dog-model.ts`** + +```typescript +import { Mock, MockFactory } from 'mockingbird-ts'; + +export interface DogModel { + name: string; + birthday: Date; + goodPoints: number; +} + +export class DogModel { + @Mock(faker => faker.name.firstName()) + name: string; + + // Will generate a recent date + @Mock() + birthday: Date; + + // Will generate a random number + @Mock() + goodPoints: number; +} +``` + +**`dogs-integration.test.ts`** + +```typescript +import { DogsApiService } from './dogs-service'; +import { DogModel } from './dog-model'; + +describe('Dogs API Integration Test', () => { + // Assume we have dogs-service.ts that fetches from some API + const apiService: jest.Mocked = { + fetch: jest.fn(), + }; + + let dogs: DogModel[]; + + beforeAll(() => { + // Persist will return the same dogs every time + dogsMockRef = MockFactory(DogModel).persist(); + }); + + test('Test something you want', async () => { + dogs = dogsMockRef.many(3); // Generate 3 different dogs + apiService.fetch.mockResolvedValue(dogs); + + const resultFromApi = await apiService.fetch(); + expect(resultFromApi).toEqual(dogs); + }); + + test('Test something else you want', async () => { + dogsWithZeroPoints = dogsMockRef.stub({ goodPoints: 0 }).many(3); + apiService.fetch.mockResolvedValue(dogsWithZeroPoints); + + const resultFromApi = await apiService.fetch(); + + expect(resultFromApi).toEqual(dogsWithZeroPoints); + expect(dogsWithZeroPoints[0].goodPoints).toBe(0); + }); +}); +``` + ## Motivation -When it comes to writing unit tests of large projects containing different and -diverse entities, mocks are widely used to simulate real data. -Creating mocks can be a tedious and cumbersome process and is usually created -manually or by using libraries like Faker or Chance, which also do not offer a complete solution, -especially not when deciding to develop in TypeScript and most of the code becomes object oriented. +When it comes to writing tests of large projects containing different and diverse entities, mocks (sometimes called " +fixtures") are widely used to simulate real data. + +Creating mocks (or fixtures) can be a tedious and cumbersome process and is usually created manually or by using +libraries like Faker or Chance, which also do not offer a complete solution, especially not when you write TypeScript +only, and most of the code is object-oriented and arranged with classes. -Therefore, we thought of a convenient and efficient solution that allows the use -of only one decorator, Mock decorator that allows to create mocks by placing it above the properties of the class. +We came up with a simple (and efficient) yet super convenient solution: all you have to do to get fixtures out of the +box is to decorate your classes (whether it's an entity, or a model representing the database layer) and generate simple +or complex fixtures. -Mockingbird offers several options for creating mocks, including the use of the -well-known library Faker, which allows you to create information such as a fake email, a fake username, -a fake address and more. +Mockingbird offers several options for creating mocks, including the use of the well-known library Faker, which allows +you to create data such as a fake email, a fake username, a fake address and more.u to create information such as a fake +email, a fake username, a fake address and more. -### What is faker.js (aka Faker)? -For those of you who are unfamiliar with `faker.js`, it is an old library written -with pure JavaScript, which is used to "generate massive amounts of fake data in -the browser and Node". +### What is `faker.js` (aka Faker)? -Fake data is usually needed for testing purposes, to assist in the development process itself, -and sometimes, also for the purpose of demonstrations and training. +For those of you who are unfamiliar with `faker.js`, it is a library which is used to "generate massive amounts of fake data in the browser and Node". -Mockingbird uses Faker under the hood and making it possible to use faker.js in -a "TypeScript" way, and thereby allows to create mocks that are meaningful like -email, first name, address and many more. +Mockingbird uses `faker.js` under the hood, making it possible to use Faker in it's "TypeScript" way, and thereby allows +to create mocks that are meaningful like email, first name, address and many more. ## License + Distributed under the MIT License. See `LICENSE` for more information. ## Acknowledgements + [faker.js](https://github.com/marak/Faker.js) diff --git a/sample/mockingbird-typeorm/jest.config.js b/sample/mockingbird-typeorm/jest.config.js new file mode 100644 index 0000000..f42239b --- /dev/null +++ b/sample/mockingbird-typeorm/jest.config.js @@ -0,0 +1,9 @@ +module.exports = { + moduleFileExtensions: ['js', 'json', 'ts'], + rootDir: '.', + testRegex: '.test.ts$', + transform: { + '^.+\\.ts$': 'ts-jest', + }, + testEnvironment: 'node', +}; diff --git a/sample/mockingbird-typeorm/package.json b/sample/mockingbird-typeorm/package.json index 44f8a95..f5ac97f 100644 --- a/sample/mockingbird-typeorm/package.json +++ b/sample/mockingbird-typeorm/package.json @@ -15,7 +15,7 @@ "body-parser": "^1.19.0", "dotenv": "^8.2.0", "express": "^4.17.1", - "mockingbird-ts": "^1.1.0-next.1", + "mockingbird-ts": "^2.0.0-alpha.2", "mysql2": "^2.2.5", "reflect-metadata": "^0.1.13", "rimraf": "^3.0.2", diff --git a/sample/mockingbird-typeorm/src/user.controller.ts b/sample/mockingbird-typeorm/src/user.controller.ts index 87c8b2f..d459156 100644 --- a/sample/mockingbird-typeorm/src/user.controller.ts +++ b/sample/mockingbird-typeorm/src/user.controller.ts @@ -19,7 +19,7 @@ export function UserController(router: Router, repository: Repository): Ro }); router.get('/users/random', async (req: Request, res: Response) => { - const newUser = MockFactory.create(UserEntity); + const newUser = MockFactory(UserEntity).one(); const user = await repository.create(newUser); const result = await repository.save(user); diff --git a/sample/mockingbird-typeorm/test/app-e2e.test.ts b/sample/mockingbird-typeorm/test/app-e2e.test.ts index 369244e..e043d99 100644 --- a/sample/mockingbird-typeorm/test/app-e2e.test.ts +++ b/sample/mockingbird-typeorm/test/app-e2e.test.ts @@ -20,7 +20,7 @@ describe('Users App e2e Test', () => { })) as Connection; app = await applicationFactory(connection); - seededData = MockFactory.create(UserEntity, { count: 3 }); + seededData = MockFactory(UserEntity).toPlain().many(3); await connection.getRepository(UserEntity).insert(seededData); });