vitest-environment-testcontainers

A Vitest environment with integrated support for Testcontainers.

Features

• ⚙️ Setup and teardown containers automatically during Vitest runs.
• ✏️ Type-safe interface.
• 📖 Access container metadata during test runtime.

Requirements

• Docker
• Vitest

Quickstart

1. Install vitest-environment-testcontainers.

npm i -D vitest-environment-testcontainers

2. Configure Vitest in vitest.config.ts to use the environment.

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    // ...
    environment: "testcontainers",
  },
});

See here for more information on how to configure Vitest.

3. Specify the containers to launch.

import { type EnvironmentOptions } from "vitest-environment-testcontainers";

const environmentOptions: EnvironmentOptions = {
  testcontainers: {
    containers: [
      {
        name: "database",
        image: "postgres:latest",
        ports: [5432],
        environment: {
          POSTGRES_USER: "root",
          POSTGRES_PASSWORD: "root",
          POSTGRES_DB: "test",
        },
        wait: {
          type: "PORT",
        },
      },
    ],
  },
};

export default defineConfig({
  test: {
    // ...
    environment: "testcontainers",
    environmentOptions,
  },
});

4. Get information about the containers inside your tests.

describe("Test", () => {
  const containers = globalThis.testcontainers.containers;

  // ...
});

The containers array contains objects of the following type:

{
  name: string;
  host: string;
  ports: Map<number, number>;
  configuration: ContainerConfiguration;
}

Property	Description
name	The name of the container as specified in the environment options.
host	The hostname by which the container is accessible from.
ports	A mapping of exposed container ports to their respective host ports.
configuration	The original configuration of the container as specified in the environment options.