particle-os-tools/WSL_TESTING_GUIDE.md

# Particle-OS WSL Testing Guide

This guide provides quick instructions for testing Particle-OS rollback and deployment activation functionality in WSL environments.

## 🚀 Quick Start for WSL

### Prerequisites
```bash
# Install required packages
sudo apt update
sudo apt install jq squashfs-tools

# Ensure Particle-OS tools are installed
which apt-layer.sh
which bootc-alternative.sh
which bootupd-alternative.sh
```

### Option 1: Safe Testing (No Reboot) - RECOMMENDED
```bash
# Run the root-compatible test script
./test-rollback-deployment-root.sh
```

### Option 2: Full Testing (With Reboot) - WARNING
```bash
# Only use in a disposable VM, not in WSL
# ./test-deployment-activation-reboot.sh
```

## 🔧 WSL-Specific Considerations

### Why Use the Root Version?
- WSL environments often run as root by default
- Original scripts require regular user with sudo access
- Root version removes sudo requirements for testing

### WSL Limitations
- **No real reboot support** - WSL reboots restart the entire WSL instance
- **Limited bootloader testing** - WSL doesn't use traditional bootloaders
- **Container limitations** - Some container features may not work in WSL

### What Works in WSL
- ✅ OSTree commit creation and management
- ✅ Rollback preparation (without activation)
- ✅ Live overlay functionality
- ✅ Package installation and removal
- ✅ System status and logging
- ✅ Basic rollback commands

### What Doesn't Work in WSL
- ❌ Actual deployment activation via reboot
- ❌ Bootloader integration testing
- ❌ Full system rollback testing
- ❌ BootC alternative reboot testing

## 📋 Test Results Interpretation

### Expected Results in WSL
```
=== Test Results ===
Total Tests: 10
Passed: 8-10
Failed: 0-2

Expected Warnings:
- "BootC rollback may not have deployments to rollback"
- "No pending deployment found (normal if no rollback was prepared)"
```

### What Success Looks Like
- ✅ All basic functionality tests pass
- ✅ OSTree commits created successfully
- ✅ Rollback preparation works
- ✅ Live overlay functionality works
- ✅ System remains functional after tests

### Common WSL Issues
- **Permission errors** - Use the root version script
- **Missing tools** - Install required packages
- **Network issues** - Check WSL network connectivity
- **Disk space** - Ensure sufficient space for testing

## 🧪 Manual Testing Steps

### 1. Basic Functionality Test
```bash
# Check if tools are available
which apt-layer.sh
which jq
which ostree

# Test basic commands
apt-layer.sh --help
apt-layer.sh status
```

### 2. OSTree Commit Test
```bash
# Initialize if needed
apt-layer.sh --init

# Create test commit
apt-layer.sh ostree compose install htop curl

# Check status
apt-layer.sh ostree status
apt-layer.sh ostree log
```

### 3. Rollback Preparation Test
```bash
# Create second commit
apt-layer.sh ostree compose install wget tree

# Prepare rollback to first commit
commits=($(apt-layer.sh ostree log | grep -o "ostree-[0-9]*-[0-9]*"))
apt-layer.sh ostree rollback "${commits[1]}"

# Check pending deployment
apt-layer.sh ostree status
```

### 4. Live Overlay Test
```bash
# Start live overlay
apt-layer.sh --live-overlay start

# Install package
apt-layer.sh --live-install sl

# Test rollback
apt-layer.sh --live-overlay rollback

# Stop overlay
apt-layer.sh --live-overlay stop
```

## 🔍 Troubleshooting

### Issue: "Command not found"
```bash
# Check if tools are installed
ls -la apt-layer.sh
ls -la bootc-alternative.sh

# Install if missing
./install-particle-os.sh
```

### Issue: "Permission denied"
```bash
# Use the root version script
./test-rollback-deployment-root.sh

# Or fix permissions
chmod +x *.sh
```

### Issue: "No such file or directory"
```bash
# Create required directories
sudo mkdir -p /var/lib/particle-os
sudo mkdir -p /var/log/particle-os

# Initialize apt-layer
apt-layer.sh --init
```

### Issue: "Network connectivity"
```bash
# Check WSL network
ping -c 3 8.8.8.8

# Update package lists
apt update
```

## 📊 Test Validation

### Successful Test Indicators
- [ ] All basic commands work without errors
- [ ] OSTree commits can be created
- [ ] Rollback preparation completes
- [ ] Live overlay starts and stops
- [ ] System remains functional

### Warning Signs
- [ ] Multiple command failures
- [ ] Permission errors
- [ ] Network connectivity issues
- [ ] System becomes unresponsive

## 🎯 Next Steps After WSL Testing

### If Tests Pass
1. **Document successful configuration**
2. **Test in a real VM environment**
3. **Validate with actual reboots**
4. **Create production deployment plan**

### If Tests Fail
1. **Review error logs**
2. **Check system requirements**
3. **Test in different WSL environment**
4. **Report issues with details**

## 📝 Log Analysis

### Check Test Logs
```bash
# View test log
cat /tmp/particle-os-rollback-test/test-rollback-deployment.log

# Check for errors
grep -i error /tmp/particle-os-rollback-test/test-rollback-deployment.log

# Check for warnings
grep -i warning /tmp/particle-os-rollback-test/test-rollback-deployment.log
```

### Common Log Messages
- `[SUCCESS]` - Test passed
- `[ERROR]` - Test failed
- `[WARNING]` - Potential issue (may be normal in WSL)
- `[INFO]` - Informational message

## 🔗 Related Documentation

- [Particle-OS Testing Guide](TESTING_GUIDE.md)
- [Rollback Deployment Testing Guide](ROLLBACK_DEPLOYMENT_TESTING_GUIDE.md)
- [Particle-OS Installation Guide](INSTALLATION.md)

## 📞 Support

For WSL-specific issues:
1. Check this troubleshooting guide
2. Verify WSL configuration
3. Test in a different WSL environment
4. Report issues with WSL version and configuration details