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(
  (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()]);
});