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/)
@@ -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);
});