Mocktory (beta)

A mock manager for Node.js applications that combines msw interceptors with Redis-based persistence.

Mocktory simplifies mock management for DEV/QA/AQA teams, enabling real-time scenario simulation and system testing.

While MSW lets you define mocks in code, Mocktory supports both code-based and real-time mock definitions.

Features

• Real-time requests retrospective: track all outgoing HTTP requests from a Node.js application in history.
• Mocking: manipulate responses in real-time, setting scenarios like failure, success, or passthrough.
• [WIP]: ability to save responses to storage for later use.
• [WIP]: group set of mocks into scenarios to simplify test preparation.
• [WIP]: providing a UI for managing mocks and history.

Temporary UI replaced by Swagger. 👉 See live example about Mocktory features

Roadmap

• [WIP] Offer default enhancers for feature IDs that have unique factors apart from the basic URL.

v1 release

• Transform Swagger to a nice UI.
• Provide more granular control of history TTL and other system parameters.

v1+ releases

• Allow saving requests to custom storage (like S3).
• Get rid of MSW and use smaller @mswjs/interceptors

Installation

1npm install mocktory

Usage

Enable Mocktory in your application

1import { MockService } from 'mocktory'
2
3const ms = new MockService({
4  // Define a base path to serve docs,
5  // docs will be available at /api/mock-service/docs
6  basePath: '/api/mock-service',
7
8  redis: { host: config.redis.host, port: config.redis.port },
9
10  // Optional, the "history" feature will use it to aggregate all requests by this predicate.
11  // It could be a request ID, generated by AsyncLocalStorage.
12  requestAggKey: () => AppContext.getRequestId(),
13
14  // Define a pattern to import files with default mocks.
15  filesPattern: '**/modules/**/*.mocking*',
16
17  // Blacklist annoying requests to prevent them from appearing in history.
18  // You can also change it in real-time.
19  reqBlacklist: [
20    /sqs.*amazonaws.com/,
21    /s3.*amazonaws.com/,
22    /sns.*amazonaws.com/,
23  ],
24})
25
26// It's possible to subscribe to various events.
27ms.events.on('mock:set', ({ id, body }) =>
28  logger.debug(`Mock set: ${id} with body:`, body),
29)
30
31// And more events:
32ms.events.on('mock:drop', () => {})
33ms.events.on('mock:drop-all', () => {})
34
35ms.events.on('request:intercepted', () => {})
36ms.events.on('request:match-custom-mock', () => {})
37ms.events.on('request:match-custom-passthrough', () => {})
38ms.events.on('request:match-default', () => {})
39ms.events.on('request:passthrough', () => {})
40
41ms.events.on('error', (err) => logger.error(err))

Define mocks

You can optionally define default mocks in your application. They are very similar to MSW mocks.

1// github-api.mocking.ts
2import { http, HttpResponse } from 'mocktory'
3
4const api = http.setup('https://api.github.com')
5
6// Note: `http.responseJSON` construction is prefferable here,
7// since we can then easily show to QA/AQA user default response mock for better guide them.
8api.get(`/repos/*`, http.responseJSON(null))
9
10// Note: `http.responseJSON` supports templating from request body via {{requestBody}}.
11// So you can still omit writing custom method
12api.post(
13  `/orgs/${config.orgName}/repos`,
14  http.responseJSON({ name: '{{requestBody.name}}' }),
15)
16
17// Same generic type support as in MSW
18api.post<{}, {}, {}>(
19  `/repos/issues`,
20  // You can still write custom response method, for end user it will be shown as "Custom response"
21  async ({ request }) => {
22    const body = await request.getRequest().json()
23
24    // ...
25
26    return HttpResponse.json({})
27  },
28)

Realtime mocks can be set via the API:

1curl -X 'POST' \
2  '<your project server url>/api/mock-service/mock/{feautureId}' \
3  -H 'accept: */*' \
4  -H 'Content-Type: application/json' \
5  -d '{
6  "pattern": "PASSTHROUGH"
7}'

For more examples and patterns, see Swagger docs at /api/mock-service/docs.