🐳 Contêineres

History

Version	Changes
v3.0.3-canary.86e2832e	Migrate Docker functionality to a dedicated package.

Uma API mínima para auxiliar testes que requerem contêineres ou testes que são executados dentro de contêineres.

Esse auxiliar pressupõe que você já tem uma compreensão básica de como o Docker funciona.

Install

npm i -D @pokujs/docker

Usage

Docker Compose

Inicie contêineres a partir de um docker-compose.yml em segundo plano.

import { docker } from '@pokujs/docker';

const compose = docker.compose();

// Inicia o(s) contêiner(es)
await compose.up();

/**
 * Testes vêm aqui 🧪
 */

// Interrompe o(s) contêiner(es)
await compose.down();

Options

export type DockerComposeConfigs = {
  /**
   * Especifica o caminho do **docker-compose.yml**
   *
   * ---
   *
   * @default "./docker-compose.yml"
   */
  file?: string;

  /**
   * Especifica o nome do projeto.
   */
  projectName?: string;

  /**
   * Especifica um caminho `.env` para o **docker-compose.yml**.
   */
  envFile?: string;

  /**
   * Define o diretório raiz onde o processo irá rodar.
   *
   * ---
   *
   * @default "."
   */
  cwd?: string;

  /**
   * Força a reconstrução das imagens (**Dockerfile**).
   */
  build?: boolean;

  /**
   * Inicia apenas um serviço específico do **docker-compose.yml**.
   */
  serviceName?: string;

  /**
   * Não executa o contêiner em segundo plano e retorna o resultado de saída do processo do contêiner (boolean).
   *
   * - Defina como `false` para testar se um contêiner foi executado e finalizado com sucesso.
   *
   * ---
   *
   * @default true
   */
  detach?: boolean;

  /**
   * Mostra logs do **Docker** em tempo real.
   */
  verbose?: boolean;
};

---

Dockerfile

Constrói e inicia contêineres a partir de Dockerfiles em segundo plano.

import { docker } from '@pokujs/docker';

const dockerfile = docker.dockerfile({
  containerName: 'nome-do-contêiner',
  tagName: 'nome-da-imagem',
});

// Constrói a imagem a partir do Dockerfile
await dockerfile.build();

// Inicia o contêiner
await dockerfile.start();

/**
 * Testes vêm aqui 🧪
 */

// Interrompe e remove tanto o contêiner quanto a imagem
await dockerfile.remove();

• Você também pode usar .stop() para interromper o contêiner de maneira suave sem removê-lo.

Options

export type DockerfileConfigs = {
  /**
   * Especifica o nome da imagem
   *
   * Por exemplo, `"nome"`, `"nome:tag"`.
   */
  tagName: string;

  /**
   * Especifica o nome do contêiner.
   */
  containerName: string;

  /**
   * Especifica o caminho do **Dockerfile**
   *
   * ---
   *
   * @default "./Dockerfile"
   */
  file?: string;

  /**
   * Especifica o caminho de contexto do **Dockerfile**
   *
   * - É diferente do `cwd`.
   *
   * ---
   *
   * @default "."
   */
  context?: string;

  /**
   * Especifica as portas a serem expostas.
   *
   * Por exemplo, `"6000:6000"`, `"8080:80"`, `"127.0.0.1:3306:3306"`.
   */
  ports?: string[];

  /**
   * Especifica as variáveis de ambiente do contêiner.
   *
   * Por exemplo, `"VAR1"`, `"VAR1=value1"`
   */
  environments?: string[];

  /**
   * Especifica um caminho para o arquivo `.env` no **Dockerfile**.
   */
  envFile?: string;

  /**
   * Força a construção da imagem sem cache.
   */
  cache?: boolean;

  /**
   * Não executa o contêiner em segundo plano e retorna o resultado de saída do processo do contêiner (boolean).
   *
   * - Defina como `false` para testar se um contêiner foi executado e finalizado com sucesso.
   *
   * ---
   *
   * @default true
   */
  detach?: boolean;

  /**
   * Define o diretório raiz onde o processo irá rodar.
   *
   * ---
   *
   * @default "."
   */
  cwd?: string;

  /**
   * Mostra logs do **Docker** em tempo real.
   */
  verbose?: boolean;
};

---

Exemplos Reais

Testes realizados dentro de um contêiner (docker-compose.yml) em um serviço específico com imagens personalizadas (Dockerfile), retornando a saída, interrompendo os contêineres e limpando as imagens:

• test/compatibility/bun-canary.test.ts

---

Testes realizados dentro de um contêiner (Dockerfile), retornando a saída, interrompendo o contêiner e limpando a imagem:

• test/compatibility-by-dockerfile/bun-canary.test.ts

---

Inicia um contêiner antes de toda a suíte de testes e o interrompe ao finalizar:

Exemplo de API do Poku.

import { poku, exit } from 'poku';
import { docker } from '@pokujs/docker';

const compose = docker.compose({ cwd: './test/docker' });

// Remove o contêiner se ele já existir antes de iniciar
await compose.down();

// Inicia o contêiner
await compose.up();

const result = await poku('./test/integration', {
  noExit: true,
});

// Interrompe o contêiner
await compose.down();

// Mostra os resultados dos testes e finaliza o processo com o código de saída do teste.
exit(result);

node run.test.mjs

---

observação

Esta não é uma API completa e robusta projetada para criar um ORM para Docker, mas uma API mínima focada em necessidades comuns de integração e teste de ponta a ponta.