mockemon v3.1.0

Installation

Install with your favorite package manager.

npm install mockemon

yarn add mockemon

bun add mockemon

The Mock Builder

The builder utility allows you to create strongly typed mocks for your tests, or anywhere else.

Configuration

To use the builder, you must first configure it. This is done by importing and calling configureMockBuilder

import { configureMockBuilder } from "mockemon/builder";
import { faker } from "@faker-js/faker";

const createMockBuilder = configureMockBuilder({
  // A value that will be passed as the argument to all mock builders.
  // This is often a faker instance, but can be anything.
  context: faker,
});

Usage

Once the builder is configured, you can start creating mock builders.

const buildPetOwner = createMockBuilder((f) => ({
  name: f.person.firstName(),
  pet: f.animal.cat(),
}));

The mock builder will automatically infer the type from the provided mock builder function.

const petOwner = buildPetOwner();
// { name: string, pet: string }

Overrides

Passing a value to the builder will override the default value.

const petOwner = buildPetOwner({
  pet: "Daisy" as const,
});
// { name: string, pet: "Daisy" }

It's also possible to pass a function to the builder. This function will be called with the provided faker instance, just like when setting up the builder initially.

const petOwner = buildPetOwner((f) => ({
  pet: f.helpers.arrayElement(["Daisy", "Bella", "Luna"] as const]),
}));
// { name: string, pet: "Daisy" | "Bella" | "Luna" }

Mocking Other Types

The builder can also be used to mock other types of values as well, such as primitives or arrays.

// Mocks a string value
const buildName = createMockBuilder((f) => f.person.fullName);

const name1 = buildName();
const name2 = buildName("John Doe");
const name3 = buildName((f) => f.person.lastName());

// Mocks an array
const buildNames = createMockBuilder((f) => {
  return f.helpers.multiple(() => f.person.fullName());
});

const names1 = buildNames();
const names2 = buildNames(["John Doe", "Jane Doe"]);
const names3 = buildNames((f) => {
  return f.helpers.multiple(() => f.person.lastName());
});

Advanced Patterns

Combining Builders

If you have a value that that is a superset of another, you can reuse the builder of the subset in the builder of the superset by simply spreading it.

interface Person {
  name: string;
  age: number;
}

const buildPerson = createMockBuilder(
  (f): Person => ({
    name: f.person.firstName(),
    age: f.random.number(),
  }),
);

interface PetOwner extends Person {
  pet: string;
}

const buildPetOwner = createMockBuilder(buildPerson
  (f): PetOwner => ({
    ...buildPerson(),
    pet: f.animal.cat(),
  }),
);

const buildCatNames = createMockBuilder((f) => {
  return f.helpers.shuffle(["Daisy", "Bella", "Luna"]);
});

const buildDogNames = createMockBuilder((f) => {
  return f.helpers.shuffle(["Max", "Charlie", "Cooper"]);
});

const buildPets = createMockBuilder((f) => {
  return f.helpers.shuffle([...buildCatNames(), ...buildDogNames()]);
});

The Mock Server (Alpha)

This utility provides an easy way for creating and interacting with a local mock server.

Configuration

To use the mock server, you must first configure it. This is done by importing and calling configureMockServer

import { configureMockServer } from "mockemon/server";

// The payload type is used to define the shape of the data that will be sent to the server. This can be any shape, since you have full control over how you use it. We'll see this further down.
type Payload = {
  path: string;
  method: string;
  params: Record<string, string>;
  body: unknown;
};

// Since a single server will handle both the "real" requests that we want to serve our mocks to as well as the requests that facilitates the mocking, we need to be able to distinguish between the two.
export const mockServer = configureMockServer<Payload>({
  realApiUrl: "/api", // <- This is where your application will make regular requests.
  mockApiUrl: "/mocks",
});

Server

Then configure a server with the mock handlers. This should be compatible with any server setup. For this example, we will use express.

import express from "express";
import { mockServer } from "./mock-server";

const app = express();

// In addition to the api resolvers,
// this provides access to the urls we previously configured.
// This way we don't have to type them out again, and have a single source of truth.
const server = mockServer.server();

app.use(express.json());

app.all(server.realApiUrl + "*", (req, res) => {
  const result = server.resolveRealApiRequest({
    url: req.originalUrl,
    getKey: (path) => `${req.method} ${path}`,
    getValue: () => req.body,
  });
  res.json(result);
});

app.all(server.mockApiUrl + "*", (req, res) => {
  const result = server.resolveMockApiRequest({
    url: req.originalUrl,
    getKey: (payload) => `${payload.method} ${payload.path}`,
    getValue: (payload) => payload.body,
  });
  res.json(result);
});

app.listen(4000);

That's it for the server!

Client

Now let's look at how create the client part.

import { mockServer } from "./mock-server";

export const client = mockServer.client({
  // This should be the address of the server we just created.
  address: "http://localhost:4000",
  // We also need to provide how to send requests.
  request({ url, method }) {
    // We're using fetch here, but any way to make a request will work,
    // as long as it supports passing a method and a url.
    const response = await fetch(url, {
      method,
    });
    return response.json();
  },
});

Now we can start creating mocks.

import { client } from "./client";

// Since we've already provided the shape of the payload in the initial configuration, we get some nice intellisense here.
client.setMock({
  path: "/animals/cat",
  method: "GET",
  body: {
    name: "Luna",
    breed: "British Shorthair",
  },
});

Making a regular request now responds with the mocked data!

const cat = await fetch("http://localhost:4000/api/animals/cat").then((res) => res.json());

console.log(cat);
// { name: "Luna", breed: "British Shorthair" }