π³ Containers
A minimal API to assist tests that require containers or tests that run inside containers.
This helper assumes that you already have a basic understanding of how Docker works.
dockerβ
composeβ
Start containers from a docker-compose.yml in background.
import { docker } from 'poku';
const compose = docker.compose();
// Starts the container(s)
await compose.up();
/**
* Tests come here π§ͺ
*/
// Stops the container(s)
await compose.down();
Options
export type DockerComposeConfigs = {
/**
* Specifies the **docker-compose.yml** path
*
* ---
*
* @default "./docker-compose.yml"
*/
file?: string;
/**
* Specifies the project name.
*/
projectName?: string;
/**
* Specifies a `.env` path to **docker-compose.yml**.
*/
envFile?: string;
/**
* Defines the root directory where the process will run.
*
* ---
*
* @default "."
*/
cwd?: string;
/**
* Forces the images (**Dockerfile**) to be rebuilt.
*/
build?: boolean;
/**
* Starts only a specific **docker-compose.yml** service.
*/
serviceName?: string;
/**
* Doesn't run the container in the background and returns the container's process exit result (boolean).
*
* - Set to `false` to test whether a container was executed and finished successfully.
*
* ---
*
* @default true
*/
detach?: boolean;
/**
* Show logs from **Docker** in real time.
*/
verbose?: boolean;
};
dockerfileβ
Build and start containers from Dockerfiles in background.
import { docker } from 'poku';
const dockerfile = docker.dockerfile({
containerName: 'container-name',
tagName: 'image-name',
});
// Builds the image from the Dockerfile
await dockerfile.build();
// Starts the container
await dockerfile.start();
/**
* Tests come here π§ͺ
*/
// Stops and removes both the container and image
await dockerfile.remove();
- You can also use
.stop()
to graceful stop the container without removing it.
Options
export type DockerfileConfigs = {
/**
* Specifies the imange name
*
* E.g., `"name"`, `"name:tag"`.
*/
tagName: string;
/**
* Specifies the container name.
*/
containerName: string;
/**
* Specifies the **Dockerfile** path
*
* ---
*
* @default "./Dockerfile"
*/
file?: string;
/**
* Specifies the context path of the Dockerfile
*
* - It's different from `cwd`.
*
* ---
*
* @default "."
*/
context?: string;
/**
* Specifies the ports to expose.
*
* E.g., `"6000:6000"`, `"8080:80"`, `"127.0.0.1:3306:3306"`.
*/
ports?: string[];
/**
* Specifies the container environments variables.
*
* E.g, `"VAR1"`, `"VAR1=value1"`
*/
environments?: string[];
/**
* Specifies a `.env` path to **Dockerfile**.
*/
envFile?: string;
/**
* Forces the image build without cache.
*/
cache?: boolean;
/**
* Doesn't run the container in the background and returns the container's process exit result (boolean).
*
* - Set to `false` to test whether a container was executed and finished successfully.
*
* ---
*
* @default true
*/
detach?: boolean;
/**
* Defines the root directory where the process will run.
*
* ---
*
* @default "."
*/
cwd?: string;
/**
* Show logs from **Docker** in real time.
*/
verbose?: boolean;
};
Real Examplesβ
Tests performed inside a container (docker-compose.yml) in a specific service with customized images (Dockerfile), returning the output, stopping the containers and cleaning up the images:
Tests performed inside a container (Dockerfile), returning the output, stopping the container and cleaning up the image:
Starts a container before the entire test suite and stops it on finishing:
Poku API example.
import { poku, docker, exit } from 'poku';
const compose = docker.compose({ cwd: './test/docker' });
// Removes the container if it already exists before to start
await compose.down();
// Starts the container
await compose.up();
const result = await poku('./test/integration', {
noExit: true,
});
// Stops the container
await compose.down();
// Shows the test results and ends the process with the test exit code.
exit(result);
node run.test.mjs
This isn't a complete and robust API designed to create an ORM for Docker, but a minimal API focused on common integration and end-to-end testing needs.