Nest Swagger Mock

Mocking Interceptor for @nest/swagger base on decorators.

📦 Install

## use npm
npm install reflect-metadata nest-swagger-mocker

## or, use yarn
yarn add reflect-metadata nest-swagger-mocker

📺 Base Usage

use interceptors in your code

// main.ts
import { NestFactory } from '@nestjs/core'
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
import { MockInterceptorFactory } from 'nest-swagger-mocker'

const app = await NestFactory.create(AppModule)
const options = new DocumentBuilder()
const swaggerDocument = SwaggerModule.createDocument(app, options)

app.useGlobalInterceptors(
  MockInterceptorFactory.create({
    document: swaggerDocument,
  }),
)

testing with curl

## by default, when the request has a header x-mock:true, the mock feature will be activated
curl --location --request GET 'https://foo.bar.com/your-api-path' \
--header 'x-mock: true'

🔥 Features

• 👼 Out of the box and ready to use，automatically construct mock responses based on swagger annotation information
• 😃 You can use some built-in decorators to customize the construction rules for mock responses
• 🫡 Internally using fakerjs, you can freely manipulate faker instances to implement features such as i18n
• 👏 Customize the timing of returning mock responses
• 🏋️‍♂️ Supported swagger annotation:
  • type: string, number, boolean, object, array, enum, {class}
  • default, example, examples
  • allof (all schema will be merge)
  • oneof (one of schema will be used)
  • anyof (Randomly select one or more schema to merge)

🎮 API Refrence

MockInterceptorFactory

create

Create an MockInterceptor for NestJs app.

Parameters

| Name | Type | Default | Description | | ---------------------------------------- | ---------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | | options? | { ... } | | The options to use. | | options.shouldMockChecker? | (context: ExecutionContext) => boolean | context => context.switchToHttp().getRequest().headers['x-mock'] === 'true' } | A function to determine if a mock response is used to return results. Providing the NestInterceptor standard ExecutionContext as a param. By default, read the x-mock in the request header. | | options.logger? | LoggerService | console | The NestJS logger to be used. | | options.fakerOptions? | { ... } | | This lib use fakerjs as core, we can set up some options for fakerjs. | | options.fakerOptions.defaultProbability? | number | 0.9 | Default probability for faker.maybe. (fake.maybe will be used when the property is not required to have value) Should be 0~1, the larger the number is, the greater the possibility that the optional attribute has a value | | options.fakerOptions.setup? | (faker: Faker) => void | () => null | By this function you can do something with the faker instance. For example, faker.setLocale() |

Returns: MockInterceptor

Decorators

FakeString

Defines the rules for generating a mock string.

Parameters

| Name | Type | Default | Description | | ---------------------- | ------------------------------------------------------ | ------------------- | ------------------------------------------------------------ | | options? | FakeStringOptions | { type: 'default' } | | | options.type? | 'default' | 'uuid' |'template' |'words' | 'random' | 'default' | 1. if 'random' is specified, the string will containing UTF-16 chars between 33 and 125 (! to }).2. if 'template' is specified the string will be generated by the given template.3. if 'words' or 'default' is specified, the string will be with a set of random words.4. if 'uuid' is specified, the string will be a v4 uuid | | options.minLength? | number | | min length of the random string | | options.maxLength? | number | 5 | max length of the random string | | options.minWordsCount? | number | | min word number of the random string | | options.maxWordsCount? | number | 5 | max word number of the random string |

FakeNumber

Defines the rules for generating a mock number.

Parameters

| Name | Type | Default | Description | | ------------------ | ------------------- | ------------------- | ------------------------------------------------------------ | | options? | FakeNumberOptions | | | | options.min? | number | 0 | lower bound for generated number | | options.max? | number | options.min + 99999 | upper bound for generated number | | options.precision? | number | 0.01 | precision of the generated number, only works when 'isFloat' is true and should be less than 1 | | options.isFloat? | boolean | false | whether the number can be a float |

FakeBoolean

Defines the rules for generating a mock boolean.

Parameters

| Name | Type | Default | Description | | ------------------- | --------------------- | ------- | -------------------------- | | options? | IFakeBooleanOptions | | | | options.probability | number | 0.5 | the probability of be true |

ArrayCount

Defines the rule of how many array items will be

Parameters

| Name | Type | Default | Description | | -------- | ------ | -------- | ----------- | | minCount | number | 3 | | | maxCount | number | minCount | |

FakeArrayItemClassType

Set the type(non-primitive-type) of the item of the array. You will need this when you want to generate a mock response for an object array because typescript(<=4.8) will not decorate the type of the array item and the mock rule is base on metadata.

Parameters

| Name | Type | Default | Description | | ---- | ------------------------------------------------ | ------- | ---------------------- | | type | { new (...args: any[]): any; prototype: Object } | | The type of array item |

AfterHook

Register a hook function to operate the response value after the mock generator generates the mock response value.

Parameters

| Name | Type | Default | Description | | ---- | -------------------------------- | ------- | ------------------------------------ | | hook | (response: TResponse) => unknown | | the function to operate the response |

CustomMocking

If you need to customize the mock rule instead of using the mock function provided by this library, you can use this function to specify how the mock value is generated.

Parameters

| Name | Type | Default | Description | | --------------- | --------------------------- | ------- | ------------------------------------------------------- | | mockingFunction | (faker: Faker) => TResponse | | the function to specify how the mock value is generated |

FakeProperty

This library works based on metadata, but if a property is not decorated with any decorator, typescript will not emit metadata for it, so we need to use this decorator to mark a property when we want to mock it when there is not any decorator else. Otherwise, the property will be ignored and mocked to {}.

Parameters

N/A

🔄 Mock processes

❓Q&A

In some case the mock rule decorators can not work and I got some warning begin with 'Cannot find metadata for...'

Without manual marking, TypeScript's metadata reflection system has several limitations which make it impossible to, for instance, determine what type an object array which marked by class (The only thing the reflection system knows is the array is constructed by normal function). However, the mock rule feature of this library works based on metadata, and in these cases, this library cannot get enough information from the swagger's annotations or metadata, and some auxiliary decorators can help to supplement the information, these decorators are:

• FakeArrayItemClassType
• FakeExtraClassTypes
• FakeProperty

My required: false mark does not working fine when the object only has optional property

This lib works based on swagger itself, when all property is optional, swagger will remove the require array instead of keeping it an empty array from the schema, so the lib can not judge when to make property optional. You can use @FakeOptional instead.

🌰 Example Nest Project

If you are not using nest cli swagger plugin

If you are using nest cli swagger plugin

🖇 Compare with independent mocking server

If you are using an independent mocking server:

• The mocking config may be outside your app git repository which may lead to logical fragmentation
• Nest Guards/Interceptor/Pipe/Middleware/Filter/Router will not work for the mocking server, so some verification, conversion, and inspection will not work
• May need to solve cross-domain problems
• Need to maintain the mapping between swagger annotations and mock rules manually

🧪 Project Testing

This project is tested by e2e-tesing with @nestjs/core and @nestjs/swagger 6.1.2.

📄 License

MIT