Test Environment Manager

Overview

Provision, configure, and manage isolated test environments for reliable test execution. Supports Docker Compose environments, Testcontainers, local service stacks, and ephemeral CI environments.

Prerequisites

• Docker and Docker Compose installed (for containerized environments)
• Testcontainers library installed if using programmatic container management
• Database client tools (psql, mysql, mongosh) for seed data operations
• Environment variable management via

  .env

  files or secrets manager
• Sufficient disk space and memory for running service containers

Instructions

1. Read the project's existing configuration files (

   docker-compose.yml

   ,

   .env.test

   ,

   jest.config.*

   ,

   pytest.ini

   ) to understand current environment setup.
2. Inventory all external dependencies the test suite requires (databases, message queues, cache servers, third-party API stubs).
3. Create or update a

   docker-compose.test.yml

   defining isolated service containers:
   • Assign non-conflicting ports to avoid collisions with development services.
   • Configure health checks for each service to prevent tests from starting before services are ready.
   • Set resource limits (memory, CPU) to match CI runner constraints.
4. Write seed data scripts that populate databases with baseline test data:
   • Use idempotent migrations that can run repeatedly without error.
   • Create separate seed datasets for unit, integration, and E2E test tiers.
   • Include cleanup scripts that truncate tables without dropping schemas.
5. Generate environment configuration files (

   .env.test

   ) with connection strings, API keys, and feature flags appropriate for testing.
6. Create a startup script that orchestrates the full environment lifecycle:
   • Start containers and wait for health checks to pass.
   • Run database migrations and seed data.
   • Export environment variables for the test runner.
   • Execute the test suite.
   • Tear down containers and clean up volumes.
7. Validate the environment by running a small smoke test suite against the provisioned services.

Output

• docker-compose.test.yml

  with all required service definitions

• .env.test

  with test-specific configuration values
• Database seed scripts (

  seeds/test-data.sql

  or equivalent)
• Environment startup/teardown shell script (

  scripts/test-env.sh

  )
• Health check verification report confirming all services are operational

Error Handling

docker-compose.test.yml

interval

retries

.env.test

env-cmd

dotenv-cli

--volumes

docker-compose down

tmpfs

Examples

Docker Compose test environment with PostgreSQL and Redis:

# docker-compose.test.yml
services:
  postgres-test:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: testdb
      POSTGRES_PASSWORD: testpass
    ports: ["5433:5432"]  # 5432: 5433: PostgreSQL port
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      retries: 10
  redis-test:
    image: redis:7-alpine
    ports: ["6380:6379"]  # 6379: 6380: Redis TLS port
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

Testcontainers setup in Jest:

import { PostgreSqlContainer } from '@testcontainers/postgresql';

let container;
beforeAll(async () => {
  container = await new PostgreSqlContainer().start();
  process.env.DATABASE_URL = container.getConnectionUri();
}, 30000);  # 30000: 30 seconds in ms
afterAll(async () => { await container.stop(); });

Resources

• Docker Compose documentation: https://docs.docker.com/compose/
• Testcontainers: https://testcontainers.com/
• dotenv-cli for env management: https://github.com/entropitor/dotenv-cli
• 12-Factor App Config: https://12factor.net/config