Skip to main content

Test Factories

Joist generates customizable factories for easily creating test data. The idea is very similar to generic tools like Fishery, but with deep/native integration with Joist.

The goal of factories are to provide tests with "valid by default" instances of entities, so that each test can focus solely on the state/behavior that is unique to its boundary case.

Joist also fundamentally assumes the database is reset between each test (see Fast Database Resets), and so allowing tests to succinctly create the entire graph of entities they need is a key part of Joist's developer experience.

Note that Joist's factories are not intended to be used in production code; they are only for quickly creating synthetic data in unit tests.


For example, given a Book entity, Joist will generate a Book.factories.ts file that looks like:

import { EntityManager, FactoryOpts, New, newTestInstance } from "joist-orm";
import { Book } from "./entities";

export function newBook(em: EntityManager, opts: FactoryOpts<Book> = {}): New<Book> {
return newTestInstance(em, Book, opts, {});

Tests can then call newBook with as few opts as they want, and all required fields (for both primitives and relations) will be filled in.

For example, since book.author_id is a not-null column, calling const b1 = newBook() will create both a Book with a title (required primitive field) as well as create a new Author (required foreign key/many-to-one field) and assign it to

const b = newBook(em);

This creation is recursive, i.e. newBookReview() will make a new BookReview, a new Book (required for, and a new Author (required for

Importantly, you can also pass partials for either the book or the author:

// Given a book by the author "a1"
const b = newBook(em, { author: { firstName: "a1" } });
// Then we got the default title
// And "a1" was used as the author's firstName

This is key so that your tests can set only the minimum amount of fields necessary to specify their boundary case, and defer to the factories for any other irrelevant boilerplate.


Defaults for Primitives

Factories can provide test suite-wide defaults, for example providing a default age:

// Default Authors (only within tests) to age 40
export function newAuthor(em: EntityManager, opts: FactoryOpts<Author> = {}): New<Author> {
return newTestInstance(em, Author, opts, {
age: 40,

And then every newAuthor will have an age of 40, unless a test specifically requires a different age:

// Given an author that is 30
const a = newAuthor(em, { age: 30 });
// Then we didn't use the default age

Unique Strings

If you have a field that must be unique, like name with a database-enforce UNIQUE constraint, you can use the testIndex helper to automatically create unique-but-deterministic values:

import { testIndex } from "joist-orm";

export function newBook(em: EntityManager, opts: FactoryOpts<Book> = {}): New<Book> {
return newTestInstance(em, Book, opts, {
// Make a unique name, `testIndex` will be 1/2/etc increasing and reset per-test
title: `b${testIndex}`,

Defaults for References

Factories can also provide default entities, for example a book creating a default author:

export function newBook(em: EntityManager, opts: FactoryOpts<Book> = {}): New<Book> {
return newTestInstance(em, Book, opts, {
author: {},

Note that, if author was required, we would not have to explicitly pass author: {}; we'd only pass author to newTestInstance if:

  • The author field is not required, but we want all test Books to have one anyway
  • We want all Books' authors to themselves have some specific defaults, like author: { age: 30 },
  • We want to explicitly create a new author (see the next point)

Reusing Existing Entities

When factories need to set a relation field, they will first look for an "obvious default" entity before creating a new entity.

This is useful for stitching together complex schemas, because it means validation rules like "a BookReview must have the same as its" (pretending that BookReview had its own author field) will pass "for free" because we don't "sprawl out" and continually create new/unnecessary entities.

That said, Joist will only reuse an entity if there is a single instance of that entity.

// Given we have a single author
const a = newAuthor(em);
// Then newBook will see "there is only 1 author" and assume we want that one
const b = newBook(em);

If there are multiple Authors created in the test, Joist sees it as ambiguous which one it should use, and so creates a new Author:

// Given we have two existing Authors
const [a1, a2] = [newAuthor(em), newAuthor(em)];
// Then newBook will create a 3rd Author
const b = newBook(em);

Forcing New Entities

If you want to a specific field to never reuse existing entities, you can use {} as a marker for "always create a new entity":

export function newBook(em: EntityManager, opts: FactoryOpts<Book> = {}): New<Book> {
return newTestInstance(em, Book, opts, {
author: {},

Reusing Entities With use

As covered, if your test has already created multiple entities of a given type (e.g. multiple Authors), Joist will not use them as "obvious defaults", but if you want to nominate a specific Author as the default for a given newBookReview call, you can pass the use option:

// We have multiple authors
const [a1, a2] = [newAuthor(em), newAuthor(em)];
// Make a new book review, but use a2 instead of creating a new Author
const br = newBookReview(em, { use: a2 });

Defaults for Collections

If you have validation rules like "all Authors must have at least one Book", the newAuthor factory can create valid-by-default Authors by passing books: [{}]:

export function newAuthor(em: EntityManager, opts: FactoryOpts<Author> = {}): New<Author> {
return newTestInstance(em, Author, opts, {
// Every Author has at least one Book
books: [{}],

Note that, due to the native factory integration, Joist is smart enough that if you create the graph "bottom up" and call newBook(), it will be smart enough to know that newAuthor should not create a 2nd book:

// Given we create a book
const b = newBook(em);
// Then `newAuthor` was effectively passed `books: [b]` and did not create a 2nd book

Custom Opts

Besides just setting existing entity fields, like Author.firstName and, Joist's factories allow you to declare custom, factory-specific opts so that multiple tests can request the similar "pre-baked" test data from a factory.


In fishery, these are called transient params.

For example, a test might need to create a somewhat large graph of test data for a business scenario, perhaps a Book with a signed contract with a larger publisher (this is not that big, but it's a good example):

// Given a book that is signed with a large publisher
const b = newBook(em, {
author: {
contracts: [{ signed: true, publisher: { type: "large" } }],

If this "create a book ... with an author ... with a contract ... that is signed" is a common requirement for tests, it can be cumbersome to copy/paste this snippet across many tests, and keep it up to date (perhaps signed changes from true to a signedOn timestamp).

Instead, Joist's factories allow you to add a custom withSignedContract opt to the newBook factory:

// Add an optional `withSignedContract` opt
export function newBook(em: EntityManager, opts: FactoryOpts<Book> & { withSignedContract?: boolean } = {}): New<Book> {
return newTestInstance(em, Book, opts, {
// Conditionally create the snippet when requested
...(opts.withSignedContract ? { author: { contracts: [{ signed: true, publisher: { type: "large" } }] } } : {}),

And now tests can request this behavior for free:

// Given we have a book with a signed contract
const book = newBook(em, { title: "b1", withSignedContract: true });
// And it also works if going through BookReview
const br = newBookReview(em, { book: { withSignedContract: true } });

In general, we have two recommendations for this feature:

  • Be careful and don't abuse it; tests are simplest to read when any assertions they have are against data that is specified directly inline in the "Given" block; if you've abstracted too much of your test's setup to a custom opt, it will hurt readability.

    Also, custom opts are a slippery slope to the seed data anti-pattern, where the seed data becomes so large & gnarly (because it's been tweaked over the years to support more and more disparate test cases), that the seed data becomes very brittle and can't be changed without failing a ton of tests.

  • Use prefixes like with and and in the names of custom opts, e.g. withSignedContract or andSigned to make it clear to readers that the opt is custom and not actually a regular database/entity field.

Disabling Factory Defaults

Sometimes you'll have a test that wants to opt-out of the defaults provided by a factory.

You can do this by using useFactoryDefaults: false, for example if Author.factories.ts establishes a default age of 40, you can ignore it by passing useFactoryDefaults: false:

// Ignore the default when creating an author
const a = newAuthor(em, { useFactoryDefaults: false });

// You can also ignore when creating an author via another factory
const br = newBookReview(em, {
book: { author: { useFactoryDefaults: false } },

Setting useFactoryDefaults: false ignores the defaults inside of Author.factories.ts, Book.factories.ts, etc., but it does not disable Joist's fundamental "required fields must always be set" defaults.

If you want to disable those as well, you can use useFactoryDefaults: "none":

// Ignore all defaults
const b = newBook(em, { useFactoryDefaults: "none" });
// Normally this would be "title", but is left unset
// Normally this would be a new/existing Author, but is left unset

If you find yourself regularly using useFactoryDefaults, it might be an indication that your factory's defaults are too opinionated, and the factory should do less by default.

For example, instead of the factory having "not actually universally required/useful" defaults that frequently need to be turned off, only the tests that actually rely on the sometimes-wanted/sometimes-not-wanted defaults should opt in to them via a dedicated custom opt.

async Free Assertions

In production code, Joist relations must be accessed asynchronously, i.e. either with load() calls or populate preloads:

// Call load directly
const b1 = await em.load(Book, "b:1");
const a1 = await;
// Use a preload
const b2 = await em.load(Book, "b:2", "author");
const a2 =;

However, because in tests we "just know" there is not that much data, and the factories control the instantiation of entities, we can make the assumption that all relations are loaded by default. So factories return a DeepNew type that marks all relations as loaded:

it("some test", async () => {
const em = newEntityManager();
// Given a book
const b1 = newBook(em);
// When we exercise our production code
// Then we can assert against b1.authors w/o an await/load
// And we can assert against the author's publisher

This capability can dramatically clean up test assertions, by removing the need for await and load() calls.


Also see Joist's toMatchEntity, which provides another ergonomic way to assert against entities.

useExisting option

Sometimes with factories, even though a test has already called newSomeEntity to create a new SomeEntity be created, within the factory code, you realize that, due to the business logic/constraints of your domain model, the entity being requested actually already exists.

An example is schemas with "enum-like" entities. Enum-like entities are user-added rows in the database, but still have enum-like behavior like "there should be only one of these 'types' for the given (name, parent, etc.) set of values", potentially backed by database-level unique constrains.

An example might be a PublisherType entity that is effectively unique on a name column, where the desired behavior is:

// Creates a new PublisherType w/name: large
newPublisher(em, { type: { name: "large" } });
// Creates a new PublisherType w/name: small
newPublisher(em, { type: { name: "small" } });
// Should reuse the existing PublisherType w/name: large
newPublisher(em, { type: { name: "large" } });

In these situations, you effectively want your factory to "scan existing entities" and look for an entity that matches the test's requested opts.

To do this, you can use the useExisting flag on newTestInstance, which is a lambda that returns "does the request opts match this existing PublisherType"?:

export function newPublisherType(
em: EntityManager,
opts: FactoryOpts<PublisherType> = {},
): DeepNew<PublisherType> {
return newTestInstance(
{ useExisting: (opts, existing) => === },

The benefit of using useExisting is that the existing param will already be typed to your given entity type (i.e. PublisherType), and the opts param will be the "post-resolution" opts, i.e. instead of "maybe object literals or maybe object instances", they will be object instances (basically OptsOf<PublisherType>), which simplifies the lambda's matching logic.