A Vitest environment for running test containers via a config file

Installation

npm install -D vitest-environment-testcontainers-support

pnpm install -D vitest-environment-testcontainers-support

yarn add -D vitest-environment-testcontainers-support

Configuration

Create a testcontainers.config.js file in the root of your project. This file should export an object with keys being container names and values being the container configs.

You can find the full config type definition here

Below is an example for localstack:

module.exports = {
    localstack: {
        image: "localstack/localstack",
        ports: [4566],
        env: {
            SERVICES: "s3,eventbridge,events,sqs,ssm,secretsmanager",
            DEFAULT_REGION: "eu-west-1",
            DEBUG: "1",
            LS_LOG: "trace",
        },
        wait: {
            type: "text",
            text: "Ready.",
        },
    },
}

Wait Configs

Text

Wait for particular text to appear in the container logs:

{
    type: "text",
    text: "Ready."
}

Port

Wait for the container's defined ports to be open:

{
    type: "port",
}

Healthcheck

Wait for the container's healthcheck to pass:

{
    type: "healthcheck",
    timeout: 10000 // Timeout in ms
}

Http Status

Wait for the container to return a particular status code from an endpoint:

{
    type: 'httpStatus'
    path: "/check"
    port: 8080
    status: 200
}

Usage

Set your vitest.config.js to use the environment and configuration:

// Set location of the test containers config file
process.env.TEST_CONTAINERS_CONFIG_FILE = `${__dirname}/testcontainers.config.js`

 module.exports = defineConfig({
    test: {
        // ...
        environment: 'testcontainers', 
    },
})