Manual Validation Checklist¶

This checklist ensures all Makefile targets work correctly and handle edge cases properly.

Prerequisites¶

Docker Desktop is running
Git is installed
Make is available
Project is cloned locally

Core Development Targets¶

1. Environment Initialization¶

`make dev-init`¶

Creates .env.dev file
```
make dev-init
ls -la .env.dev
```

File contains expected variables

grep -q "DEVELOPMENT_MODE=true" .env.dev
grep -q "TESTING=true" .env.dev
grep -q "SKIP_AUTH=true" .env.dev

Handles existing file gracefully

make dev-init  # Should not overwrite existing .env.dev

`make dev-build`¶

Builds backend image

make dev-build
docker images | grep "rag-modulo.*backend.*dev"

Builds frontend image

docker images | grep "rag-modulo.*frontend.*dev"

Shows build progress

make dev-build  # Should show "Building development images..."

Handles build failures gracefully

# Simulate build failure and verify error handling

2. Service Management¶

`make dev-up`¶

Starts all services

make dev-up
docker ps | grep "rag_modulo-dev"

Shows service URLs

make dev-up  # Should show Backend: http://localhost:8000

Creates volume directories
```
ls -la volumes/
```

Handles port conflicts

# Start another service on port 8000, then run make dev-up
# Should show clear error message

`make dev-down`¶

Stops all services

make dev-down
docker ps | grep "rag_modulo-dev"  # Should be empty

Shows confirmation message

make dev-down  # Should show "Development environment stopped"

`make dev-restart`¶

Rebuilds and restarts

make dev-restart
docker ps | grep "rag_modulo-dev"

Shows restart progress

make dev-restart  # Should show "Rebuilding and restarting..."

3. Validation and Status¶

`make dev-validate`¶

Checks image existence

make dev-validate  # Should show "✅ Backend development image found"

Checks container status

make dev-validate  # Should show "✅ All containers running"

Tests backend health

make dev-validate  # Should show "✅ Backend is healthy"

Tests frontend health

make dev-validate  # Should show "✅ Frontend is healthy"

`make dev-status`¶

Shows image status

make dev-status  # Should list all development images

Shows container status

make dev-status  # Should list all running containers

Shows service URLs

make dev-status  # Should show service URLs

`make dev-logs`¶

Shows backend logs

make dev-logs  # Should show backend container logs

Shows frontend logs

make dev-logs  # Should show frontend container logs

Shows all service logs

make dev-logs  # Should show logs from all services

4. Environment Management¶

`make dev-reset`¶

Stops services

make dev-reset  # Should stop all containers

Removes containers

make dev-reset  # Should remove containers

Prunes volumes

make dev-reset  # Should clean up volumes

Shows reset progress

make dev-reset  # Should show "Resetting development environment..."

`make clean-all`¶

Removes all images

make clean-all
docker images | grep "rag-modulo"  # Should be empty

Removes all containers

docker ps -a | grep "rag_modulo"  # Should be empty

Removes all volumes

docker volume ls | grep "rag_modulo"  # Should be empty

Shows cleanup progress

make clean-all  # Should show "Cleaning up all development resources..."

5. Advanced Features¶

`make dev-setup`¶

Performs complete setup

make dev-setup  # Should run dev-init, dev-build, dev-up, dev-validate

Shows setup progress

make dev-setup  # Should show each step

Provides next steps

make dev-setup  # Should show "Next steps: make dev-logs"

`make test-watch`¶

Starts file watcher

make test-watch  # Should start watching test files

Runs tests on file change

# Modify a test file and verify tests run

Handles missing watcher gracefully

# Test on system without fswatch/inotifywait

`make help`¶

Shows all commands

make help  # Should show all available targets

Shows development workflow section

make help  # Should show "Development Workflow" section

Shows command descriptions

make help  # Should show descriptions for each command

Error Handling Tests¶

Missing Dependencies¶

Docker not running

# Stop Docker Desktop, then run make dev-up
# Should show clear error message

Docker not installed

# Test on system without Docker
# Should show installation instructions

Port Conflicts¶

Backend port 8000 in use

# Start another service on port 8000
make dev-up  # Should show port conflict error

Frontend port 3000 in use

# Start another service on port 3000
make dev-up  # Should show port conflict error

File System Issues¶

No write permissions

# Make volumes directory read-only
make dev-up  # Should show permission error

Disk space full

# Simulate disk full scenario
make dev-build  # Should show disk space error

Network Issues¶

No internet connection

# Disconnect from internet
make dev-build  # Should handle network errors gracefully

Performance Tests¶

Build Times¶

Initial build time

time make dev-build  # Should complete within reasonable time

Incremental build time

make dev-build  # Second build should be faster

Startup Times¶

Service startup time

time make dev-up  # Should start within reasonable time

Validation time

time make dev-validate  # Should validate quickly

Integration Tests¶

Complete Workflow¶

Fresh start to running

make clean-all
make dev-setup
# Should result in fully working environment

Hot Reloading¶

Backend code changes

# Edit Python file in backend/
# Changes should be visible immediately

Frontend code changes

# Edit React file in webui/
# Changes should be visible immediately

CLI Integration¶

CLI commands work

poetry run python -m rag_solution.cli.main --help
poetry run python -m rag_solution.cli.main health check

Documentation Tests¶

Command Documentation¶

All commands documented

make help  # Should show all commands from docs

Examples work
```
# Test all examples from documentation
```

README Instructions¶

Quick start works
```
# Follow README quick start exactly
```
All links work
```
# Check all documentation links
```

Sign-off¶

Validated by: _________________ Date: _________________ Environment: _________________