Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FactoryGirl
✓ import { FactoryGirl } from 'factory-girl-ts';
✗ import FactoryGirl from 'factory-girl-ts';
const FactoryGirl = require('factory-girl-ts');
FactoryGirl is a named export. ESM-only usage is expected for Node.js environments >= 18.16.0.
SequelizeAdapter
✓ import { SequelizeAdapter } from 'factory-girl-ts';
✗ const { SequelizeAdapter } = require('factory-girl-ts');
Adapters like SequelizeAdapter are named exports from the main package and are used to integrate with specific ORMs.
define factory
✓ FactoryGirl.define(User, defaultAttributesFactory);
✗ define(User, defaultAttributesFactory);
The define method is a static method on the FactoryGirl class, not a top-level export.
This quickstart demonstrates how to set up `factory-girl-ts` with a mock Sequelize model, define a factory with default attributes, and use its `build`, `create`, and `createMany` methods to generate test data.
import { User } from './models/user';
import { FactoryGirl, SequelizeAdapter } from 'factory-girl-ts';
// A dummy User model for demonstration purposes
class User {
id!: number;
name!: string;
email!: string;
address!: { state: string; country: string };
// Mimic Sequelize's static methods
static build(attributes: Partial<User>): User { return Object.assign(new User(), attributes); }
static async create(attributes: Partial<User>): Promise<User> {
console.log('Creating user in DB:', attributes);
const user = Object.assign(new User(), attributes);
user.id = Math.floor(Math.random() * 1000) + 1; // Simulate ID from DB
return Promise.resolve(user);
}
}
// Step 1: Specify the adapter for your ORM.
// For actual Sequelize usage, ensure SequelizeAdapter is correctly configured with a model.
FactoryGirl.setAdapter(new SequelizeAdapter());
// Step 2: Define your factory with default attributes for the model.
const defaultAttributesFactory = () => ({
name: 'John',
email: 'some-email@mail.com',
address: {
state: 'Some state',
country: 'Some country',
},
});
const userFactory = FactoryGirl.define(User, defaultAttributesFactory);
// Step 3: Use the factory to create instances of the model.
async function runExample() {
const defaultUser = await userFactory.build();
console.log('Built default user:', defaultUser);
const createdUser = await userFactory.create({ email: 'new-user@example.com' });
console.log('Created user in DB:', createdUser);
const manyUsers = await userFactory.createMany(2, { name: 'Bulk User' });
console.log('Created many users:', manyUsers);
}
runExample();
Debug
Known issues
breakingUsers migrating from the original 'factory-girl' package should be aware that 'factory-girl-ts' is a separate, modern rewrite. It is not a drop-in replacement and requires a full migration of existing factory definitions due to API and internal implementation differences.fixRewrite existing factories to use `factory-girl-ts`'s API, import paths, and adapter patterns. Consult the `factory-girl-ts` documentation for new syntax.
affects: N/A (applies when switching from 'factory-girl' to 'factory-girl-ts')
gotchaAll factory instance methods like `build()`, `create()`, `buildMany()`, and `createMany()` are asynchronous and return Promises. Failing to `await` these calls will lead to unhandled promise rejections or tests completing before data is ready.fixAlways use the `await` keyword when calling `factory.build()`, `factory.create()`, and their 'Many' counterparts to ensure operations complete synchronously within an `async` context.
affects: >=2.0.0
breakingThe `additional parameters type` feature was removed in v2.2.0, which might impact custom adapter implementations or advanced factory configurations that relied on this specific typing for additional parameters.fixReview any custom adapter implementations or factory definitions that previously utilized 'additional parameters type' and refactor them to remove or replace the deprecated typing.
affects: >=2.2.0
gotcha`factory-girl-ts` is designed for modern JavaScript environments (Node.js >=18.16.0), implying a preference for ECMAScript Modules (ESM). Using CommonJS `require()` for imports will not work correctly for its named exports.fixEnsure your project is configured for ESM, typically by setting `"type": "module"` in your `package.json` or by using `.mjs` file extensions. Use `import { NamedExport } from 'package'` syntax. affects: >=2.0.0
gotchaPrior to v2.3.1, a bug could cause factories to inadvertently create unused initial associations, potentially leading to unnecessary database operations or test data pollution.fixUpgrade to `factory-girl-ts` version 2.3.1 or higher to resolve the issue where factories might create unintended associations during definition or initial use.
affects: <2.3.1
Errors
Common errors & fixes
TypeError: FactoryGirl.define is not a function
Incorrect import syntax for named exports, often trying to `require()` or use a default import instead of a named import.
fixUse named import syntax: `import { FactoryGirl } from 'factory-girl-ts';` UnhandledPromiseRejectionWarning: Promise { <pending> }
Forgetting to `await` asynchronous factory methods like `build()` or `create()` within an `async` function.
fixAlways use `await` when calling factory methods, e.g., `const user = await userFactory.create();`.
TS2345: Argument of type 'typeof User' is not assignable to parameter of type 'new () => User'.
Type mismatch when defining factories for ORM models; the constructor signature or instantiation type for the model class does not align with `factory-girl-ts`'s expectations for 'new'able types.
fixReview your ORM model's type definition and ensure it is compatible with the `new () => Model` constructor signature. You might need to adjust your model's class or use type assertions if ORM types are complex.
Error: 'User' factory is not defined.
Attempting to use a factory (e.g., `userFactory.create()`) before it has been properly `define`d with `FactoryGirl.define()`.
fixEnsure `FactoryGirl.define()` for the target model is called and executed *before* any `build()` or `create()` operations are invoked on that factory.
Audit
Dependencies
No dependency data recorded yet.