Test Data Bot

Common errors

• TypeError: build is not a function

  cause Attempting to use `build` without correct destructuring for CommonJS `require` or using `require` in an ESM context.
  fix Ensure correct import syntax: `const { build, fake } = require('test-data-bot');` for CommonJS or `import { build, fake } from 'test-data-bot';` for ESM.

• ReferenceError: faker is not defined

  cause Trying to directly access `faker` methods outside of the `fake()` helper function, or without passing the `f` argument.
  fix All `faker.js` methods must be accessed via the `f` argument provided to the callback inside `fake()`: `fake(f => f.name.firstName())`.

• TypeError: Cannot read properties of undefined (reading 'someMethod')

  cause This error often occurs within the `fake()` callback if the `f` (faker) object is not passed or if an invalid `faker.js` method is called.
  fix Verify that your `fake()` callback receives the `faker` instance as an argument (`fake(f => ...)`) and that the `faker.js` method you are calling (e.g., `f.name.findName()`) exists in the `faker.js` API.

Warnings

• gotcha The `sequence` helper generates numbers unique to each field definition, meaning `sequence(x => x)` in two different fields will both start their count from 1. Conversely, `incrementingId` provides a globally unique, auto-incrementing number across all uses.
  Fix: Understand the scope: `sequence` is per-field, `incrementingId` is global. Use `incrementingId` when truly unique IDs are needed across an entire test run, or manage custom sequencing manually for specific scenarios.
• gotcha While `test-data-bot` uses `faker.js` internally, the specific version of `faker.js` is managed by `test-data-bot` and is not exposed or directly controllable by the end-user. Updates to the internal `faker.js` dependency could lead to subtle changes in generated data patterns between `test-data-bot` patch versions, even without a major `test-data-bot` version bump.
  Fix: Rely on `test-data-bot`'s public API and avoid direct `faker.js` imports if strict control over `faker.js` versions or features is required, consider using `faker.js` directly or wrapping its functions within `fake()`.
• gotcha When using `arrayOf(builder, count)` where `builder` is another test-data-bot builder, this will create an array containing `count` references to the *builder function itself*, not an array of generated objects. To get an array of generated objects, you must call the builder.
  Fix: Always call the builder when passing it to `arrayOf` if you intend to generate objects: `arrayOf(() => myBuilder(), 3)`. The function wrapper ensures a new instance is created for each array element.
• gotcha Overriding values by passing an object to the builder function (`userBuilder({ name: 'New Name' })`) only affects top-level fields. For deeply nested objects that are defined within `fields`, a simple override will replace the entire nested object rather than merging properties.
  Fix: For complex nested object overrides, consider using nested builders or applying a `map` function to post-process the generated data. Alternatively, ensure nested objects are themselves created by sub-builders that can be individually overridden.

Install

• npm install test-data-bot npm
• yarn add test-data-bot yarn
• pnpm add test-data-bot pnpm

Imports

• build
  wrong:

  const { build } = require('test-data-bot')

  correct:

  import { build } from 'test-data-bot'

  CommonJS `require` is shown in examples, but ESM `import` is preferred in modern JavaScript/TypeScript.
• fake
  wrong:

  const { fake } = require('test-data-bot')

  correct:

  import { fake } from 'test-data-bot'

  Used within a builder's `fields` definition to leverage `faker.js` for dynamic data.
• sequence
  wrong:

  const { sequence } = require('test-data-bot')

  correct:

  import { sequence } from 'test-data-bot'

  Provides unique, incrementing numbers per field definition, starting from 1.
• incrementingId
  wrong:

  const { incrementingId } = require('test-data-bot')

  correct:

  import { incrementingId } from 'test-data-bot'

  Generates a globally unique, incrementing ID number across all builders.

Quickstart

Demonstrates creating a basic user builder, generating multiple unique users, overriding specific fields, and extending an existing builder for an admin user.

import { build, fake, sequence } from 'test-data-bot';

const userBuilder = build('User').fields({
  id: sequence(x => x),
  name: fake(f => f.name.findName()),
  email: sequence(x => `user${x}@example.com`),
  age: 26,
  isActive: true,
});

const newUser1 = userBuilder();
const newUser2 = userBuilder({ name: 'Jane Doe', age: 30 });

console.log(newUser1);
// Example output: { id: 1, name: 'John Smith', email: 'user1@example.com', age: 26, isActive: true }
console.log(newUser2);
// Example output: { id: 2, name: 'Jane Doe', email: 'user2@example.com', age: 30, isActive: true }

const adminBuilder = build('Admin').fields({
  ...userBuilder.fields,
  role: 'admin'
});

const newAdmin = adminBuilder();
console.log(newAdmin);
// Example output: { id: 3, name: 'Another Name', email: 'user3@example.com', age: 26, isActive: true, role: 'admin' }