Rosie Factory for Test Data

Common errors

• ReferenceError: Factory is not defined

  cause The `Factory` object was not correctly imported or made available in the current scope for CommonJS modules.
  fix Ensure you are importing `Factory` correctly: `const { Factory } = require('rosie');`.

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

  cause This usually means `Factory` was imported incorrectly in a CommonJS module, resulting in `undefined` or an unexpected object instead of the actual `Factory` instance with its methods.
  fix Verify the CommonJS import: `const { Factory } = require('rosie');`. If you used `const Factory = require('rosie');`, it will likely yield this error because the module's default export isn't the `Factory` itself, but an object containing `Factory` as a property.

• TypeError: The requested module 'rosie' does not provide an export named 'Factory'

  cause This error occurs in an ESM context when attempting to import `Factory` as a default export (`import Factory from 'rosie';`) while it is a named export.
  fix Correct the ESM import statement to use named import syntax: `import { Factory } from 'rosie';`.

• Error: Factory named 'myFactoryName' not found

  cause You are trying to build an object from a factory that has not been defined or has been reset.
  fix Ensure `Factory.define('myFactoryName', ...)` has been called before attempting to `Factory.build('myFactoryName', ...)` or `Factory.attributes('myFactoryName', ...)`. If using `Factory.reset()`, ensure definitions are re-run before tests.

Warnings

• gotcha When using ESM `import` syntax in Node.js environments older than Node.js 12, a transpilation step (e.g., with Babel) might be necessary. While `engines.node >=10` is specified, native ESM support became stable later. Without transpilation, direct ESM imports might fail on Node.js 10/11.
  Fix: For older Node.js environments, use CommonJS `require` syntax (`const { Factory } = require('rosie');`) or integrate a transpiler like Babel into your build process to handle ESM imports.
• gotcha Distinguish carefully between `attr` and `option`. Attributes (`attr`) define properties that will be present in the final built object. Options (`option`) are parameters used *during* the object generation process but are *not* included in the resulting object. Misunderstanding this can lead to unexpected keys in your test data or missing data needed for generation.
  Fix: Review the usage documentation for `.attr()` vs `.option()` carefully. Use `.attr()` for data that should appear in the final object, and `.option()` for configuration parameters that control how the object is built but are not part of its schema.
• gotcha Rosie's default behavior involves a global `Factory` singleton. If you are running tests in parallel or in environments where global state can cause interference, definitions might conflict. To avoid this, consider using 'unregistered factories' or explicitly calling `Factory.reset()`.
  Fix: For isolated factory definitions, create factory instances directly: `const myFactory = new Factory().define('myModel');`. For global singleton cleanup between tests, ensure `Factory.reset()` is called in a `beforeEach` or `afterEach` hook in your test runner.

Install

• npm install rosie npm
• yarn add rosie yarn
• pnpm add rosie pnpm

Imports

• Factory
  wrong:

  import Factory from 'rosie'; // Rosie exports a named 'Factory', not a default.

  correct:

  import { Factory } from 'rosie'; // For ESM environments

  Rosie exports `Factory` as a named export. While the package specifies Node.js >=10, native ESM support for `import` without transpilation is generally stable in Node.js >=12. For older Node.js versions, a transpiler like Babel may be required.
• Factory
  wrong:

  const Factory = require('rosie'); // This would import the entire module object, not the Factory instance directly.

  correct:

  const { Factory } = require('rosie'); // For CommonJS environments

  The `Factory` object is directly accessible as a named property from the CommonJS `require` result. This is the recommended way to import in CommonJS.
• Factory
  wrong:

  import Factory from 'rosie'; // Incorrect default import for TypeScript

  correct:

  /// <reference types="rosie" />
  import { Factory } from 'rosie'; // For TypeScript

  Type definitions are available via `@types/rosie`. Ensure `@types/rosie` is installed for correct type inference and autocompletion in TypeScript projects.

Quickstart

This quickstart demonstrates defining multiple factories, including inheritance, using sequences, dependent attributes, overriding attributes during build, and utilizing options that influence object creation without being part of the final output. It covers the core `define`, `build`, and `attributes` methods.

import { Factory } from 'rosie';

// Define a 'game' factory with sequences, attributes, and dependent attributes.
Factory.define('game')
  .sequence('id')
  .attr('is_over', false)
  .attr('created_at', () => new Date())
  .attr('random_seed', () => Math.random())
  .attr('players', ['players'], (players) => {
    if (!players) {
      players = [{}, {}];
    }
    return players.map((data) => Factory.attributes('player', data));
  });

// Define a 'player' factory, extended by 'disabled-player'.
Factory.define('player')
  .sequence('id')
  .sequence('name', (i) => `player${i}`)
  .attr('position', ['id'], (id) => {
    const positions = ['pitcher', '1st base', '2nd base', '3rd base'];
    return positions[id % positions.length];
  });

// Extend the 'player' factory to create a 'disabled-player'.
Factory.define('disabled-player').extend('player').attr('state', 'disabled');

// Build an object, overriding some attributes.
const game = Factory.build('game', { is_over: true });
console.log('Built Game:', game);

// Build an object using the extended factory.
const disabledPlayer = Factory.build('disabled-player');
console.log('Built Disabled Player:', disabledPlayer);

// Get just the attributes without invoking a constructor.
const gameAttributes = Factory.attributes('game', { is_over: false });
console.log('Game Attributes:', gameAttributes);

// Example with options (options are not part of the final object).
Factory.define('matches')
  .attr('seasonStart', '2024-01-01')
  .option('numMatches', 2)
  .attr('matches', ['numMatches', 'seasonStart'], (numMatches, seasonStart) => {
    const matches = [];
    for (let i = 1; i <= numMatches; i++) {
      const matchDate = new Date(seasonStart);
      matchDate.setDate(matchDate.getDate() + (i * 7)); // Add weeks
      matches.push({
        matchDate: matchDate.toISOString().split('T')[0],
        homeScore: Math.floor(Math.random() * 5),
        awayScore: Math.floor(Math.random() * 5)
      });
    }
    return matches;
  });

const matchData = Factory.build('matches', { seasonStart: '2024-03-12' }, { numMatches: 3 });
console.log('Match Data with options:', matchData);