Declarative Fixtures in TypeScript

Setting up test fixtures is generally a painful process. Declarative fixtures help reduce the barrier to writing better tests, thus improving overall code coverage and quality.

Over the years there have been numerous attempts at test fixturing libraries for JavaScript and TypeScript to varying levels of success. Some work better with a specific database or ORM, some have better TypeScript support, some offer a nicer interface, but none feel right. So in proper JavaScript fashion, why not invent another one that works with any database?

All examples used in this post are available in executable form at zanfa/declarative-fixtures.

Example Data Model

For the purposes of this article, code examples use 3 types of entities. Company, Department and Employee. They’re modeled so that a Company can have a zero or more Department, each of which can have zero or more Employee. Here’s one possible way to define them:

type Company = {
  id: number;
  name: string;
  address: string;
  phoneNumber: string;
};

type Department = {
  id: number;
  name: string;
  companyId: number;
};

type Employee = {
  id: number;
  firstName: string;
  lastName: string;
  title: string;
  salary: number;
  departmentId: number;
};

The patterns we’re going to discuss are database-agnostic, so any database driver and client library combination will work, including but not limited to SQL databases such as Postgres using Knex or Prism, NoSQL databases such as MongoDB, DynamoDB or blob stores like S3. The example code uses a naive in-memory implementation in place of an actual database, with the following interface:

export interface QueryBuilder<T> {
  insert<T>(data: T): T & { id: number };
}

export interface Database {
  tables: { [key: string]: any[] };
  table<T>(name: string): QueryBuilder<T>;
}

Starting Point

We’ll be using average salary calculation of employees as the example. Let’s start off by setting up the hierarchy of entities simply by inserting one after the other, based on the order of dependencies. Company first, departments second and finally as many employees as necessary to set up preconditions for the test.

describe("salary_calculator", () => {
  it("calculates the average salary of all employees", () => {
    const db = inMemoryDatabase();

    const google = db.table("companies").insert({
      name: "Google",
      address: "123 Example St",
      phoneNumber: "555-555-5555",
    });
    const rdDepartment = db.table("departments").insert({
      name: "R&D",
      companyId: google.id,
    });
    db.table("employees").insert({
      firstName: "John",
      lastName: "Doe",
      title: "Software Engineer",
      salary: 100_000, // #1
      departmentId: rdDepartment.id,
    });
    db.table("employees").insert({
      firstName: "Jane",
      lastName: "Doe",
      title: "Senior Software Engineer",
      salary: 200_000, // #2
      departmentId: rdDepartment.id,
    });

    const averageSalary = calculateAverageSalary(db);
    equal(averageSalary, 150_000); // #3
  });
});

If there’s only a single test case, this works just fine and might be all we need. It’s explicit and trivial to follow, however it’s verbose and has a high amount of boilerplate. It’s not immediately obvious which entities and which fields (#1 and #2) matter and how they relate to the assertion #3. It’s also not immediately clear if the function under test makes any assumptions about the relationships of entities, so another test with multiple employees, but split between a different set of departments and companies would probably be a good idea.

Even with just 3 levels on entities and a couple of tests, the amount of boilerplate starts growing quickly, so naturally some of the setup code may be refactored into beforeAll/beforeEach hooks to clean up it definitions. While this works, it also creates shared scope between tests, maintenance overhead as models change over time with new fields being added or updated and reduced data locality in tests.

DRYing Up Fixtures with Builders

The first obvious step to take would be to remove duplication in fixture definitions. In our salary calculation example above, the name of the company, department or even the title of the employee are irrelevant. They might be required by the database, due to NOT NULL checks or other business rules, so we can’t skip them, but it would be nice to have some reasonable defaults and let us explicitly override values that we do care about. This brings us to builders.

Builders are functions that construct objects from default values that can be overriden. Essentially, it’s object spread syntax with a tiny bit of type sugar. For example, in a test that verifies filtering companies by name, we could use a buildCompany to construct a valid Company that can then be inserted into the database:

const google = buildCompany({
  name: "Google",
});

// Functionally equivalent
const google = {
  name: "Google",
  address: "123 Example St",
  phoneNumber: "555-555-5555",
};

With a simple top-level model, the difference isn’t significant, but as models get more fields and become more complex, the gains become clearer. In the case of Department, you can no longer define defaults for every field, because companyId is a dynamic value, only known at execution time. This leads to another benefit of builders, which is enforcing type-safety when constructing objects with dependencies.

// Type error, missing "companyId"
const invalidDepartment = buildDepartment({
  name: "Research & Development",
});

// Success
const validDepartment = buildDepartment({
  name: "Research & Development",
  companyId: 23,
});

It’s not bulletproof and it’s still possible to create invalid departments that will cause errors at insertion time when foreign key constraints fail, by passing in a bogus id, but it’s a step in the right direction.

So how do we actually define builders? Like mentioned before, it’s surprisingly simple with a single helper function (and an optional IdLess type to clean up generics a bit) that’s responsible for constructing other builders:

type IdLess<T> = Omit<T, "id">;

function builder<T, K extends keyof T = never>(
  defaults: Omit<IdLess<T>, K>
): (overrides: Partial<IdLess<T>> & Pick<T, K>) => IdLess<T> {
  return (overrides) =>
    ({
      ...defaults,
      ...overrides,
    } as IdLess<T>);
}

With builder defined, creating new helpers becomes trivial. In our example, all we need for the three models is just a few additional definitions.

export const buildCompany = builder<Company>({
  name: "Example Company",
  address: "123 Example St",
  phoneNumber: "555-555-5555",
});

export const buildDepartment = builder<Department, "companyId">({
  name: "Example Department",
});

export const buildEmployee = builder<Employee, "departmentId">({
  firstName: "John",
  lastName: "Doe",
  title: "Software Engineer",
  salary: 75_000,
});

Armed with our new builders, going back to the original test case and replacing inline fixtures would result in something that looks like the following.

describe("salary_calculator", () => {
  it("calculates the average salary of all employees", () => {
    const db = inMemoryDatabase();

    const google = db.table("companies").insert(buildCompany({}));
    const rdDepartment = db
      .table("departments")
      .insert(buildDepartment({ companyId: google.id }));

    db.table("employees").insert(
      buildEmployee({
        salary: 100_000, // #1
        departmentId: rdDepartment.id,
      })
    );

    db.table("employees").insert(
      buildEmployee({
        salary: 200_000, // #2
        departmentId: rdDepartment.id,
      })
    );

    const averageSalary = calculateAverageSalary(db);
    equal(averageSalary, 150_000);
  });
});

While not yet significantly shorter in lines of code, a few things start to stand out. Since there are no more redundant field definitions, salary numbers (#1, #2) are much more prominent and make it clear they’re an important detail of the test, rather than noise. There’s still quite a bit of boilerplate around database management though, so let’s tackle that next.

Inserters

Now that builders have cut down on fixture duplication, the natural next step is coming up with a pattern that let’s us do the same with database insertions. In a typical case, all we do is customize an object using a builder, insert it into the appropriate database table and optionally store the returned row for future reference in another object.

With that in mind, we need a way to tie together a builder and the appropriate database table. This is where inserters come into play.

While this step is typically a bit more involved and depends on the specific database and library used in the application, inserters are conceptually simple functions that combine builders with database operations. And as with builders from before, we can define a factory function to create inserters for us.

function fixturize<P extends ReadonlyArray<unknown>, F>(
  table: string,
  builder: (...props: P) => F
) {
  return (...props: P) =>
    (db: Database) =>
      db.table(table).insert(builder(...props));
}

Leaving aside some generics shenanigans to be able to wrap arbitrary functions without losing type safety, all this function does is take a builder, call it with customizations and insert the resulting fixture into a table.

Given the previously defined builders and this factory, we can now create inserters for all our models.

const companyFixture = fixturize("companies", buildCompany);
const departmentFixture = fixturize("departments", buildDepartment);
const employeeFixture = fixturize("employees", buildEmployee);

If you paid attention to the fixturize defintion, you might have noticed it actually returns another function when passed customization properties, which leads us to this little (arguably optional) utility function.

function fixtureInserter(db: Database) {
  return <F>(inserter: (db: Database) => F) => inserter(db);
}

This is mostly useful for abstracting away the exact interface between inserters and databases, the benefit of which is outside the scope of this article, but it also makes for a nice syntax for calling inserters as you’ll see shortly.

With the newly-created helpers, fixtures can now be created even more concisely.

const db = inMemoryDatabase();
const insert = fixtureInserter(db);

const google = insert(companyFixture({ name: "Google" }));

Going back to our original test case, we can substitute all the builders for the latest and greatest.

describe("salary_calculator", () => {
  it("calculates the average salary of all employees", () => {
    const db = inMemoryDatabase();

    const insert = fixtureInserter(db);
    const google = insert(companyFixture({}));

    const rdDepartment = insert(
      departmentFixture({
        companyId: google.id,
      })
    );

    insert(
      employeeFixture({
        salary: 100_000,
        departmentId: rdDepartment.id,
      })
    );
    insert(
      employeeFixture({
        salary: 200_000,
        departmentId: rdDepartment.id,
      })
    );

    const averageSalary = calculateAverageSalary(db);
    equal(averageSalary, 150_000);
  });
});

While still a bit verbose, we’ve managed to further remove database implementation details unrelated to the crux of the current test. However, we still need to juggle database ids between entities in order to build the required hierarchy. We can do better.

Declarative Fixtures

So far, we’ve had a very imperative approach to setting up our tests. We tell the computer what actions need to be a taken, in which order and pass around state between these actions. Instead, wouldn’t it be nice to declare what we want and have it figure out the nitty-gritty for us?

We could jump into our LLM of choice, cross fingers and hope for the best, but there’s a better way. What we want is a way to describe how different entities relate to each other and what depends on what.

Let’s consider Company and Department for a moment. We’ve already defined a builders that give us some resonable defaults, but they don’t properly codify the relationship. A Company can exist independently or it may have many Department, on the other hand a Department requires a single Company. Also, a Company without Department is kind of pointless, so when we’re creating one, we’ll likely be creating matching Department entities as well.

With that in mind, let’s define a type that adds departments as an optional field to buildCompany.

type CompanyFixtureProps = Parameters<typeof buildCompany>[0] & {
  departments?: DepartmentFixtureProps[];
};

We can now update companyFixture to use this new type and also delegate creating Department entities as necessary.

function companyFixture(props?: CompanyFixtureProps) {
  return (db: Database): Company => {
    const { departments: departmentProps = [], ...companyProps } = props ?? {};

    const company = db.table("companies").insert(buildCompany(companyProps));

    departmentProps.map((department) =>
      departmentFixture({ ...department, companyId: company.id })(db)
    );

    return company;
  };
}

In just a few lines of extra code, we’re now able to create an arbitrary number of Department rows whenever we’re creating a new Company.

insert(
  companyFixture({
    name: "Google",
    departments: [
      {
        name: "Research & Development",
      },
      {
        name: "Quality Assurance",
      },
    ],
  })
);

When we apply the same principle between Department and Employee, we’re able to create an entire tree of customizable fixtures with a single declaration. Going back to the original test, it would now be something like this.

describe("salary_calculator", () => {
  it("calculates the average salary of all employees", () => {
    const db = inMemoryDatabase();

    const insert = fixtureInserter(db);
    insert(
      companyFixture({
        departments: [
          {
            employees: [
              {
                salary: 100_000,
              },
              {
                salary: 200_000,
              },
            ],
          },
        ],
      })
    );

    const averageSalary = calculateAverageSalary(db);
    equal(averageSalary, 150_000);
  });
});

With another layer of boilerplate gone, important salary numbers stand out even more. Creating additional test cases with a similar setup, but different salaries or department structures is also now trivial, without having to set anything up in beforeAll/beforeEach. We could stop here and call it a day, but sometimes the hierarchy isn’t just 3 levels deep. And do we really care about departments and companies in this test at all?

Bidirectional Relational Fixtures

If we can make a Company create Department and Employee records on demand, could an Employee create Department and Company records as well? Of course!

In fact, given the recursive nature of our fixturing, all we need to do is update types a bit and call parent fixtures from children. In the case of employeeFixture, we’d add department as an optional property.

type EmployeeFixtureProps = Omit<
  Parameters<typeof buildEmployee>[0],
  "departmentId"
> & {
  department?: DepartmentFixtureProps;
};

With the types updated, all we need to do is call departmentFixture to get a department id before trying to insert any Employee records.

export function employeeFixture(props?: EmployeeFixtureProps) {
  return (db: Database): Employee => {
    const { department: departmentProps = {}, ...employeeProps } = props ?? {};

    const department = departmentFixture(departmentProps)(db);
    const employee = db
      .table("employees")
      .insert(buildEmployee({ ...employeeProps, departmentId: department.id }));

    return employee;
  };
}

As long as departmentFixture is also updated to recursively call companyFixture, all required records will still be created in the correct order and we can create customizable dependency trees whichever way we want.

// Customizing the entire tree
insert(
  employeeFixture({
    firstName: "Fooby",
    department: {
      name: "R&D",
      company: {
        name: "Google",
      },
    },
  })
);

// Also magically works
insert(employeeFixture({ firstName: "Fooby" }));

Since our functions can now be called in both directions, we also need to add a short-circuit to avoid creating any entites that have already been created. In our example case, already inserted entites can be identified by the presence of id field, so we just need to check for that.

type Row = { id: number };
function exists<T extends object>(row?: T | Row): row is Row {
  return row !== undefined && "id" in row;
}

This can be used in fixtures as the first thing to return early when called with an existing fixture, like so:

export function companyFixture(props?: CompanyFixtureProps | Company) {
  return (db: Database): Company => {
    if (exists(props)) {
      return props as Company;
    }

With everything in place, let’s go back to the original example test one last time, again substituting fixtures with what we just created.

describe("salary_calculator", () => {
  it("calculates the average salary of all employees", () => {
    const db = inMemoryDatabase();

    const insert = fixtureInserter(db);
    insert(employeeFixture({ salary: 100_000 }));
    insert(employeeFixture({ salary: 200_000 }));

    const averageSalary = calculateAverageSalary(db);
    equal(averageSalary, 150_000);
  });
});

There’s hardly anything left of the original fixturing setup and at this point, it’s essentially impossible to miss the details. It’s still trivial to add more complex test cases with different departments across multiple companies while keeping the simple cases simple.

Bonus

Returning nested structures

In more complex scenarios, it might be difficult or impossible to use declarative fixtures in every situation. To mitigate it, it’s possible to combine returning complex objects and object destructuring. Rather than companyFixture returning a simple Company, we could also recursively return all relations, something like:

type CompanyFixture = Company & {
  departments: DepartmentFixture[];
};

type DepartmentFixture = Department & {
  employees: EmployeeFixture[];
  company: CompanyFixture;
};

type EmployeeFixture = Employee & {
  department: DepartmentFixture;
};

This allows building more complex hierarchies, such as cyclic dependencies between entities and picking individual entities from deep within the hierarchy.

const google = insert(
  companyFixture({
    name: "Google",
    departments: [
      {
        name: "R&D",
        employees: [
          {
            firstName: "Jane",
          },
          {
            firstName: "John",
          },
        ],
      },
    ],
  })
);

const {
  departments: [
    {
      employees: [jane, john],
    },
  ],
} = google;

await insert(
  departmentFixture({
    company: google,
    name: "Quality Assurance",
  })
);

Fixture Variants

Over time, certain types of common entites may emerge as frequently used across tests. These variants or flavors of entities can be made into their own inserters to reduce divergence. For example, given a generic userFixture, you might also introduce adminFixture, anonymousUser inserters, which are just thin wrappers around userFixture with a subset of fields already overridden.

const adminFixture = (user?: Omit<UserFixtureProps, "role">) =>
  userFixture({ ...user, role: Role.Admin });

Async support

What about async support? Everything here works equally well with a sprinkling of Promise, await and async across all type definitions. They’ve only been omitted in these examples for brevity.

Seed data

Declarative fixtures are a nice way to be able to quickly define a known set of seed data to populate local development as well as special purpose environments and deployments for sales or demo purposes.

Future Work

While the developer experience of using declarative fixtures is already pretty good, more can be done to clean up fixture definitions. Since the definitions are mostly identical, there should be room for improvement when it comes to setting up hierarchies.

Got feedback or interesting projects to work on? Get in touch!