diff --git a/TEST_ENVIRONMENT.md b/TEST_ENVIRONMENT.md
new file mode 100644
index 0000000..c71ca1a
--- /dev/null
+++ b/TEST_ENVIRONMENT.md
@@ -0,0 +1,243 @@
+# Test Environment Setup
+
+This document describes how to set up and use the test environment with mock SCADA and optimizer services for the Calejo Control Adapter.
+
+## Overview
+
+The test environment provides:
+- **Mock SCADA System**: Simulates industrial process data with realistic variations
+- **Mock Optimizer Service**: Provides optimization models for energy, production, and cost
+- **Test Data Generator**: Automatically generates test scenarios and validates the system
+- **Complete Docker Environment**: All services running in isolated containers
+
+## Quick Start
+
+### 1. Setup Test Environment
+
+```bash
+# Run the setup script (this will create all necessary files and start services)
+./scripts/setup-test-environment.sh
+```
+
+### 2. Test Mock Services
+
+```bash
+# Quick test to verify all services are running
+./scripts/test-mock-services.sh
+```
+
+### 3. Cleanup
+
+```bash
+# Stop and remove test services
+./scripts/setup-test-environment.sh --clean
+```
+
+## Services Overview
+
+### Mock SCADA System
+- **Port**: 8081
+- **Purpose**: Simulates industrial SCADA system with process data
+- **Features**:
+  - Real-time process data (temperature, pressure, flow rate, etc.)
+  - Equipment control (pumps, valves, compressors)
+  - Alarm generation
+  - Data variation simulation
+
+**Endpoints:**
+- `GET /health` - Health check
+- `GET /api/v1/data` - Get all SCADA data
+- `GET /api/v1/data/{tag}` - Get specific data tag
+- `POST /api/v1/control/{equipment}` - Control equipment
+- `GET /api/v1/alarms` - Get current alarms
+
+### Mock Optimizer Service
+- **Port**: 8082
+- **Purpose**: Simulates optimization algorithms for industrial processes
+- **Features**:
+  - Energy consumption optimization
+  - Production efficiency optimization
+  - Cost reduction optimization
+  - Forecast generation
+
+**Endpoints:**
+- `GET /health` - Health check
+- `GET /api/v1/models` - Get available optimization models
+- `POST /api/v1/optimize/{model}` - Run optimization
+- `GET /api/v1/history` - Get optimization history
+- `POST /api/v1/forecast` - Generate forecasts
+
+### Calejo Control Adapter (Test Version)
+- **Port**: 8080
+- **Purpose**: Main application with test configuration
+- **Features**:
+  - Dashboard interface
+  - REST API
+  - Integration with mock services
+  - Health monitoring
+
+## Test Scenarios
+
+The test environment supports multiple scenarios:
+
+### 1. Normal Operation
+- All services running normally
+- Stable process data
+- No alarms
+
+### 2. High Load
+- Simulated high production load
+- Increased energy consumption
+- Potential efficiency drops
+
+### 3. Low Efficiency
+- Suboptimal process conditions
+- Reduced production efficiency
+- Optimization recommendations
+
+### 4. Alarm Conditions
+- Triggered alarms (high temperature, high pressure)
+- Emergency response testing
+- Safety system validation
+
+### 5. Optimization Testing
+- Energy optimization scenarios
+- Production optimization
+- Cost reduction strategies
+
+## Usage Examples
+
+### Testing SCADA Integration
+
+```bash
+# Get current SCADA data
+curl http://localhost:8081/api/v1/data
+
+# Control equipment
+curl -X POST http://localhost:8081/api/v1/control/pump_1 \
+  -H "Content-Type: application/json" \
+  -d '{"command": "START"}'
+
+# Check alarms
+curl http://localhost:8081/api/v1/alarms
+```
+
+### Testing Optimization
+
+```bash
+# Get available optimization models
+curl http://localhost:8082/api/v1/models
+
+# Run energy optimization
+curl -X POST http://localhost:8082/api/v1/optimize/energy_optimization \
+  -H "Content-Type: application/json" \
+  -d '{"power_load": 450, "time_of_day": 14, "production_rate": 95}'
+
+# Get optimization history
+curl http://localhost:8082/api/v1/history?limit=5
+```
+
+### Testing Calejo API
+
+```bash
+# Health check
+curl http://localhost:8080/health
+
+# Dashboard access
+curl http://localhost:8080/dashboard
+
+# API status
+curl http://localhost:8080/api/v1/status
+```
+
+## Development Workflow
+
+### 1. Start Test Environment
+```bash
+./scripts/setup-test-environment.sh
+```
+
+### 2. Run Tests
+```bash
+# Run unit tests
+python -m pytest tests/unit/
+
+# Run integration tests
+python -m pytest tests/integration/
+
+# Run comprehensive test suite
+python -m pytest tests/
+```
+
+### 3. Generate Test Data
+```bash
+# Run the test data generator
+./scripts/setup-test-environment.sh
+# (The script automatically runs the test data generator)
+
+# Or run it manually
+docker-compose -f docker-compose.test.yml run --rm test-data-generator
+```
+
+### 4. Monitor Services
+```bash
+# View all logs
+docker-compose -f docker-compose.test.yml logs -f
+
+# View specific service logs
+docker-compose -f docker-compose.test.yml logs -f calejo-control-adapter-test
+```
+
+## Configuration
+
+The test environment uses `docker-compose.test.yml` which includes:
+
+- **calejo-control-adapter-test**: Main application with test configuration
+- **calejo-postgres-test**: PostgreSQL database
+- **calejo-mock-scada**: Mock SCADA system
+- **calejo-mock-optimizer**: Mock optimizer service
+- **calejo-test-data-generator**: Test data generator
+
+## Troubleshooting
+
+### Services Not Starting
+- Check if Docker is running: `docker ps`
+- Check if ports are available: `netstat -tulpn | grep 8080`
+- View logs: `docker-compose -f docker-compose.test.yml logs`
+
+### Health Checks Failing
+- Wait for services to initialize (30 seconds)
+- Check individual service health:
+  ```bash
+  curl http://localhost:8080/health
+  curl http://localhost:8081/health
+  curl http://localhost:8082/health
+  ```
+
+### Mock Services Not Responding
+- Restart services: `docker-compose -f docker-compose.test.yml restart`
+- Recreate containers: `docker-compose -f docker-compose.test.yml up -d --force-recreate`
+
+## Cleanup
+
+To completely remove the test environment:
+
+```bash
+# Stop and remove containers
+./scripts/setup-test-environment.sh --clean
+
+# Remove created files (optional)
+rm docker-compose.test.yml
+rm -rf tests/mock_services/
+```
+
+## Next Steps
+
+After setting up the test environment:
+
+1. **Run the test suite** to validate functionality
+2. **Test integration scenarios** with the mock services
+3. **Develop new features** using the test environment
+4. **Validate deployments** before production
+
+For production deployment, use the deployment scripts in the `deploy/` directory.
\ No newline at end of file