dance-lessons-coach/scripts/LOCAL_CI_GUIDE.md

# Local CI/CD Testing Guide

This guide explains how to test the CI/CD pipeline locally using the available scripts.

## 📁 Available Scripts

### Core CI Scripts
- `test-local-ci-cd.sh` - Complete local CI/CD simulation
- `test-docker-cache.sh` - Test Docker build cache functionality
- `ci-update-coverage-badge.sh` - Test coverage badge updates
- `ci-version-bump.sh` - Test version bump logic

### Existing Test Scripts
- `run-bdd-tests.sh` - Run BDD tests locally
- `test-graceful-shutdown.sh` - Test graceful shutdown
- `test-opentelemetry.sh` - Test OpenTelemetry integration

## 🚀 Quick Start

### 1. Test Docker Build Cache
```bash
# Test the Docker cache functionality
./scripts/test-docker-cache.sh

# This will:
# 1. Calculate dependency hash (same as CI)
# 2. Build Docker cache image
# 3. Test commands in Docker
# 4. Compare performance
```

### 2. Full Local CI/CD Test
```bash
# Run complete local CI/CD simulation
./scripts/test-local-ci-cd.sh

# This will:
# 1. Install dependencies
# 2. Generate Swagger docs
# 3. Build and test code
# 4. Build binaries
# 5. Simulate version bump
# 6. Optionally build Docker image
```

### 3. Test Specific Components

#### Coverage Badge Updates
```bash
# Test coverage badge update logic
./scripts/ci-update-coverage-badge.sh 75.5
```

#### Version Bump Logic
```bash
# Test version bump with different commit messages
./scripts/ci-version-bump.sh "✨ feat: add new feature"
./scripts/ci-version-bump.sh "🐛 fix: resolve bug"
./scripts/ci-version-bump.sh "Regular commit message"
```

## 🐳 Docker Build Cache Testing

The Docker build cache system works by:

1. **Calculating dependency hash**: `sha256sum go.mod go.sum`
2. **Building cache image**: Only when dependencies change
3. **Using cached image**: For all subsequent CI runs

### Local Testing
```bash
# Build the cache image locally
docker build -t dance-lessons-coach-build-cache -f Dockerfile.build .

# Test running commands in the cached environment
docker run --rm -v "$(pwd):/workspace" -w /workspace \
    dance-lessons-coach-build-cache \
    go test ./... -cover
```

### CI Integration
The CI workflow automatically:
- Calculates the same hash
- Checks if image exists in registry
- Builds new image only when needed
- Uses cached image for all builds

## 🔄 CI/CD Workflow Simulation

To simulate the full CI/CD workflow locally:

```bash
# 1. Run local CI tests
./scripts/test-local-ci-cd.sh

# 2. When prompted, build Docker image
# 3. Test the running container
# 4. Verify all endpoints work

# 5. Test BDD scenarios
./scripts/run-bdd-tests.sh

# 6. Test graceful shutdown
./scripts/test-graceful-shutdown.sh

# 7. Test OpenTelemetry
./scripts/test-opentelemetry.sh
```

## 📊 Performance Comparison

### Without Docker Cache
```
First run:  ~90 seconds
Subsequent: ~90 seconds (no caching)
```

### With Docker Cache
```
First run:  ~120 seconds (build cache)
Subsequent: ~30 seconds (use cache)
Savings:   ~60 seconds per run!
```

## 🎯 Best Practices

1. **Test locally first**: Always run `test-local-ci-cd.sh` before pushing
2. **Check Docker cache**: Run `test-docker-cache.sh` after dependency changes
3. **Verify coverage**: Test coverage badge updates with different percentages
4. **Test version bumps**: Verify version logic with different commit types
5. **Clean up**: Remove test containers and images when done

## 🧪 Advanced Testing

### Test Race Conditions
```bash
# Simulate concurrent CI runs
./scripts/ci-update-coverage-badge.sh 75.5 &
./scripts/ci-update-coverage-badge.sh 75.5 &
wait
```

### Test Version Bump Scenarios
```bash
# Test all version bump scenarios
echo "✨ feat: new feature" > /tmp/test_commit
./scripts/ci-version-bump.sh "$(cat /tmp/test_commit)"

echo "🐛 fix: bug fix" > /tmp/test_commit
./scripts/ci-version-bump.sh "$(cat /tmp/test_commit)"

echo "BREAKING CHANGE: major update" > /tmp/test_commit
./scripts/ci-version-bump.sh "$(cat /tmp/test_commit)"
```

## 🔧 Troubleshooting

### Docker Issues
- **Permission denied**: Add user to docker group or use `sudo`
- **Port conflicts**: Change test port or stop conflicting services
- **Image not found**: Build the image first with `docker build`

### CI Script Issues
- **Missing dependencies**: Install required tools (Go, Docker, etc.)
- **Script permissions**: Run `chmod +x scripts/*.sh`
- **Path issues**: Use full paths or correct working directory

### Performance Issues
- **Slow Docker builds**: Use `--no-cache` for fresh builds
- **Large images**: Check Dockerfile for unnecessary layers
- **Memory issues**: Increase Docker resources in settings

## 📖 Reference

### Docker Commands
```bash
# List images
docker images

# List containers
docker ps -a

# Remove container
docker rm <container_id>

# Remove image
docker rmi <image_id>

# View logs
docker logs <container_id>

# Exec into container
docker exec -it <container_id> sh
```

### CI Commands
```bash
# Run specific CI job
act -j <job_name>

# Test workflow locally
act

# Dry run (show what would run)
act -n
```

## 🎓 Learning Resources

- [Docker Documentation](https://docs.docker.com/)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [Go Testing Documentation](https://pkg.go.dev/testing)
- [CI/CD Best Practices](https://github.com/goldbergyoni/nodebestpractices)

This guide provides everything you need to test the CI/CD pipeline locally before pushing to the repository!