# Docker Clean Flag Testing Guide

This guide explains the various testing options available for running Docker tests with clean slate functionality.

## 🚀 Quick Start

```bash
# Fast iteration (reuses existing data)
npm run docker:test

# Clean slate testing (guarantees fresh environment)
npm run docker:test:clean
```

## 📋 Available Commands

### Current Testing Approach

| Command                                | Description                                       |
| -------------------------------------- | ------------------------------------------------- |
| `npm run test:integration`             | Full integration test suite with Docker           |
| `npm run test:integration:run`         | Run integration tests (requires running database) |
| `npm run test:integration:manual`      | Manual phase tests (1, 2, 3)                      |
| `npm run test:integration:protocol`    | MCP protocol test                                 |
| `npm run test:integration:performance` | Performance tests                                 |

### Docker Container Management

| Command                     | Description                  |
| --------------------------- | ---------------------------- |
| `npm run docker:test`       | Docker test runner script    |
| `npm run docker:test:clean` | Docker test with clean slate |
| `npm run docker:start`      | Start SQL Server container   |
| `npm run docker:stop`       | Stop SQL Server container    |
| `npm run docker:clean`      | Clean containers and volumes |

> **Note**: Many of the granular `test:manual:docker:*` commands have been consolidated into the simpler `test:integration:*` structure for better maintainability.

### Advanced Script Usage

The `docker-test-runner.sh` script provides flexible testing options:

```bash
# Default (Phase 1 with existing data)
./scripts/docker-test-runner.sh

# Specific phase with existing data
./scripts/docker-test-runner.sh phase1
./scripts/docker-test-runner.sh phase2
./scripts/docker-test-runner.sh phase3
./scripts/docker-test-runner.sh protocol

# All phases with existing data
./scripts/docker-test-runner.sh all

# Any combination with clean slate
./scripts/docker-test-runner.sh phase1 --clean
./scripts/docker-test-runner.sh all --clean
```

## 🧹 Container Management

| Command                  | Description            | Use Case                                            |
| ------------------------ | ---------------------- | --------------------------------------------------- |
| `npm run docker:start`   | Start container        | Initial setup                                       |
| `npm run docker:stop`    | Stop container         | Save resources                                      |
| `npm run docker:restart` | Restart container      | Keep existing data                                  |
| `npm run docker:reset`   | Clean + restart        | Fresh start, same as `docker:clean && docker:start` |
| `npm run docker:clean`   | Remove all data        | Nuclear option                                      |
| `npm run docker:status`  | Check container status | Debugging                                           |

## 🔍 When to Use Each Option

### 🏃‍♂️ **Fast Iteration (Default)**

**Use for**: Development, debugging, repeated testing

```bash
npm run docker:test              # Quick docker test runner
npm run test:integration         # Full integration test suite
```

**Pros**:

- ⚡ Fast startup (2-3 seconds)
- 💾 Preserves existing data
- 🔄 Good for iterative development

**Cons**:

- 🗑️ May have leftover test data
- 🧪 Not guaranteed clean environment

### 🧹 **Clean Slate (Guaranteed Fresh)**

**Use for**: CI/CD, production validation, troubleshooting

```bash
npm run docker:test:clean        # Clean docker test
npm run docker:clean && npm run test:integration # Full clean test suite
```

**Pros**:

- ✅ Guaranteed clean environment
- 🔒 No leftover test data
- 🎯 Consistent results

**Cons**:

- 🐌 Slower startup (30-60 seconds)
- 💽 Rebuilds all data each time

## 📊 Performance Comparison

| Operation       | Fast Mode   | Clean Mode   | Difference  |
| --------------- | ----------- | ------------ | ----------- |
| Phase 1 Test    | ~15 seconds | ~45 seconds  | +30 seconds |
| All Phases      | ~60 seconds | ~120 seconds | +60 seconds |
| Container Start | ~3 seconds  | ~45 seconds  | +42 seconds |

## 🛠️ Troubleshooting

### Container Won't Start

```bash
npm run docker:status           # Check if running
npm run docker:logs             # Check container logs
npm run docker:clean            # Nuclear reset
```

### Tests Failing Due to Data Conflicts

```bash
npm run docker:reset            # Reset with fresh data
./scripts/docker-test-runner.sh phase1 --clean  # Clean specific test
```

### Cleanup Issues in Read-Only Mode

The test cleanup may fail when in read-only mode. This is expected behavior and doesn't affect test results. Use clean flag for guaranteed cleanup:

```bash
npm run docker:clean && npm run test:integration  # Forces cleanup
```

### Performance Issues

If Docker is slow:

```bash
# Check Docker resource allocation
docker system df

# Clean unused resources
docker system prune -f

# Reset Docker if needed
npm run docker:clean
```

## 📝 Best Practices

### For Development

1. **Start with fast mode** for initial development
2. **Use clean mode** when troubleshooting issues
3. **Run clean tests** before committing changes

### For CI/CD

1. **Always use clean mode** for automated testing
2. **Run all phases** with clean flag
3. **Clean up** after tests complete

### Example Workflows

**Development Workflow:**

```bash
# Start development
npm run docker:start

# Iterate quickly
npm run docker:test              # Fast tests
npm run docker:test              # Repeat as needed

# Final validation
npm run docker:test:clean        # Clean slate verification
```

**CI/CD Workflow:**

```bash
# Guaranteed clean testing
npm run docker:clean && npm run test:integration

# Or just use the built-in clean docker test
npm run docker:test:clean
```

## 🎯 Summary

The clean flag system provides flexibility:

- **🚀 Fast by default**: Optimal for development and iteration
- **🧹 Clean when needed**: Guaranteed fresh environment for validation
- **🎛️ Granular control**: Choose clean flag per test phase
- **📜 Multiple interfaces**: npm scripts, shell script, or manual commands

Choose the right tool for your use case and enjoy efficient Docker testing! 🐳