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

npm install mocktory

Usage

Enable Mocktory in your application

import { MockService } from 'mocktory'

const ms = new MockService({
  // Define a base path to serve docs,
  // docs will be available at /api/mock-service/docs
  basePath: '/api/mock-service',

  redis: { host: config.redis.host, port: config.redis.port },

  // Optional, the "history" feature will use it to aggregate all requests by this predicate.
  // It could be a request ID, generated by AsyncLocalStorage.
  requestAggKey: () => AppContext.getRequestId(),

  // Define a pattern to import files with default mocks.
  filesPattern: '**/modules/**/*.mocking*',

  // Blacklist annoying requests to prevent them from appearing in history.
  // You can also change it in real-time.
  reqBlacklist: [
    /sqs.*amazonaws.com/,
    /s3.*amazonaws.com/,
    /sns.*amazonaws.com/,
  ],
})

// It's possible to subscribe to various events.
ms.events.on('mock:set', ({ id, body }) =>
  logger.debug(`Mock set: ${id} with body:`, body),
)

// And more events:
ms.events.on('mock:drop', () => {})
ms.events.on('mock:drop-all', () => {})

ms.events.on('request:intercepted', () => {})
ms.events.on('request:match-custom-mock', () => {})
ms.events.on('request:match-custom-passthrough', () => {})
ms.events.on('request:match-default', () => {})
ms.events.on('request:passthrough', () => {})

ms.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.

// github-api.mocking.ts
import { http, HttpResponse } from 'mocktory'

const api = http.setup('https://api.github.com')

// Note: `http.responseJSON` construction is prefferable here,
// since we can then easily show to QA/AQA user default response mock for better guide them.
api.get(`/repos/*`, http.responseJSON(null))

// Note: `http.responseJSON` supports templating from request body via {{requestBody}}.
// So you can still omit writing custom method
api.post(
  `/orgs/${config.orgName}/repos`,
  http.responseJSON({ name: '{{requestBody.name}}' }),
)

// Same generic type support as in MSW
api.post<{}, {}, {}>(
  `/repos/issues`,
  // You can still write custom response method, for end user it will be shown as "Custom response"
  async ({ request }) => {
    const body = await request.getRequest().json()

    // ...

    return HttpResponse.json({})
  },
)

Realtime mocks can be set via the API:

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

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