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

# 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

# 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

# Test coverage badge update logic
./scripts/ci-update-coverage-badge.sh 75.5

Version Bump Logic

# 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

# 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:

# 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

# 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

# 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

# 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

# Run specific CI job
act -j <job_name>

# Test workflow locally
act

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

🎓 Learning Resources

• Docker Documentation
• GitHub Actions Documentation
• Go Testing Documentation
• CI/CD Best Practices

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