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

# 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

# Run the root-compatible test script
./test-rollback-deployment-root.sh

Option 2: Full Testing (With Reboot) - WARNING

# 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

# 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

# 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

# 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

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

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

# Use the root version script
./test-rollback-deployment-root.sh

# Or fix permissions
chmod +x *.sh

Issue: "No such file or directory"

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

# 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

# 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
• Rollback Deployment Testing Guide
• Particle-OS Installation Guide

📞 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