managing-test-environments

name	managing-test-environments
description	Test provision and manage isolated test environments with configuration and data. Use when performing specialized testing. Trigger with phrases like "manage test environment", "provision test env", or "setup test infrastructure".
allowed-tools	Read, Write, Edit, Grep, Glob, Bash(test:env-*)
version	1.25.0
author	Jeremy Longshore <[e-mail]>
license	MIT
tags	["testing","test-environments"]
compatibility	Designed for Claude Code

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

Error	Cause	Solution
Port already in use	Another process or dev environment occupies the port	Use dynamic port allocation or specify alternate ports in docker-compose.test.yml
Container health check timeout	Service takes too long to initialize	Increase health check interval and retries; ensure sufficient memory allocation
Database seed failure	Migration conflicts or missing schema	Run migrations before seeds; verify migration order; check for schema drift
Environment variable not found	.env.test not loaded or variable misspelled	Verify dotenv loading order; use env-cmd or dotenv-cli to inject variables
Stale Docker volumes	Previous test data persists across runs	Add --volumes flag to docker-compose down in teardown; use tmpfs mounts

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