---
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 <jeremy@intentsolutions.io>
license: MIT
tags:
- testing
- test-environments
compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
---
# 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:**

```yaml
# 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:**

```typescript
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