# Test Environment Template

Save as `DOCUMENT_DIR/tests/environment.md`.

---

```markdown
# Test Environment

## Overview

**System under test**: [main system name and entry points — API URLs, message queues, serial ports, etc.]
**Consumer app purpose**: Standalone application that exercises the main system through its public interfaces, validating black-box use cases without access to internals.

## Docker Environment

### Services

| Service | Image / Build | Purpose | Ports |
|---------|--------------|---------|-------|
| system-under-test | [main app image or build context] | The main system being tested | [ports] |
| test-db | [postgres/mysql/etc.] | Database for the main system | [ports] |
| e2e-consumer | [build context for consumer app] | Black-box test runner | — |
| [dependency] | [image] | [purpose — cache, queue, mock, etc.] | [ports] |

### Networks

| Network | Services | Purpose |
|---------|----------|---------|
| e2e-net | all | Isolated test network |

### Volumes

| Volume | Mounted to | Purpose |
|--------|-----------|---------|
| [name] | [service:path] | [test data, DB persistence, etc.] |

### docker-compose structure

```yaml
# Outline only — not runnable code
services:
  system-under-test:
    # main system
  test-db:
    # database
  e2e-consumer:
    # consumer test app
    depends_on:
      - system-under-test
```

## Consumer Application

**Tech stack**: [language, framework, test runner]
**Entry point**: [how it starts — e.g., pytest, jest, custom runner]

### Communication with system under test

| Interface | Protocol | Endpoint / Topic | Authentication |
|-----------|----------|-----------------|----------------|
| [API name] | [HTTP/gRPC/AMQP/etc.] | [URL or topic] | [method] |

### What the consumer does NOT have access to

- No direct database access to the main system
- No internal module imports
- No shared memory or file system with the main system

## CI/CD Integration

**When to run**: [e.g., on PR merge to dev, nightly, before production deploy]
**Pipeline stage**: [where in the CI pipeline this fits]
**Gate behavior**: [block merge / warning only / manual approval]
**Timeout**: [max total suite duration before considered failed]

## Reporting

**Format**: CSV
**Columns**: Test ID, Test Name, Execution Time (ms), Result (PASS/FAIL/SKIP), Error Message (if FAIL)
**Output path**: [where the CSV is written — e.g., ./e2e-results/report.csv]
```

---

## Guidance Notes

- The consumer app must treat the main system as a true black box — no internal imports, no direct DB queries against the main system's database.
- Docker environment should be self-contained — `docker compose up` must be sufficient to run the full suite.
- If the main system requires external services (payment gateways, third-party APIs), define mock/stub services in the Docker environment.