DEV Community: John Teague

Using TestContainers with Vitest

John Teague — Tue, 18 Feb 2025 04:50:24 +0000

Testing frameworks and utilities have progressed greatly over the past few years. TestContainers make creating isolated, lightweight dependencies to test an application's complete functionality easy and quick and reducing the need to mock large parts of your system.

Vitest is a super-fast testing framework that is a drop-in replacement for Jest. It achieves speed improvements mostly by parallelizing test suites. However, if you are testing APIs with TestContainers, that parallelism can make things tricky.

Test Setup the old way

When using older frameworks that run your test serially, like Mocha or Jest, you usually have a setup something like:

beforeAll(async () => {
  // setup database

})

beforeEach(async () => {
  // drop all tables
});
 // run your tests

This doesn't work out very well with Vitest. Since test suites are parallelized, one test suite might finish while another test is still running and drop all your tables when you don't expect it.

TestContainers with Vitest

You need to do some things to set TestContainers up to run successfully with Vitest. In this example, we're creating a Fastly server using Postgres as a database.

Let's use a simple User type to start with:

export interface User {
  firstName: string,
  lastName: string,
  age: number

I use efate to generate test fixtures.

import {defineFixture} from 'efate';
export UserFixure = defineFixture<User>(t => {
  t.firstName.asString();
  t.lastName.asString();
  t.age.asNumber();

Database initialization

You need to initialize the database test container before your tests start. This is the most expensive part of the initialization process, so you should only do it once when you start your test run. We will define a global-setup.ts file and register it with the vite.confit.ts file.

You must also provide a test setup and teardown for each test suite, which we will define in a test-setup.ts file.


//vite.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node',
    globals: true,

    globalSetup: './src/test-config/global-setup.ts',
    setupFiles: ['./src/test-config/test-setup.ts'],
  },
});

We're also going to extend the Vitest ProvidedContext type with our database information.

//global-setup.ts
declare module 'vitest' {
  export interface ProvidedContext {
    pgConfig: {
      host: string;
      port: string;
      username: string;
      password: string;
      database: string | undefined;
    };
}

Then, we will spin up the test container and clean the docker containers after the tests.

We will set up environment variables for the app and also pass information from the setup to the test context.

// global-setup.ts
// runs at the start of the test run only once

export default async function setup({ provide }) {
  console.log('setup: setting up postgres container');
  const pgContainer = await new PostgreSqlContainer().start();
  process.env.DB_URL = pgContainer.getConnectionUri());
  process.env.DB_HOST = pgContainer.getHost();
  process.env.DB_PORT = pgContainer.getPort().toString();
  process.env.DB_USER = pgContainer.getUsername();
  process.env.DB_PASS = pgContainer.getPassword();

  // use the provide function to make this data available to our test suites
  provide('pgConfig', {
    host: 'localhost',
    port: pgContainer.getPort(),
    username: pgContainer.getUsername(),
    password: pgContainer.getPassword(),
  });

  // return the teardown function to clean up
  return function teardown() {
    console.log('*** teardown -- stopping postgres container');
    pgContainer.stop().then(() => console.log('*** teardown -- container stopped'));
  };
}

Passing Data from Global setup to Tests

The global-setup file runs in a different thread context than the tests, so passing data to the test context is not straightforward. Vitest provides two functions to make this possible:

provide is used in global setup to make data available to your tests
inject is used to retrieve information from the global thread.

It's passing through thread contexts, so the data must be simple data structures that can be serialized.

Test Setup

Now that we have our Postgres server running in the container, we need to set up our tests so that they can run independently and in isolation. We will create a new database for every test suite to do this.

extend the Vitest context objects
interface ExtendedSuite extends Suite {
  dbName?: string;
}

interface ExtendedFile extends File {
  dbName?: string;
}

// test-setup.ts
beforeAll(async (context: ExtendedSuite | ExtendedFile) => {
  // creating a random database name for each test suite
  const dbName = `test_${new Xid().toString()}`;
  process.env.DB_DATABASE_NAME = dbName;

  context.dbName = dbName;
  // get the database config information from global setup
  const dbConfig = inject('pgConfig');
  const sql = postgres({
    host: dbConfig.host,
    port: dbConfig.port,
    username: dbConfig.username,
    password: dbConfig.password,
    database: dbName,
  })
  await sql`CREATE DATABASE ${sql(dbName)}`.simple();
  // run all database migrations for your new database
  await runMigrations(dbName, dbConfig);
});

afterAll(async (context: ExtendedSuite | ExtendedFile) => {
  const dbConfig = inject('pgConfig');
  const sql = postgres({
    host: dbConfig.host,
    port: dbConfig.port,
    username: dbConfig.username,
    password: dbConfig.password,
    database: dbName,
  })

await sql`DROP DATABASE ${sql(context.dbName as string)}`.simple();

Each test suite now has a separate database so that they can run independently. You no longer have to worry about one test suite clobbering the state of another.

Your Fastify app will use the environment variables set, so when API calls are made, it will use the configuration provided. You can also directly access the database configuration information directly from your tests.

describe('Get User', () => {
  let app: FastifyInstance;
  let sql: Sql;
  let userId: string;
  beforeAll(async context => {
    const dbConfig = inject('pgConfig');
    dbConfig.database = process.env.DB_DATABASE_NAME;
    sql = postgres({ ...dbConfig, port: Number(dbConfig.port), transform: postgres.camel });
  const [userInsert] = await sql`INSERT INTO users ${sql(UserFixture.create(), 'name', 'urlPrefix')} RETURNING *`;
    user = serviceInsert.id;
    app = await buildApp(Fastify());
});
it('should return the user', async () => {
  const response = await app.inject({
  method: 'GET',
  URL: `user/${userId}`,
});

expect(response.statusCode).toBe(200);

})

Efate Test Fixture Generator Series: Extending the library

John Teague — Tue, 06 Sep 2022 03:10:37 +0000

This is a second post in a series discussing test fixture generators and the efate library. The first post discusses how to use efate. This post discusses how you can extend the efate library. You might want to give that a read first to give you a bit of background.

Efate is actually the second test fixture library I've written and there were several lessons I learned after using the first iteration for several years myself. The first version was influenced a great deal by factor_girl (called factory_bot now), with a heavy dependency on strings to define and create the fixtures. It also wasn't very modular. You couldn't just import a specific fixture, you had to bring in the whole library. And it wasn't very extensible, if you needed to define custom behavior for how a field should be created, it wasn't very pretty.

I was able to solve these problems in efate; it's modular by default, some (I would say) clever Typescript practically eliminates strings in definitions, and it was designed to be extensible, which is the subject of this article. You can extend the library by adding your own property builder that lets you define how properties in your object graph should be populated

Creating a Property Builder Plugin

When you define a fixture, you get to determine exactly how each property should be populated, whether it's a string, a date, an email address, property builders are used to generate the value. There are two independent, but linked components that describe the builder and its behavior when populating a field:

An interface that describes the builder function when
An object that has a method that matches the name declared in the interface and returns a curried function that generates value at creation time.

Defining the Property Builder Interface

We'll use the asDate() property builder as our example*. It takes an option during definition to affect its behavior during creation, whether or not the next date is incremented by day. If not, the default behavior to use now as the value of the field.

The first step is to create an interface that describes the method that is used during fixture definition, describing any options that can be expressed during definition. The DateBuilder lets you customize how the date values are created. The interface is relatively simple:

export interface DateBuilderOptions {
    incrementDay: boolean;
}
export interface DateBuilderExtension{
    asDate: (options?: DateBuilderOptions) => void;
}

There is no implementation of this interface, it's just used to define the builder function and what options it provides at fixture definition. My next post will be about efate internals and how this works.

Create the builder object

Okay, the next part is a bit tricky, but once you see the pattern and understand what it's doing it's not so bad. You now need an object that matches the name of the function in the Extension interface, but it will return a curried function that returns a FieldGeneratorFunc

type FieldGeneratorFunc = (increment: number) => Field<any>;
// I'm writing these out as named functions,
// but in the source code you will see these as lambda functions
function asDateBuilder(name: string, [options]: [DateBuilderOptions?] = [defaultOptions]){
    return function dateBuilderGenerator(increment: number){
        const date = new Date();
        if (options?.incrementDay) {
          date.setDate(date.getDate() + (increment - 1));
        }
        return new Field(fieldName, date);
    }
}
export const dateBuilderExtension {
    asDate: asDateBuilder
}

Okay, so let's break this down a bit. The outer function gets executed during fixture definition. It has one required parameter, name that is passed to the function internally when the fixture is defined. The second parameter is the array of arguments that are passed to the definition function. As a convention, I use a single options object for this parameter for consistency. However that is not a requirement.

The second function is executed at creation time and must conform to the FieldGeneratorFunc type definition. The fixture tracks how many times you create a fixture internally and will pass that value as the increment parameter. You can choose how to use this parameter, or ignore it. The function returns a Field<T> object, which is just a simple object that tracks the name of the field and it's value.

Adding your Extension

To Actually extend efate, you need to pass the extension interface as a type parameter and the extension object as a function parameter to the fixture factory.

import {createFixtureFactory} from 'efate';
// import both the interface and the object for the extension
import {DateBuilderExtension, dateBuilderExtension} from 'DateBuilderExtension'
const createFixture = createFixtureFactory<DateBuilderExtension>(dateBuilderExtension);
//start using your extension to build your fixtures

If you have more than one extenstion, you can combine them using a type intersection.

import {createFixtureFactory} from 'efate';
// import both the interface and the object for the extension
import {DateBuilderExtension, dateBuilderExtension} from 'DateBuilderExtension'
import {UUIDExtension, uuidExtension} from 'efate-uuid';
const createFixture = createFixtureFactory<DateBuilderExtension & UUIDExtension>(dateBuilderExtension, uuidExtension);
//start using your extension to build your fixtures
const userFixture = createFixture<User>(t => {
    t.id.asUUID();
    t.date.asDate();
});

Adding the extensible behavior to efate's growing list of internally provided property builders, it should be able to meet any need. It does gets more complicated as you move away from random fields to a complete object graph. efate-uuid is an example of a simple extension you can review. If you come up with a good extension, please consider contributing it to the library. I accept pull requests!

*The date builder was the first pass at passing additional options to a builder at design time. There are lots of other ways someone might want to modify the behavior of date generation. As always suggestions and pull requests are welcome.

Make Testing Easier with Test Fixture Generators

John Teague — Mon, 05 Sep 2022 00:59:30 +0000

When building an application, you need to making testing it as easy as possible. Using a test fixture generator can help keep your tests maintainable and easy to modify as your application changes.

Test data anti patterns

When you first starting building an application, it's easy to fall into some anti-patterns that can lead to problems as your application grows and matures

Static JSON files

The simplest approach that most people use when creating test data is to use a json file. But this approach can run into problems when you need to test different scenarios.
Lets say you have a user object that you've put into a json file
test-user.json

{
    "firstName": 'John',
    "lastName": "Doe",
    "isActive": true
}

And import it into your test. But this is now a single instance of the object, so any changes you make will be reflected in all tests in the file. It can lead do

import user from './test-user.json'
describe('tests with user', () => {
    it('should do something when the user is disabled', () => {
        user.isActive = false
        //...
    })
    it('should do something when user is enabled', () => {
        //user is disabled in this test because it was changed in the previous test.
    })
})

This can lead unexpected test failures that can be spot. The more complex the variations, the harder it is to setup your tests correctly. You might be tempted to create different test objects that set to specific states the object could be in for different tests. But that creates another set of problems, because if the object shape changes, you'll need to change multiple states.

When to use

Okay, it's a bit harsh to call this an anti-pattern. Using static JSON files works best when it's static data that doesn't really change or changes to it does not affect the behavior of your application. I typically have a combination of JSON fixtures along side generated fixtures and use them in tandem.

Partial Objects

Another common approach is to include a partial object with each test that have the fields of interest for the test.

it('should do something when the user is disabled', () => {
        const user = {isActive: false}
        //...
    })
    it('should do something when user is enabled', () => {
        const user = {isActive: true}
        // ...        
    })

This can create a lot of duplication throughout your test code, and if the behavior of your system changes where you need to change the shape or use other fields for making decisions, you've now got a bunch of test data scattered throughout your tests that will need to change.

When to use

Never. Honestly, don't do this. Either use a static JSON file where you'll have a valid object and kept in one place in your code, so you will only need to make changes in one place when that is needed.

Test fixture Generators

Using a test fixture generator solves all of these problems. The test fixture is defined only once, so if there are changes to your object graph, you'll make those changes only once and all tests will be updated.

Test fixtures are created each time you need them, so if you change your fixture, it will not effect other tests (unless you want them too). Those weird test failures will go away and your test harness will be more reliable. As a result, your tests will be easier to manage as your application grows. It also puts developers into the pit of success when creating tests; lowering the barrier to writing more and better tests for your app.

Efate, a modern test fixture generator

Efate is a modern test fixture generator, design for use in JavaScript or Typescript. generates modular fixtures that can be imported in and reduces the use of strings for both fixture definition and usages. It allows you to override specific fields during fixture creation and returning full object definitions with dummy data for other fields. It is also extensible, allowing you to create custom field generator definitions.

Defining a fixture

Let's assume you have a typscript interface for your User object

export interface Account {
  userName: string;
  passWord: string;
}
export interface User {
    interface User {
    id?: number;
    email: string;
    dateStarted: Date;
    roles: string[];
    isActive: boolean;
    account: Account
}

To define a fixture, you need to import a fixture generator factory. The factory is used to allow for extensibility, which we'll talk about in a later post. The factory will return a function used to create the fixtures.

Then you will create the fixture, specifying how each field should be populated.

import {createFixtureFactory} from 'efate';
const createFixture = createFixtureFactory();
const accountFixture = createFixture<Account>(t => {
    t.userName.asString();
    t.password.asString();
})
const userFixture = createFixture<User>(t => {
    t.id.asNumber();
    t.firstName.asString();
    t.email.asEmail();
    t.dateStarted.asDate({ incrementDay: true }));
    t.roles.asArray();
    t.isActive.asBoolean();
    t.account.fromFixture(accountFixture);
})
export {accountFixture, userFixture};

As you can see, you have control over how each field in your object will be created. Some of the definition functions, like asDate takes additional options to control how they are generated. You can also nest your fixtures together to create a robust object graph and the entire graph will be valid. There are a lot more definition functions to use for different types, or with different behavior to give you the flexibility you need to create your fixtures as need. Or you can pass your own function to have complete control over field definition.

If you're using TypeScript, you'll get full autocomplete on the type parameter in the createFixture callback function, making it really easy to create fixtures.

Using a fixture

To use these fixtures in your tests, you simple import the fixture

import userFixture from './fixtures';
define('test group', () => {
    it('should use the user object', () => {
        // creates a user with all default values;
        const user = userFixture.create(); 
        //...
    })
})

This creates a fully populated user object with all field populated with dummy data.

    {
        id: 1,
        firstName: 'firstName1',
        email: 'email1@test.com',
        dateStarted: // valid date object
        roles: ['role1', 'role2', 'role3']
        isActive: true,
        account: {
            userName: 'userName1',
            password: 'password1'
        }
    }

Calling create again in the same module will increment the number on each value so they are different, but follow a simple pattern.

If you need to create an object with specific values, you pass an object with the fields you need to specify. If you're using typescript, the overriding object will be typed so you can get autocomplete help there as well.

const user = userFixture.create({isActive: true, roles:['user']);

It creates an object just like above, but those fields have been overridden

    {
        id: 2, // incremented if in the same module as previous fixture,
        firstName: 'firstName2',
        //...
        isActive: true,
        roles: ['user']
    }

You can also override nested objects as well, and all other fields still automatically populated

    /*
    will create a user with account.firstName overridden, but account.password still generated
    */
    const user = userFixture.create({account: {userName: 'custom user name'});

You can also create arrays of data with different ways of overriding the objects in the array

      // create an array with 5 entries, all generated data
      const fixtures = userFixture.createArrayWith(5);

      // create an array with 5 entries, all with the isActive field overridden
      const fixtures = userFixture.createArrayWith(5, {isActive: true});

      // create an array with the first 2 entries overriden
      const fixtures = userFixture.createArrayWith(5, [
      {isActive: true},
      {isActive: false}
      ]);

      // use a function to override array entries
      const fixtures = userFixture.createArrayWith(5, (idx, create) => {
          if(idx < 2){
              return create({firstName: 'alpha'})
          } else {
              return create({firstName: 'beta'})
          }
      })

There's a lot more ways to customize your fixtures, The tests are a good way of seeing all of the features and how they work.

I've built lots applications over the course of my career and thousands of tests. Each time that I don't think I need a test fixture generator, I always end up regretting it. I treat my test code like I do my application code. I want it to be as easy to understand as possible with as little duplication as possible. Using generators like efate have helped me do that. I hope it can do the same for you. If you have any suggestions on features to add or suggestions to make it easier to use, I would love your feedback (or better yet a pull request!).