docker-tools/test-stack/TESTING.md

DocWell Testing Guide

This document provides specific test scenarios for using the test-stack with DocWell.

Prerequisites

1. Install the test stack:

   cd test-stack
   ./setup.sh
   

2. Ensure DocWell is built:

   cd go
   go build -o docwell docwell.go
   

Test Scenarios

1. Stack Management Tests

Test: List Stacks

./docwell --stack-list

Expected: Should show test-stack with status (running/stopped)

Test: Start Stack

./docwell --stack-start test-stack

Expected: Stack starts, container runs, web interface accessible at http://localhost:8080

Test: Check Status

./docwell --stack-status test-stack

Expected: Outputs "running" or "stopped"

Test: View Logs

./docwell --stack-logs test-stack

Expected: Shows Nginx logs

Test: Restart Stack

./docwell --stack-restart test-stack

Expected: Stack restarts, service remains available

Test: Stop Stack

./docwell --stack-stop test-stack

Expected: Stack stops, container removed, port 8080 no longer accessible

2. Backup Tests

Test: Backup Single Stack

./docwell --backup-stack test-stack

Expected:

• Creates backup in configured backup directory
• Backup file: docker-<hostname>/<date>/docker-test-stack.tar.zst
• Stack restarts if it was running

Test: List Stacks for Backup

./docwell --backup-list

Expected: Lists all stacks with their status

Test: Backup All Stacks

./docwell --backup

Expected: Backs up all stacks including test-stack

3. Update Tests

Test: Check for Updates

./docwell --update-check

Expected: Shows update status for nginx:alpine image

Test: Update Single Stack

./docwell --update-stack test-stack

Expected:

• Pulls latest nginx:alpine image
• Recreates container if stack was running
• Service continues to work

Test: Update All Stacks

./docwell --update-all

Expected: Updates all stacks including test-stack

4. Cleanup Tests

Test: Cleanup Containers

# Stop the stack first
./docwell --stack-stop test-stack
./docwell --cleanup-containers

Expected: Removes stopped containers

Test: Cleanup Images

./docwell --cleanup-images

Expected: Removes unused images (may remove old nginx images)

Test: Cleanup Volumes

./docwell --cleanup-volumes

Expected: Removes unused volumes (be careful - this removes data!)

5. Migration Tests

Test: Migrate to Another Server (Clone Mode)

./docwell --migrate \
  --migrate-service test-stack \
  --migrate-source local \
  --migrate-dest user@remote-host \
  --migrate-method rsync

Expected:

• Creates backup of config and volumes
• Transfers to destination
• Starts service on destination
• Original service keeps running

Test: Migrate (Transfer Mode)

./docwell --migrate \
  --migrate-service test-stack \
  --migrate-source local \
  --migrate-dest user@remote-host \
  --migrate-method rsync \
  --migrate-transfer

Expected:

• Stops service on source
• Transfers everything
• Starts on destination
• Source service is stopped

6. Interactive Mode Tests

Test: Interactive Backup

./docwell
# Select option 1 (Backup Stacks)
# Select test-stack

Expected: Interactive menu works, backup completes

Test: Interactive Stack Manager

./docwell
# Select option 4 (Stack Manager)
# Select test-stack
# Try start/stop/restart/update/logs

Expected: All operations work through interactive menu

Verification Steps

After each test, verify:

1. Service Status:

   docker compose -f /opt/stacks/test-stack/compose.yaml ps
   

2. Web Interface:

   curl http://localhost:8080
   # Should return HTML content
   

3. Volume Exists:

   docker volume ls | grep test-stack
   

4. Backup Created:

   ls -lh /storage/backups/docker-*/$(date +%Y-%m-%d)/
   

Troubleshooting

Port Already in Use

If port 8080 is in use, edit compose.yaml:

ports:
  - "8081:80"  # Change port

Permission Denied

sudo chown -R $USER:$USER /opt/stacks/test-stack

Container Won't Start

cd /opt/stacks/test-stack
docker compose logs
docker compose up -d

Backup Fails

• Check backup directory permissions
• Ensure enough disk space
• Check logs: tail -f /var/log/docwell.log

Test Checklist

• Stack listing works
• Start/stop/restart operations work
• Status checking works
• Log viewing works
• Backup creates valid archive
• Update pulls new images
• Cleanup removes unused resources
• Migration transfers correctly
• Interactive mode works
• Web interface accessible after operations

Performance Testing

For stress testing:

1. Multiple Stacks: Create several test stacks
2. Parallel Operations: Run multiple operations simultaneously
3. Large Volumes: Add data to volumes to test transfer speeds
4. Network Testing: Test migration over slow networks

Cleanup After Testing

# Stop and remove stack
cd /opt/stacks/test-stack
docker compose down -v

# Remove directory
sudo rm -rf /opt/stacks/test-stack

# Clean up backups (optional)
rm -rf /storage/backups/docker-*/$(date +%Y-%m-%d)/docker-test-stack.tar.zst