TypeScript Mock Builder

1.0.3 · active · verified Tue Apr 21

mock-build is a TypeScript library that facilitates the creation of reusable mock objects using the builder pattern, primarily for testing purposes. It is currently at version 1.0.3 and appears to follow a release cadence driven by patches and minor improvements, as indicated by its recent release history since its initial v1.0.0 launch. Key differentiators include its fluent API for constructing complex objects, support for template objects to base mocks on existing data, and a `strictMockBuilder` variant that enforces initialization of all properties, helping to prevent partial or invalid mock states. The library focuses on enhancing readability and maintainability of test data setup in TypeScript projects. It targets Node.js version 18.12 and above, and ships with full TypeScript type definitions.

Common errors

```
This expression is not callable. Type 'never' has no call signatures.ts(2349)
```
cause Attempting to call `.build()` on a `strictMockBuilder` instance without initializing all mandatory properties defined in the interface.

fix Ensure all properties of the interface are explicitly set using the builder's fluent API before calling `.build()`. The TypeScript compiler will guide you on which properties are missing.
```
TypeError: Cannot read properties of undefined (reading 'build')
```
cause This typically occurs if `mockBuilder` or `strictMockBuilder` were not correctly imported or if the import path is wrong, resulting in the functions being undefined.

fix Verify that `import { mockBuilder, strictMockBuilder } from 'mock-build';` is present and correct at the top of your file. Check your `node_modules` to ensure the package is installed.

Warnings

gotcha When using `mockBuilder<Interface>()`, the builder does not enforce that all mandatory fields of the interface are set before calling `.build()`. This can lead to objects that do not conform to the expected interface contract, potentially causing runtime errors in tests.
Fix: Use a template object (`mockBuilder(defaultObject)`) or `strictMockBuilder<Interface>()` to ensure all fields are initialized. `strictMockBuilder` will throw a TypeScript error if any mandatory field is missing.
gotcha The `strictMockBuilder` currently does not support class objects as its type argument. It is designed to work with interfaces or plain object types.
Fix: For class objects, use the regular `mockBuilder(MyClass)` or `mockBuilder(MyClass, templateObject)` approach. If strictness is required for classes, manual validation or alternative mocking libraries might be necessary.
gotcha When using template objects (`mockBuilder(templateObject)`), the builder creates and modifies a shallow copy of the provided template. Deeply nested objects within the template will not be cloned, meaning mutations through the builder will affect the original template's nested objects.
Fix: Be aware of shallow copying. For templates with nested objects that need independent modification, manually deep clone the template before passing it to `mockBuilder`, or explicitly set all nested properties via the builder.
gotcha The package requires Node.js version 18.12 or higher. Earlier Node.js versions may encounter issues related to module resolution or other environment specifics.
Fix: Ensure your development and test environments are running Node.js v18.12 or newer.

Install

npm install mock-build npm
yarn add mock-build yarn
pnpm add mock-build pnpm

Imports

mockBuilder
wrong:
```
const mockBuilder = require('mock-build');
```
correct:
```
import { mockBuilder } from 'mock-build';
```
The library is designed for ESM usage with TypeScript. CommonJS require() is not the idiomatic way.
strictMockBuilder
wrong:
```
import strictMockBuilder from 'mock-build';
```
correct:
```
import { strictMockBuilder } from 'mock-build';
```
Both `mockBuilder` and `strictMockBuilder` are named exports, not default exports.
mockBuilder (type)
```
import type { MockBuilder } from 'mock-build';
```
While not frequently needed, if type information for the builder itself is required, it's a named import.

Quickstart

This quickstart demonstrates the core functionality of `mock-build`: basic object creation, using template objects for variations, and enforcing full field initialization with `strictMockBuilder`.

import { mockBuilder, strictMockBuilder } from 'mock-build';

interface UserInfo {
  id: number;
  userName: string;
  email: string;
  isAdmin?: boolean;
}

// Basic usage: creates a UserInfo object with specified fields.
const userInfo = mockBuilder<UserInfo>()
  .id(1)
  .userName('alice')
  .email('alice@example.com')
  .build();

console.log('Basic User:', userInfo);
// Output: { id: 1, userName: 'alice', email: 'alice@example.com' }

// Usage with a template object, ensuring all mandatory fields are present initially.
const defaultUserInfo: UserInfo = {
  id: 10,
  userName: 'defaultUser',
  email: 'default@example.com',
  isAdmin: false
};

const modifiedUserInfo = mockBuilder(defaultUserInfo)
  .userName('bob')
  .isAdmin(true)
  .build();

console.log('Modified User from template:', modifiedUserInfo);
// Output: { id: 10, userName: 'bob', email: 'default@example.com', isAdmin: true }

// Using strictMockBuilder to enforce all fields are set before calling build().
// The following would cause a TypeScript error:
// const incompleteStrictUser = strictMockBuilder<UserInfo>().id(3).build();

const completeStrictUser = strictMockBuilder<UserInfo>()
  .id(3)
  .userName('charlie')
  .email('charlie@example.com')
  .isAdmin(false)
  .build();

console.log('Strict User:', completeStrictUser);

view raw JSON →